Enum TypeSignature 

pub enum TypeSignature {
    Variadic(Vec<DataType>),
    UserDefined,
    VariadicAny,
    Uniform(usize, Vec<DataType>),
    Exact(Vec<DataType>),
    Coercible(Vec<Coercion>),
    Comparable(usize),
    Any(usize),
    OneOf(Vec<TypeSignature>),
    ArraySignature(ArrayFunctionSignature),
    Numeric(usize),
    String(usize),
    Nullary,
}

The types of arguments for which a function has implementations.

TypeSignature DOES NOT define the types that a user query could call the function with. DataFusion will automatically coerce (cast) argument types to one of the supported function signatures, if possible.

Overview

Functions typically provide implementations for a small number of different argument [DataType]s, rather than all possible combinations. If a user calls a function with arguments that do not match any of the declared types, DataFusion will attempt to automatically coerce (add casts to) function arguments so they match the TypeSignature. See the type_coercion module for more details

Example: Numeric Functions

For example, a function like cos may only provide an implementation for [DataType::Float64]. When users call cos with a different argument type, such as cos(int_column), and type coercion automatically adds a cast such as cos(CAST int_column AS DOUBLE) during planning.

Example: Strings

There are several different string types in Arrow, such as [DataType::Utf8], [DataType::LargeUtf8], and [DataType::Utf8View].

Some functions may have specialized implementations for these types, while others may be able to handle only one of them. For example, a function that only works with [DataType::Utf8View] would have the following signature:

// Declares the function must be invoked with a single argument of type `Utf8View`.
// if a user calls the function with `Utf8` or `LargeUtf8`, DataFusion will
// automatically add a cast to `Utf8View` during planning.
let type_signature = TypeSignature::Exact(vec![DataType::Utf8View]);

Example: Timestamps

Types to match are represented using Arrow’s [DataType]. [DataType::Timestamp] has an optional variable timezone specification. To specify a function can handle a timestamp with ANY timezone, use the TIMEZONE_WILDCARD. For example:

let type_signature = TypeSignature::Exact(vec![
    // A nanosecond precision timestamp with ANY timezone
    // matches  Timestamp(Nanosecond, Some("+0:00"))
    // matches  Timestamp(Nanosecond, Some("+5:00"))
    // does not match  Timestamp(Nanosecond, None)
    DataType::Timestamp(TimeUnit::Nanosecond, Some(TIMEZONE_WILDCARD.into())),
]);

Variants

Variadic(Vec<DataType>)

One or more arguments of a common type out of a list of valid types.

For functions that take no arguments (e.g. random() see TypeSignature::Nullary).

Examples

A function such as concat is Variadic(vec![DataType::Utf8, DataType::LargeUtf8])

UserDefined

The acceptable signature and coercions rules are special for this function.

If this signature is specified, DataFusion will call ScalarUDFImpl::coerce_types to prepare argument types.

VariadicAny

One or more arguments with arbitrary types

Uniform(usize, Vec<DataType>)

One or more arguments of an arbitrary but equal type out of a list of valid types.

Examples

1. A function of one argument of f64 is Uniform(1, vec![DataType::Float64])
2. A function of one argument of f64 or f32 is Uniform(1, vec![DataType::Float32, DataType::Float64])

Exact(Vec<DataType>)

One or more arguments with exactly the specified types in order.

For functions that take no arguments (e.g. random()) use TypeSignature::Nullary.

Coercible(Vec<Coercion>)

One or more arguments belonging to the TypeSignatureClass, in order.

Coercion contains not only the desired type but also the allowed casts. For example, if you expect a function has string type, but you also allow it to be casted from binary type.

For functions that take no arguments (e.g. random()) see TypeSignature::Nullary.

Comparable(usize)

One or more arguments coercible to a single, comparable type.

Each argument will be coerced to a single type using the coercion rules described in comparison_coercion_numeric.

Examples

If the nullif(1, 2) function is called with i32 and i64 arguments the types will both be coerced to i64 before the function is invoked.

If the nullif('1', 2) function is called with Utf8 and i64 arguments the types will both be coerced to Utf8 before the function is invoked.

Note:

• For functions that take no arguments (e.g. random() see TypeSignature::Nullary).
• If all arguments have type [DataType::Null], they are coerced to Utf8

Any(usize)

One or more arguments of arbitrary types.

For functions that take no arguments (e.g. random()) use TypeSignature::Nullary.

OneOf(Vec<TypeSignature>)

Matches exactly one of a list of TypeSignatures.

Coercion is attempted to match the signatures in order, and stops after the first success, if any.

Examples

Since make_array takes 0 or more arguments with arbitrary types, its TypeSignature is OneOf(vec![Any(0), VariadicAny]).

ArraySignature(ArrayFunctionSignature)

A function that has an ArrayFunctionSignature

Numeric(usize)

One or more arguments of numeric types, coerced to a common numeric type.

See NativeType::is_numeric to know which type is considered numeric

For functions that take no arguments (e.g. random()) use TypeSignature::Nullary.

String(usize)

One or arguments of all the same string types.

The precedence of type from high to low is Utf8View, LargeUtf8 and Utf8. Null is considered as Utf8 by default Dictionary with string value type is also handled.

For example, if a function is called with (utf8, large_utf8), all arguments will be coerced to LargeUtf8

For functions that take no arguments (e.g. random() use TypeSignature::Nullary).

Nullary

No arguments

Implementations

impl TypeSignature

pub fn is_one_of(&self) -> bool

pub fn arity(&self) -> Arity

Returns the arity (expected number of arguments) for this type signature.

Returns Arity::Fixed(n) for signatures with a specific argument count, or Arity::Variable for variable-arity signatures like Variadic, VariadicAny, UserDefined.

Examples

// Exact signature has fixed arity
let sig = TypeSignature::Exact(vec![DataType::Int32, DataType::Utf8]);
assert_eq!(sig.arity(), Arity::Fixed(2));

// Variadic signature has variable arity
let sig = TypeSignature::VariadicAny;
assert_eq!(sig.arity(), Arity::Variable);

impl TypeSignature

pub fn to_string_repr(&self) -> Vec<String>

pub fn to_string_repr_with_names( &self, parameter_names: Option<&[String]>, ) -> Vec<String>

Return string representation of the function signature with parameter names.

This method is similar to Self::to_string_repr but uses parameter names instead of types when available. This is useful for generating more helpful error messages.

Arguments

• parameter_names - Optional slice of parameter names. When provided, these names will be used instead of type names in the output.

Examples

let sig = TypeSignature::Exact(vec![DataType::Int32, DataType::Utf8]);

// Without names: shows types only
assert_eq!(sig.to_string_repr_with_names(None), vec!["Int32, Utf8"]);

// With names: shows parameter names with types
assert_eq!(
    sig.to_string_repr_with_names(Some(&["id".to_string(), "name".to_string()])),
    vec!["id: Int32, name: Utf8"]
);

pub fn join_types<T>(types: &[T], delimiter: &str) -> String

where T: Display,

Helper function to join types with specified delimiter.

pub fn supports_zero_argument(&self) -> bool

Check whether 0 input argument is valid for given TypeSignature

pub fn used_to_support_zero_arguments(&self) -> bool

Returns true if the signature currently supports or used to supported 0 input arguments in a previous version of DataFusion.

pub fn get_possible_types(&self) -> Vec<Vec<DataType>>

👎Deprecated since 46.0.0: See get_example_types instead

pub fn get_example_types(&self) -> Vec<Vec<DataType>>

Return example acceptable types for this TypeSignature’

Returns a Vec<DataType> for each argument to the function

This is used for information_schema and can be used to generate documentation or error messages.

Trait Implementations

impl Clone for TypeSignature

fn clone(&self) -> TypeSignature

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TypeSignature

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Hash for TypeSignature

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TypeSignature

fn eq(&self, other: &TypeSignature) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for TypeSignature

fn partial_cmp(&self, other: &TypeSignature) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for TypeSignature

impl StructuralPartialEq for TypeSignature