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_metadata;
25pub mod arrowtypeof;
26pub mod coalesce;
27pub mod expr_ext;
28pub mod getfield;
29pub mod greatest;
30mod greatest_least_utils;
31pub mod least;
32pub mod named_struct;
33pub mod nullif;
34pub mod nvl;
35pub mod nvl2;
36pub mod overlay;
37pub mod planner;
38pub mod r#struct;
39pub mod union_extract;
40pub mod union_tag;
41pub mod version;
42
43// create UDFs
44make_udf_function!(arrow_cast::ArrowCastFunc, arrow_cast);
45make_udf_function!(nullif::NullIfFunc, nullif);
46make_udf_function!(nvl::NVLFunc, nvl);
47make_udf_function!(nvl2::NVL2Func, nvl2);
48make_udf_function!(overlay::OverlayFunc, overlay);
49make_udf_function!(arrowtypeof::ArrowTypeOfFunc, arrow_typeof);
50make_udf_function!(r#struct::StructFunc, r#struct);
51make_udf_function!(named_struct::NamedStructFunc, named_struct);
52make_udf_function!(getfield::GetFieldFunc, get_field);
53make_udf_function!(coalesce::CoalesceFunc, coalesce);
54make_udf_function!(greatest::GreatestFunc, greatest);
55make_udf_function!(least::LeastFunc, least);
56make_udf_function!(union_extract::UnionExtractFun, union_extract);
57make_udf_function!(union_tag::UnionTagFunc, union_tag);
58make_udf_function!(version::VersionFunc, version);
59make_udf_function!(arrow_metadata::ArrowMetadataFunc, arrow_metadata);
60
61pub mod expr_fn {
62    use datafusion_expr::{Expr, Literal};
63
64    export_functions!((
65        nullif,
66        "Returns NULL if value1 equals value2; otherwise it returns value1. This can be used to perform the inverse operation of the COALESCE expression",
67        arg1 arg2
68    ),(
69        arrow_cast,
70        "Returns value2 if value1 is NULL; otherwise it returns value1",
71        arg1 arg2
72    ),(
73        nvl,
74        "Returns value2 if value1 is NULL; otherwise it returns value1",
75        arg1 arg2
76    ),(
77        nvl2,
78        "Returns value2 if value1 is not NULL; otherwise, it returns value3.",
79        arg1 arg2 arg3
80    ),(
81        overlay,
82        "replace the substring of string that starts at the start'th character and extends for count characters with new substring",
83        args,
84    ),(
85        arrow_typeof,
86        "Returns the Arrow type of the input expression.",
87        arg1
88    ),(
89        arrow_metadata,
90        "Returns the metadata of the input expression",
91        args,
92    ),(
93        r#struct,
94        "Returns a struct with the given arguments",
95        args,
96    ),(
97        named_struct,
98        "Returns a struct with the given names and arguments pairs",
99        args,
100    ),(
101        coalesce,
102        "Returns `coalesce(args...)`, which evaluates to the value of the first expr which is not NULL",
103        args,
104    ),(
105        greatest,
106        "Returns `greatest(args...)`, which evaluates to the greatest value in the list of expressions or NULL if all the expressions are NULL",
107        args,
108    ),(
109        least,
110        "Returns `least(args...)`, which evaluates to the smallest value in the list of expressions or NULL if all the expressions are NULL",
111        args,
112    ),(
113        union_tag,
114        "Returns the name of the currently selected field in the union",
115        arg1
116    ));
117
118    #[doc = "Returns the value of the field with the given name from the struct"]
119    #[expect(clippy::needless_pass_by_value)]
120    pub fn get_field(arg1: Expr, arg2: impl Literal) -> Expr {
121        super::get_field().call(vec![arg1, arg2.lit()])
122    }
123
124    #[doc = "Returns the value of nested fields by traversing multiple field names"]
125    pub fn get_field_path(base: Expr, field_names: Vec<Expr>) -> Expr {
126        let mut args = vec![base];
127        args.extend(field_names);
128        super::get_field().call(args)
129    }
130
131    #[doc = "Returns the value of the field with the given name from the union when it's selected, or NULL otherwise"]
132    #[expect(clippy::needless_pass_by_value)]
133    pub fn union_extract(arg1: Expr, arg2: impl Literal) -> Expr {
134        super::union_extract().call(vec![arg1, arg2.lit()])
135    }
136}
137
138/// Returns all DataFusion functions defined in this package
139pub fn functions() -> Vec<Arc<ScalarUDF>> {
140    vec![
141        nullif(),
142        arrow_cast(),
143        arrow_metadata(),
144        nvl(),
145        nvl2(),
146        overlay(),
147        arrow_typeof(),
148        named_struct(),
149        // Note: most users invoke `get_field` indirectly via field access
150        // syntax like `my_struct_col['field_name']`, which results in a call to
151        // `get_field(my_struct_col, "field_name")`.
152        //
153        // However, it is also exposed directly for use cases such as
154        // serializing / deserializing plans with the field access desugared to
155        // calls to [`get_field`]
156        get_field(),
157        coalesce(),
158        greatest(),
159        least(),
160        union_extract(),
161        union_tag(),
162        version(),
163        r#struct(),
164    ]
165}
datafusion_functions/core/mod.rs

datafusion_functions/core/
mod.rs
