datafusion_functions/core/
mod.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! "core" DataFusion functions
19
20use datafusion_expr::ScalarUDF;
21use std::sync::Arc;
22
23pub mod arrow_cast;
24pub mod arrow_field;
25pub mod arrow_metadata;
26pub mod arrow_try_cast;
27pub mod arrowtypeof;
28pub mod cast_to_type;
29pub mod coalesce;
30pub mod expr_ext;
31pub mod getfield;
32pub mod greatest;
33mod greatest_least_utils;
34pub mod least;
35pub mod named_struct;
36pub mod nullif;
37pub mod nvl;
38pub mod nvl2;
39pub mod overlay;
40pub mod planner;
41pub mod r#struct;
42pub mod try_cast_to_type;
43pub mod union_extract;
44pub mod union_tag;
45pub mod version;
46pub mod with_metadata;
47
48// create UDFs
49make_udf_function!(arrow_cast::ArrowCastFunc, arrow_cast);
50make_udf_function!(arrow_try_cast::ArrowTryCastFunc, arrow_try_cast);
51make_udf_function!(cast_to_type::CastToTypeFunc, cast_to_type);
52make_udf_function!(try_cast_to_type::TryCastToTypeFunc, try_cast_to_type);
53make_udf_function!(nullif::NullIfFunc, nullif);
54make_udf_function!(nvl::NVLFunc, nvl);
55make_udf_function!(nvl2::NVL2Func, nvl2);
56make_udf_function!(overlay::OverlayFunc, overlay);
57make_udf_function!(arrowtypeof::ArrowTypeOfFunc, arrow_typeof);
58make_udf_function!(r#struct::StructFunc, r#struct);
59make_udf_function!(named_struct::NamedStructFunc, named_struct);
60make_udf_function!(getfield::GetFieldFunc, get_field);
61make_udf_function!(coalesce::CoalesceFunc, coalesce);
62make_udf_function!(greatest::GreatestFunc, greatest);
63make_udf_function!(least::LeastFunc, least);
64make_udf_function!(union_extract::UnionExtractFun, union_extract);
65make_udf_function!(union_tag::UnionTagFunc, union_tag);
66make_udf_function!(version::VersionFunc, version);
67make_udf_function!(arrow_metadata::ArrowMetadataFunc, arrow_metadata);
68make_udf_function!(with_metadata::WithMetadataFunc, with_metadata);
69make_udf_function!(arrow_field::ArrowFieldFunc, arrow_field);
70
71pub mod expr_fn {
72    use datafusion_expr::{Expr, Literal};
73
74    export_functions!((
75        nullif,
76        "Returns NULL if value1 equals value2; otherwise it returns value1. This can be used to perform the inverse operation of the COALESCE expression",
77        arg1 arg2
78    ),(
79        arrow_cast,
80        "Casts a value to a specific Arrow data type",
81        arg1 arg2
82    ),(
83        arrow_try_cast,
84        "Casts a value to a specific Arrow data type, returning NULL if the cast fails",
85        arg1 arg2
86    ),(
87        cast_to_type,
88        "Casts the first argument to the data type of the second argument",
89        arg1 arg2
90    ),(
91        try_cast_to_type,
92        "Casts the first argument to the data type of the second argument, returning NULL on failure",
93        arg1 arg2
94    ),(
95        nvl,
96        "Returns value2 if value1 is NULL; otherwise it returns value1",
97        arg1 arg2
98    ),(
99        nvl2,
100        "Returns value2 if value1 is not NULL; otherwise, it returns value3.",
101        arg1 arg2 arg3
102    ),(
103        overlay,
104        "replace the substring of string that starts at the start'th character and extends for count characters with new substring",
105        args,
106    ),(
107        arrow_typeof,
108        "Returns the Arrow type of the input expression.",
109        arg1
110    ),(
111        arrow_field,
112        "Returns the Arrow field info (name, data_type, nullable, metadata) of the input expression.",
113        arg1
114    ),(
115        arrow_metadata,
116        "Returns the metadata of the input expression",
117        args,
118    ),(
119        with_metadata,
120        "Attaches Arrow field metadata (key/value pairs) to the input expression",
121        args,
122    ),(
123        r#struct,
124        "Returns a struct with the given arguments",
125        args,
126    ),(
127        named_struct,
128        "Returns a struct with the given names and arguments pairs",
129        args,
130    ),(
131        coalesce,
132        "Returns `coalesce(args...)`, which evaluates to the value of the first expr which is not NULL",
133        args,
134    ),(
135        greatest,
136        "Returns `greatest(args...)`, which evaluates to the greatest value in the list of expressions or NULL if all the expressions are NULL",
137        args,
138    ),(
139        least,
140        "Returns `least(args...)`, which evaluates to the smallest value in the list of expressions or NULL if all the expressions are NULL",
141        args,
142    ),(
143        union_tag,
144        "Returns the name of the currently selected field in the union",
145        arg1
146    ));
147
148    #[doc = "Returns the value of the field with the given name from the struct"]
149    #[expect(clippy::needless_pass_by_value)]
150    pub fn get_field(arg1: Expr, arg2: impl Literal) -> Expr {
151        super::get_field().call(vec![arg1, arg2.lit()])
152    }
153
154    #[doc = "Returns the value of nested fields by traversing multiple field names"]
155    pub fn get_field_path(base: Expr, field_names: Vec<Expr>) -> Expr {
156        let mut args = vec![base];
157        args.extend(field_names);
158        super::get_field().call(args)
159    }
160
161    #[doc = "Returns the value of the field with the given name from the union when it's selected, or NULL otherwise"]
162    #[expect(clippy::needless_pass_by_value)]
163    pub fn union_extract(arg1: Expr, arg2: impl Literal) -> Expr {
164        super::union_extract().call(vec![arg1, arg2.lit()])
165    }
166}
167
168/// Returns all DataFusion functions defined in this package
169pub fn functions() -> Vec<Arc<ScalarUDF>> {
170    vec![
171        nullif(),
172        arrow_cast(),
173        arrow_field(),
174        arrow_try_cast(),
175        cast_to_type(),
176        try_cast_to_type(),
177        arrow_metadata(),
178        with_metadata(),
179        nvl(),
180        nvl2(),
181        overlay(),
182        arrow_typeof(),
183        named_struct(),
184        // Note: most users invoke `get_field` indirectly via field access
185        // syntax like `my_struct_col['field_name']`, which results in a call to
186        // `get_field(my_struct_col, "field_name")`.
187        //
188        // However, it is also exposed directly for use cases such as
189        // serializing / deserializing plans with the field access desugared to
190        // calls to [`get_field`]
191        get_field(),
192        coalesce(),
193        greatest(),
194        least(),
195        union_extract(),
196        union_tag(),
197        version(),
198        r#struct(),
199    ]
200}
datafusion_functions/core/mod.rs

datafusion_functions/core/
mod.rs
