diff --git a/datafusion/functions-nested/src/array_has.rs b/datafusion/functions-nested/src/array_has.rs index 8f8d123bf5f9..fe1d05199e80 100644 --- a/datafusion/functions-nested/src/array_has.rs +++ b/datafusion/functions-nested/src/array_has.rs @@ -25,14 +25,17 @@ use arrow_buffer::BooleanBuffer; use datafusion_common::cast::as_generic_list_array; use datafusion_common::utils::string_utils::string_array_to_vec; use datafusion_common::{exec_err, Result, ScalarValue}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use datafusion_physical_expr_common::datum::compare_with_eq; use itertools::Itertools; use crate::utils::make_scalar_function; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; // Create static instances of ScalarUDFs for each function make_udf_expr_and_func!(ArrayHas, @@ -129,6 +132,43 @@ impl ScalarUDFImpl for ArrayHas { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_has_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_has_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns true if the array contains the element.", + ) + .with_syntax_example("array_has(array, element)") + .with_sql_example( + r#"```sql +> select array_has([1, 2, 3], 2); ++-----------------------------+ +| array_has(List([1,2,3]), 2) | ++-----------------------------+ +| true | ++-----------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Scalar or Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } fn array_has_inner_for_scalar( @@ -289,6 +329,41 @@ impl ScalarUDFImpl for ArrayHasAll { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_has_all_doc()) + } +} + +fn get_array_has_all_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns true if all elements of sub-array exist in array.", + ) + .with_syntax_example("array_has_all(array, sub-array)") + .with_sql_example( + r#"```sql +> select array_has_all([1, 2, 3, 4], [2, 3]); ++--------------------------------------------+ +| array_has_all(List([1,2,3,4]), List([2,3])) | ++--------------------------------------------+ +| true | ++--------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "sub-array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } #[derive(Debug)] @@ -335,6 +410,41 @@ impl ScalarUDFImpl for ArrayHasAny { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_has_any_doc()) + } +} + +fn get_array_has_any_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns true if any elements exist in both arrays.", + ) + .with_syntax_example("array_has_any(array, sub-array)") + .with_sql_example( + r#"```sql +> select array_has_any([1, 2, 3], [3, 4]); ++------------------------------------------+ +| array_has_any(List([1,2,3]), List([3,4])) | ++------------------------------------------+ +| true | ++------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "sub-array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// Represents the type of comparison for array_has. diff --git a/datafusion/functions-nested/src/cardinality.rs b/datafusion/functions-nested/src/cardinality.rs index ea07ac381aff..b6661e0807f4 100644 --- a/datafusion/functions-nested/src/cardinality.rs +++ b/datafusion/functions-nested/src/cardinality.rs @@ -26,12 +26,13 @@ use arrow_schema::DataType::{FixedSizeList, LargeList, List, Map, UInt64}; use datafusion_common::cast::{as_large_list_array, as_list_array, as_map_array}; use datafusion_common::Result; use datafusion_common::{exec_err, plan_err}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; use datafusion_expr::{ - ArrayFunctionSignature, ColumnarValue, ScalarUDFImpl, Signature, TypeSignature, - Volatility, + ArrayFunctionSignature, ColumnarValue, Documentation, ScalarUDFImpl, Signature, + TypeSignature, Volatility, }; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( Cardinality, @@ -89,6 +90,39 @@ impl ScalarUDFImpl for Cardinality { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_cardinality_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_cardinality_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the total number of elements in the array.", + ) + .with_syntax_example("cardinality(array)") + .with_sql_example( + r#"```sql +> select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]); ++--------------------------------------+ +| cardinality(List([1,2,3,4,5,6,7,8])) | ++--------------------------------------+ +| 8 | ++--------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// Cardinality SQL function diff --git a/datafusion/functions-nested/src/concat.rs b/datafusion/functions-nested/src/concat.rs index c52118d0a5e2..1bdcf74aee2a 100644 --- a/datafusion/functions-nested/src/concat.rs +++ b/datafusion/functions-nested/src/concat.rs @@ -17,7 +17,8 @@ //! [`ScalarUDFImpl`] definitions for `array_append`, `array_prepend` and `array_concat` functions. -use std::{any::Any, cmp::Ordering, sync::Arc}; +use std::sync::{Arc, OnceLock}; +use std::{any::Any, cmp::Ordering}; use arrow::array::{Capacities, MutableArrayData}; use arrow_array::{Array, ArrayRef, GenericListArray, OffsetSizeTrait}; @@ -27,9 +28,10 @@ use datafusion_common::Result; use datafusion_common::{ cast::as_generic_list_array, exec_err, not_impl_err, plan_err, utils::list_ndims, }; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; use datafusion_expr::{ - type_coercion::binary::get_wider_type, ColumnarValue, ScalarUDFImpl, Signature, - Volatility, + type_coercion::binary::get_wider_type, ColumnarValue, Documentation, ScalarUDFImpl, + Signature, Volatility, }; use crate::utils::{align_array_dimensions, check_datatypes, make_scalar_function}; @@ -91,6 +93,43 @@ impl ScalarUDFImpl for ArrayAppend { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_append_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_append_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Appends an element to the end of an array.", + ) + .with_syntax_example("array_append(array, element)") + .with_sql_example( + r#"```sql +> select array_append([1, 2, 3], 4); ++--------------------------------------+ +| array_append(List([1,2,3]),Int64(4)) | ++--------------------------------------+ +| [1, 2, 3, 4] | ++--------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Element to append to the array.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -150,6 +189,41 @@ impl ScalarUDFImpl for ArrayPrepend { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_prepend_doc()) + } +} + +fn get_array_prepend_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Prepends an element to the beginning of an array.", + ) + .with_syntax_example("array_prepend(element, array)") + .with_sql_example( + r#"```sql +> select array_prepend(1, [2, 3, 4]); ++---------------------------------------+ +| array_prepend(Int64(1),List([2,3,4])) | ++---------------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------------+ +```"#, + ) + .with_argument( + "element", + "Element to prepend to the array.", + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -233,6 +307,41 @@ impl ScalarUDFImpl for ArrayConcat { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_concat_doc()) + } +} + +fn get_array_concat_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Concatenates arrays.", + ) + .with_syntax_example("array_concat(array[, ..., array_n])") + .with_sql_example( + r#"```sql +> select array_concat([1, 2], [3, 4], [5, 6]); ++---------------------------------------------------+ +| array_concat(List([1,2]),List([3,4]),List([5,6])) | ++---------------------------------------------------+ +| [1, 2, 3, 4, 5, 6] | ++---------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression to concatenate. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "array_n", + "Subsequent array column or literal array to concatenate.", + ) + .build() + .unwrap() + }) } /// Array_concat/Array_cat SQL function diff --git a/datafusion/functions-nested/src/dimension.rs b/datafusion/functions-nested/src/dimension.rs index d84fa0c19ee9..7df0ed2b40bd 100644 --- a/datafusion/functions-nested/src/dimension.rs +++ b/datafusion/functions-nested/src/dimension.rs @@ -29,8 +29,11 @@ use datafusion_common::{exec_err, plan_err, Result}; use crate::utils::{compute_array_dims, make_scalar_function}; use arrow_schema::DataType::{FixedSizeList, LargeList, List, UInt64}; use arrow_schema::Field; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; -use std::sync::Arc; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayDims, @@ -85,6 +88,39 @@ impl ScalarUDFImpl for ArrayDims { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_dims_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_dims_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an array of the array's dimensions.", + ) + .with_syntax_example("array_dims(array)") + .with_sql_example( + r#"```sql +> select array_dims([[1, 2, 3], [4, 5, 6]]); ++---------------------------------+ +| array_dims(List([1,2,3,4,5,6])) | ++---------------------------------+ +| [2, 3] | ++---------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -137,6 +173,41 @@ impl ScalarUDFImpl for ArrayNdims { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_ndims_doc()) + } +} + +fn get_array_ndims_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the number of dimensions of the array.", + ) + .with_syntax_example("array_ndims(array, element)") + .with_sql_example( + r#"```sql +> select array_ndims([[1, 2, 3], [4, 5, 6]]); ++----------------------------------+ +| array_ndims(List([1,2,3,4,5,6])) | ++----------------------------------+ +| 2 | ++----------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Array element.", + ) + .build() + .unwrap() + }) } /// Array_dims SQL function diff --git a/datafusion/functions-nested/src/distance.rs b/datafusion/functions-nested/src/distance.rs index fa9394c73bcb..19a22690980b 100644 --- a/datafusion/functions-nested/src/distance.rs +++ b/datafusion/functions-nested/src/distance.rs @@ -31,9 +31,12 @@ use datafusion_common::cast::{ use datafusion_common::utils::coerced_fixed_size_list_to_list; use datafusion_common::DataFusionError; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayDistance, @@ -100,6 +103,43 @@ impl ScalarUDFImpl for ArrayDistance { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_distance_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_distance_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the Euclidean distance between two input arrays of equal length.", + ) + .with_syntax_example("array_distance(array1, array2)") + .with_sql_example( + r#"```sql +> select array_distance([1, 2], [1, 4]); ++------------------------------------+ +| array_distance(List([1,2], [1,4])) | ++------------------------------------+ +| 2.0 | ++------------------------------------+ +```"#, + ) + .with_argument( + "array1", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "array2", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } pub fn array_distance_inner(args: &[ArrayRef]) -> Result { diff --git a/datafusion/functions-nested/src/empty.rs b/datafusion/functions-nested/src/empty.rs index 36c82e92081d..5d310eb23952 100644 --- a/datafusion/functions-nested/src/empty.rs +++ b/datafusion/functions-nested/src/empty.rs @@ -23,9 +23,12 @@ use arrow_schema::DataType; use arrow_schema::DataType::{Boolean, FixedSizeList, LargeList, List}; use datafusion_common::cast::as_generic_list_array; use datafusion_common::{exec_err, plan_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayEmpty, @@ -77,6 +80,39 @@ impl ScalarUDFImpl for ArrayEmpty { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_empty_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_empty_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns 1 for an empty array or 0 for a non-empty array.", + ) + .with_syntax_example("empty(array)") + .with_sql_example( + r#"```sql +> select empty([1]); ++------------------+ +| empty(List([1])) | ++------------------+ +| 0 | ++------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// Array_empty SQL function diff --git a/datafusion/functions-nested/src/except.rs b/datafusion/functions-nested/src/except.rs index 50ef20a7d416..947d3c018221 100644 --- a/datafusion/functions-nested/src/except.rs +++ b/datafusion/functions-nested/src/except.rs @@ -24,10 +24,13 @@ use arrow_array::{Array, ArrayRef, GenericListArray, OffsetSizeTrait}; use arrow_buffer::OffsetBuffer; use arrow_schema::{DataType, FieldRef}; use datafusion_common::{exec_err, internal_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; use std::collections::HashSet; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayExcept, @@ -78,6 +81,49 @@ impl ScalarUDFImpl for ArrayExcept { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_except_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_except_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an array of the elements that appear in the first array but not in the second.", + ) + .with_syntax_example("array_except(array1, array2)") + .with_sql_example( + r#"```sql +> select array_except([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +> select array_except([1, 2, 3, 4], [3, 4, 5, 6]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [3, 4, 5, 6]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +```"#, + ) + .with_argument( + "array1", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "array2", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// Array_except SQL function diff --git a/datafusion/functions-nested/src/extract.rs b/datafusion/functions-nested/src/extract.rs index 7dfc736b76d3..275095832edb 100644 --- a/datafusion/functions-nested/src/extract.rs +++ b/datafusion/functions-nested/src/extract.rs @@ -35,10 +35,13 @@ use datafusion_common::cast::as_list_array; use datafusion_common::{ exec_err, internal_datafusion_err, plan_err, DataFusionError, Result, }; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; use datafusion_expr::Expr; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use crate::utils::make_scalar_function; @@ -147,6 +150,43 @@ impl ScalarUDFImpl for ArrayElement { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_element_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_element_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Extracts the element with the index n from the array.", + ) + .with_syntax_example("array_element(array, index)") + .with_sql_example( + r#"```sql +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "index", + "Index to extract the element from the array.", + ) + .build() + .unwrap() + }) } /// array_element SQL function @@ -314,6 +354,49 @@ impl ScalarUDFImpl for ArraySlice { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_slice_doc()) + } +} + +fn get_array_slice_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns a slice of the array based on 1-indexed start and end positions.", + ) + .with_syntax_example("array_slice(array, begin, end)") + .with_sql_example( + r#"```sql +> select array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6); ++--------------------------------------------------------+ +| array_slice(List([1,2,3,4,5,6,7,8]),Int64(3),Int64(6)) | ++--------------------------------------------------------+ +| [3, 4, 5, 6] | ++--------------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "begin", + "Index of the first element. If negative, it counts backward from the end of the array.", + ) + .with_argument( + "end", + "Index of the last element. If negative, it counts backward from the end of the array.", + ) + .with_argument( + "stride", + "Stride of the array slice. The default is 1.", + ) + .build() + .unwrap() + }) } /// array_slice SQL function @@ -580,6 +663,37 @@ impl ScalarUDFImpl for ArrayPopFront { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_pop_front_doc()) + } +} + +fn get_array_pop_front_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the array without the first element.", + ) + .with_syntax_example("array_pop_front(array)") + .with_sql_example( + r#"```sql +> select array_pop_front([1, 2, 3]); ++-------------------------------+ +| array_pop_front(List([1,2,3])) | ++-------------------------------+ +| [2, 3] | ++-------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// array_pop_front SQL function @@ -655,6 +769,37 @@ impl ScalarUDFImpl for ArrayPopBack { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_pop_back_doc()) + } +} + +fn get_array_pop_back_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the array without the last element.", + ) + .with_syntax_example("array_pop_back(array)") + .with_sql_example( + r#"```sql +> select array_pop_back([1, 2, 3]); ++-------------------------------+ +| array_pop_back(List([1,2,3])) | ++-------------------------------+ +| [1, 2] | ++-------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// array_pop_back SQL function @@ -738,6 +883,37 @@ impl ScalarUDFImpl for ArrayAnyValue { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_any_value_doc()) + } +} + +fn get_array_any_value_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the first non-null element in the array.", + ) + .with_syntax_example("array_any_value(array)") + .with_sql_example( + r#"```sql +> select array_any_value([NULL, 1, 2, 3]); ++-------------------------------+ +| array_any_value(List([NULL,1,2,3])) | ++-------------------------------------+ +| 1 | ++-------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } fn array_any_value_inner(args: &[ArrayRef]) -> Result { diff --git a/datafusion/functions-nested/src/flatten.rs b/datafusion/functions-nested/src/flatten.rs index b04c35667226..4fe631517b09 100644 --- a/datafusion/functions-nested/src/flatten.rs +++ b/datafusion/functions-nested/src/flatten.rs @@ -26,9 +26,12 @@ use datafusion_common::cast::{ as_generic_list_array, as_large_list_array, as_list_array, }; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( Flatten, @@ -95,6 +98,38 @@ impl ScalarUDFImpl for Flatten { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_flatten_doc()) + } +} +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_flatten_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Converts an array of arrays to a flat array.\n\n- Applies to any depth of nested arrays\n- Does not change arrays that are already flat\n\nThe flattened array contains all the elements from all source arrays.", + ) + .with_syntax_example("flatten(array)") + .with_sql_example( + r#"```sql +> select flatten([[1, 2], [3, 4]]); ++------------------------------+ +| flatten(List([1,2], [3,4])) | ++------------------------------+ +| [1, 2, 3, 4] | ++------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// Flatten SQL function diff --git a/datafusion/functions-nested/src/length.rs b/datafusion/functions-nested/src/length.rs index 5d9ccd2901cf..3e039f286421 100644 --- a/datafusion/functions-nested/src/length.rs +++ b/datafusion/functions-nested/src/length.rs @@ -27,9 +27,12 @@ use core::any::type_name; use datafusion_common::cast::{as_generic_list_array, as_int64_array}; use datafusion_common::DataFusionError; use datafusion_common::{exec_err, plan_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayLength, @@ -81,6 +84,43 @@ impl ScalarUDFImpl for ArrayLength { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_length_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_length_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the length of the array dimension.", + ) + .with_syntax_example("array_length(array, dimension)") + .with_sql_example( + r#"```sql +> select array_length([1, 2, 3, 4, 5], 1); ++-------------------------------------------+ +| array_length(List([1,2,3,4,5]), 1) | ++-------------------------------------------+ +| 5 | ++-------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "dimension", + "Array dimension.", + ) + .build() + .unwrap() + }) } /// Array_length SQL function diff --git a/datafusion/functions-nested/src/make_array.rs b/datafusion/functions-nested/src/make_array.rs index cafa073f9191..efc14cbbe519 100644 --- a/datafusion/functions-nested/src/make_array.rs +++ b/datafusion/functions-nested/src/make_array.rs @@ -17,8 +17,9 @@ //! [`ScalarUDFImpl`] definitions for `make_array` function. +use std::any::Any; +use std::sync::{Arc, OnceLock}; use std::vec; -use std::{any::Any, sync::Arc}; use arrow::array::{ArrayData, Capacities, MutableArrayData}; use arrow_array::{ @@ -30,8 +31,11 @@ use arrow_schema::{DataType, Field}; use datafusion_common::{exec_err, internal_err}; use datafusion_common::{plan_err, utils::array_into_list_array_nullable, Result}; use datafusion_expr::binary::type_union_resolution; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; use datafusion_expr::TypeSignature; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use itertools::Itertools; use crate::utils::make_scalar_function; @@ -149,6 +153,39 @@ impl ScalarUDFImpl for MakeArray { ) } } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_make_array_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_make_array_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an array using the specified input expressions.", + ) + .with_syntax_example("make_array(expression1[, ..., expression_n])") + .with_sql_example( + r#"```sql +> select make_array(1, 2, 3, 4, 5); ++----------------------------------------------------------+ +| make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5)) | ++----------------------------------------------------------+ +| [1, 2, 3, 4, 5] | ++----------------------------------------------------------+ +```"#, + ) + .with_argument( + "expression_n", + "Expression to include in the output array. Can be a constant, column, or function, and any combination of arithmetic or string operators.", + ) + .build() + .unwrap() + }) } fn are_all_struct_and_have_same_key(data_types: &[DataType]) -> Result { diff --git a/datafusion/functions-nested/src/position.rs b/datafusion/functions-nested/src/position.rs index a48332ceb0b3..adb45141601d 100644 --- a/datafusion/functions-nested/src/position.rs +++ b/datafusion/functions-nested/src/position.rs @@ -19,9 +19,12 @@ use arrow_schema::DataType::{LargeList, List, UInt64}; use arrow_schema::{DataType, Field}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow_array::types::UInt64Type; use arrow_array::{ @@ -86,6 +89,53 @@ impl ScalarUDFImpl for ArrayPosition { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_position_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_position_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the position of the first occurrence of the specified element in the array.", + ) + .with_syntax_example("array_position(array, element)\narray_position(array, element, index)") + .with_sql_example( + r#"```sql +> select array_position([1, 2, 2, 3, 1, 4], 2); ++----------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2)) | ++----------------------------------------------+ +| 2 | ++----------------------------------------------+ +> select array_position([1, 2, 2, 3, 1, 4], 2, 3); ++----------------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2), Int64(3)) | ++----------------------------------------------------+ +| 3 | ++----------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Element to search for position in the array.", + ) + .with_argument( + "index", + "Index at which to start searching.", + ) + .build() + .unwrap() + }) } /// Array_position SQL function @@ -210,6 +260,41 @@ impl ScalarUDFImpl for ArrayPositions { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_positions_doc()) + } +} + +fn get_array_positions_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Searches for an element in the array, returns all occurrences.", + ) + .with_syntax_example("array_positions(array, element)") + .with_sql_example( + r#"```sql +> select array_positions([1, 2, 2, 3, 1, 4], 2); ++-----------------------------------------------+ +| array_positions(List([1,2,2,3,1,4]),Int64(2)) | ++-----------------------------------------------+ +| [2, 3] | ++-----------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Element to search for positions in the array.", + ) + .build() + .unwrap() + }) } /// Array_positions SQL function diff --git a/datafusion/functions-nested/src/range.rs b/datafusion/functions-nested/src/range.rs index b3d8010cb668..2346b4d5b43f 100644 --- a/datafusion/functions-nested/src/range.rs +++ b/datafusion/functions-nested/src/range.rs @@ -37,13 +37,16 @@ use datafusion_common::cast::{ use datafusion_common::{ exec_datafusion_err, exec_err, internal_err, not_impl_datafusion_err, Result, }; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use itertools::Itertools; use std::any::Any; use std::cmp::Ordering; use std::iter::from_fn; use std::str::FromStr; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( Range, @@ -133,6 +136,54 @@ impl ScalarUDFImpl for Range { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_range_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_range_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an Arrow array between start and stop with step. The range start..end contains all values with start <= x < end. It is empty if start >= end. Step cannot be 0.", + ) + .with_syntax_example("range(start, stop, step)") + .with_sql_example( + r#"```sql +> select range(2, 10, 3); ++-----------------------------------+ +| range(Int64(2),Int64(10),Int64(3))| ++-----------------------------------+ +| [2, 5, 8] | ++-----------------------------------+ + +> select range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH); ++--------------------------------------------------------------+ +| range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH) | ++--------------------------------------------------------------+ +| [1992-09-01, 1992-10-01, 1992-11-01, 1992-12-01, 1993-01-01, 1993-02-01] | ++--------------------------------------------------------------+ +```"#, + ) + .with_argument( + "start", + "Start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported.", + ) + .with_argument( + "end", + "End of the range (not included). Type must be the same as start.", + ) + .with_argument( + "step", + "Increase by step (cannot be 0). Steps less than a day are supported only for timestamp ranges.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -226,6 +277,45 @@ impl ScalarUDFImpl for GenSeries { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_generate_series_doc()) + } +} + +fn get_generate_series_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Similar to the range function, but it includes the upper bound.", + ) + .with_syntax_example("generate_series(start, stop, step)") + .with_sql_example( + r#"```sql +> select generate_series(1,3); ++------------------------------------+ +| generate_series(Int64(1),Int64(3)) | ++------------------------------------+ +| [1, 2, 3] | ++------------------------------------+ +```"#, + ) + .with_argument( + "start", + "start of the series. Ints, timestamps, dates or string types that can be coerced to Date32 are supported.", + ) + .with_argument( + "end", + "end of the series (included). Type must be the same as start.", + ) + .with_argument( + "step", + "increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges.", + ) + .build() + .unwrap() + }) } /// Generates an array of integers from start to stop with a given step. diff --git a/datafusion/functions-nested/src/remove.rs b/datafusion/functions-nested/src/remove.rs index 0b7cfc283c06..dc1ed4833c67 100644 --- a/datafusion/functions-nested/src/remove.rs +++ b/datafusion/functions-nested/src/remove.rs @@ -27,9 +27,12 @@ use arrow_buffer::OffsetBuffer; use arrow_schema::{DataType, Field}; use datafusion_common::cast::as_int64_array; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayRemove, @@ -78,6 +81,43 @@ impl ScalarUDFImpl for ArrayRemove { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_remove_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_remove_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Removes the first element from the array equal to the given value.", + ) + .with_syntax_example("array_remove(array, element)") + .with_sql_example( + r#"```sql +> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); ++----------------------------------------------+ +| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | ++----------------------------------------------+ +| [1, 2, 3, 2, 1, 4] | ++----------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Element to be removed from the array.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -127,6 +167,45 @@ impl ScalarUDFImpl for ArrayRemoveN { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_remove_n_doc()) + } +} + +fn get_array_remove_n_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Removes the first `max` elements from the array equal to the given value.", + ) + .with_syntax_example("array_remove_n(array, element, max)") + .with_sql_example( + r#"```sql +> select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2); ++---------------------------------------------------------+ +| array_remove_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(2)) | ++---------------------------------------------------------+ +| [1, 3, 2, 1, 4] | ++---------------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Element to be removed from the array.", + ) + .with_argument( + "max", + "Number of first occurrences to remove.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -176,6 +255,41 @@ impl ScalarUDFImpl for ArrayRemoveAll { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_remove_all_doc()) + } +} + +fn get_array_remove_all_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Removes all elements from the array equal to the given value.", + ) + .with_syntax_example("array_remove_all(array, element)") + .with_sql_example( + r#"```sql +> select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2); ++--------------------------------------------------+ +| array_remove_all(List([1,2,2,3,2,1,4]),Int64(2)) | ++--------------------------------------------------+ +| [1, 3, 1, 4] | ++--------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "element", + "Element to be removed from the array.", + ) + .build() + .unwrap() + }) } /// Array_remove SQL function diff --git a/datafusion/functions-nested/src/repeat.rs b/datafusion/functions-nested/src/repeat.rs index 7ed913da3f2a..55584c143a54 100644 --- a/datafusion/functions-nested/src/repeat.rs +++ b/datafusion/functions-nested/src/repeat.rs @@ -29,9 +29,12 @@ use arrow_schema::DataType::{LargeList, List}; use arrow_schema::{DataType, Field}; use datafusion_common::cast::{as_int64_array, as_large_list_array, as_list_array}; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayRepeat, @@ -83,6 +86,49 @@ impl ScalarUDFImpl for ArrayRepeat { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_repeat_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_repeat_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an array containing element `count` times.", + ) + .with_syntax_example("array_repeat(element, count)") + .with_sql_example( + r#"```sql +> select array_repeat(1, 3); ++---------------------------------+ +| array_repeat(Int64(1),Int64(3)) | ++---------------------------------+ +| [1, 1, 1] | ++---------------------------------+ +> select array_repeat([1, 2], 2); ++------------------------------------+ +| array_repeat(List([1,2]),Int64(2)) | ++------------------------------------+ +| [[1, 2], [1, 2]] | ++------------------------------------+ +```"#, + ) + .with_argument( + "element", + "Element expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "count", + "Value of how many times to repeat the element.", + ) + .build() + .unwrap() + }) } /// Array_repeat SQL function diff --git a/datafusion/functions-nested/src/replace.rs b/datafusion/functions-nested/src/replace.rs index 46a2e078aa4c..1d0a1d1f2815 100644 --- a/datafusion/functions-nested/src/replace.rs +++ b/datafusion/functions-nested/src/replace.rs @@ -27,13 +27,16 @@ use arrow_buffer::{BooleanBufferBuilder, NullBuffer, OffsetBuffer}; use arrow_schema::Field; use datafusion_common::cast::as_int64_array; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use crate::utils::compare_element_to_list; use crate::utils::make_scalar_function; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; // Create static instances of ScalarUDFs for each function make_udf_expr_and_func!(ArrayReplace, @@ -94,6 +97,47 @@ impl ScalarUDFImpl for ArrayReplace { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_replace_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_replace_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Replaces the first occurrence of the specified element with another specified element.", + ) + .with_syntax_example("array_replace(array, from, to)") + .with_sql_example( + r#"```sql +> select array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5); ++--------------------------------------------------------+ +| array_replace(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | ++--------------------------------------------------------+ +| [1, 5, 2, 3, 2, 1, 4] | ++--------------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "from", + "Initial element.", + ) + .with_argument( + "to", + "Final element.", + ) + .build() + .unwrap() + }) } #[derive(Debug)] @@ -135,6 +179,49 @@ impl ScalarUDFImpl for ArrayReplaceN { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_replace_n_doc()) + } +} + +fn get_array_replace_n_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Replaces the first `max` occurrences of the specified element with another specified element.", + ) + .with_syntax_example("array_replace_n(array, from, to, max)") + .with_sql_example( + r#"```sql +> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); ++-------------------------------------------------------------------+ +| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | ++-------------------------------------------------------------------+ +| [1, 5, 5, 3, 2, 1, 4] | ++-------------------------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "from", + "Initial element.", + ) + .with_argument( + "to", + "Final element.", + ) + .with_argument( + "max", + "Number of first occurrences to replace.", + ) + .build() + .unwrap() + }) } #[derive(Debug)] @@ -176,6 +263,45 @@ impl ScalarUDFImpl for ArrayReplaceAll { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_replace_all_doc()) + } +} + +fn get_array_replace_all_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Replaces all occurrences of the specified element with another specified element.", + ) + .with_syntax_example("array_replace_all(array, from, to)") + .with_sql_example( + r#"```sql +> select array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5); ++------------------------------------------------------------+ +| array_replace_all(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | ++------------------------------------------------------------+ +| [1, 5, 5, 3, 5, 1, 4] | ++------------------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "from", + "Initial element.", + ) + .with_argument( + "to", + "Final element.", + ) + .build() + .unwrap() + }) } /// For each element of `list_array[i]`, replaces up to `arr_n[i]` occurrences diff --git a/datafusion/functions-nested/src/resize.rs b/datafusion/functions-nested/src/resize.rs index 83c545a26eb2..294076a52b52 100644 --- a/datafusion/functions-nested/src/resize.rs +++ b/datafusion/functions-nested/src/resize.rs @@ -25,9 +25,12 @@ use arrow_schema::DataType::{FixedSizeList, LargeList, List}; use arrow_schema::{DataType, FieldRef}; use datafusion_common::cast::{as_int64_array, as_large_list_array, as_list_array}; use datafusion_common::{exec_err, internal_datafusion_err, Result, ScalarValue}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayResize, @@ -82,6 +85,47 @@ impl ScalarUDFImpl for ArrayResize { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_resize_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_resize_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set.", + ) + .with_syntax_example("array_resize(array, size, value)") + .with_sql_example( + r#"```sql +> select array_resize([1, 2, 3], 5, 0); ++-------------------------------------+ +| array_resize(List([1,2,3],5,0)) | ++-------------------------------------+ +| [1, 2, 3, 0, 0] | ++-------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "size", + "New size of given array.", + ) + .with_argument( + "value", + "Defines new elements' value or empty if value is not set.", + ) + .build() + .unwrap() + }) } /// array_resize SQL function diff --git a/datafusion/functions-nested/src/reverse.rs b/datafusion/functions-nested/src/reverse.rs index 581caf5daf2b..1ecf7f848468 100644 --- a/datafusion/functions-nested/src/reverse.rs +++ b/datafusion/functions-nested/src/reverse.rs @@ -25,9 +25,12 @@ use arrow_schema::DataType::{LargeList, List, Null}; use arrow_schema::{DataType, FieldRef}; use datafusion_common::cast::{as_large_list_array, as_list_array}; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArrayReverse, @@ -76,6 +79,39 @@ impl ScalarUDFImpl for ArrayReverse { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_reverse_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_reverse_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns the array with the order of the elements reversed.", + ) + .with_syntax_example("array_reverse(array)") + .with_sql_example( + r#"```sql +> select array_reverse([1, 2, 3, 4]); ++------------------------------------------------------------+ +| array_reverse(List([1, 2, 3, 4])) | ++------------------------------------------------------------+ +| [4, 3, 2, 1] | ++------------------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// array_reverse SQL function diff --git a/datafusion/functions-nested/src/set_ops.rs b/datafusion/functions-nested/src/set_ops.rs index 1de9c264ddc2..ce8d248319fe 100644 --- a/datafusion/functions-nested/src/set_ops.rs +++ b/datafusion/functions-nested/src/set_ops.rs @@ -27,12 +27,15 @@ use arrow::row::{RowConverter, SortField}; use arrow_schema::DataType::{FixedSizeList, LargeList, List, Null}; use datafusion_common::cast::{as_large_list_array, as_list_array}; use datafusion_common::{exec_err, internal_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use itertools::Itertools; use std::any::Any; use std::collections::HashSet; use std::fmt::{Display, Formatter}; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; // Create static instances of ScalarUDFs for each function make_udf_expr_and_func!( @@ -102,6 +105,49 @@ impl ScalarUDFImpl for ArrayUnion { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_union_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_union_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an array of elements that are present in both arrays (all elements from both arrays) with out duplicates.", + ) + .with_syntax_example("array_union(array1, array2)") + .with_sql_example( + r#"```sql +> select array_union([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_union([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2, 3, 4, 5, 6] | ++----------------------------------------------------+ +> select array_union([1, 2, 3, 4], [5, 6, 7, 8]); ++----------------------------------------------------+ +| array_union([1, 2, 3, 4], [5, 6, 7, 8]); | ++----------------------------------------------------+ +| [1, 2, 3, 4, 5, 6, 7, 8] | ++----------------------------------------------------+ +```"#, + ) + .with_argument( + "array1", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "array2", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } #[derive(Debug)] @@ -147,6 +193,47 @@ impl ScalarUDFImpl for ArrayIntersect { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_intersect_doc()) + } +} + +fn get_array_intersect_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns an array of elements in the intersection of array1 and array2.", + ) + .with_syntax_example("array_intersect(array1, array2)") + .with_sql_example( + r#"```sql +> select array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [3, 4] | ++----------------------------------------------------+ +> select array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); ++----------------------------------------------------+ +| array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); | ++----------------------------------------------------+ +| [] | ++----------------------------------------------------+ +```"#, + ) + .with_argument( + "array1", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "array2", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } #[derive(Debug)] @@ -202,6 +289,37 @@ impl ScalarUDFImpl for ArrayDistinct { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_distinct_doc()) + } +} + +fn get_array_distinct_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Returns distinct values from the array after removing duplicates.", + ) + .with_syntax_example("array_distinct(array)") + .with_sql_example( + r#"```sql +> select array_distinct([1, 3, 2, 3, 1, 2, 4]); ++---------------------------------+ +| array_distinct(List([1,2,3,4])) | ++---------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .build() + .unwrap() + }) } /// array_distinct SQL function diff --git a/datafusion/functions-nested/src/sort.rs b/datafusion/functions-nested/src/sort.rs index 9c1ae507636c..b29c187f0679 100644 --- a/datafusion/functions-nested/src/sort.rs +++ b/datafusion/functions-nested/src/sort.rs @@ -25,9 +25,12 @@ use arrow_schema::DataType::{FixedSizeList, LargeList, List}; use arrow_schema::{DataType, Field, SortOptions}; use datafusion_common::cast::{as_list_array, as_string_array}; use datafusion_common::{exec_err, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; make_udf_expr_and_func!( ArraySort, @@ -90,6 +93,47 @@ impl ScalarUDFImpl for ArraySort { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_sort_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_sort_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Sort array.", + ) + .with_syntax_example("array_sort(array, desc, nulls_first)") + .with_sql_example( + r#"```sql +> select array_sort([3, 1, 2]); ++-----------------------------+ +| array_sort(List([3,1,2])) | ++-----------------------------+ +| [1, 2, 3] | ++-----------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "desc", + "Whether to sort in descending order(`ASC` or `DESC`).", + ) + .with_argument( + "nulls_first", + "Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`).", + ) + .build() + .unwrap() + }) } /// Array_sort SQL function diff --git a/datafusion/functions-nested/src/string.rs b/datafusion/functions-nested/src/string.rs index 2dc0a55e6951..30f3845215fc 100644 --- a/datafusion/functions-nested/src/string.rs +++ b/datafusion/functions-nested/src/string.rs @@ -39,8 +39,11 @@ use datafusion_common::cast::{ as_generic_string_array, as_large_list_array, as_list_array, as_string_array, }; use datafusion_common::exec_err; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; -use std::sync::Arc; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; +use std::sync::{Arc, OnceLock}; macro_rules! to_string { ($ARG:expr, $ARRAY:expr, $DELIMITER:expr, $NULL_STRING:expr, $WITH_NULL_STRING:expr, $ARRAY_TYPE:ident) => {{ @@ -159,6 +162,43 @@ impl ScalarUDFImpl for ArrayToString { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_array_to_string_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_array_to_string_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Converts each element to its text representation.", + ) + .with_syntax_example("array_to_string(array, delimiter)") + .with_sql_example( + r#"```sql +> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); ++----------------------------------------------------+ +| array_to_string(List([1,2,3,4,5,6,7,8]),Utf8(",")) | ++----------------------------------------------------+ +| 1,2,3,4,5,6,7,8 | ++----------------------------------------------------+ +```"#, + ) + .with_argument( + "array", + "Array expression. Can be a constant, column, or function, and any combination of array operators.", + ) + .with_argument( + "delimiter", + "Array element separator.", + ) + .build() + .unwrap() + }) } make_udf_expr_and_func!( @@ -228,6 +268,51 @@ impl ScalarUDFImpl for StringToArray { fn aliases(&self) -> &[String] { &self.aliases } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_string_to_array_doc()) + } +} + +fn get_string_to_array_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_ARRAY) + .with_description( + "Splits a string into an array of substrings based on a delimiter. Any substrings matching the optional `null_str` argument are replaced with NULL.", + ) + .with_syntax_example("string_to_array(str, delimiter[, null_str])") + .with_sql_example( + r#"```sql +> select string_to_array('abc##def', '##'); ++-----------------------------------+ +| string_to_array(Utf8('abc##def')) | ++-----------------------------------+ +| ['abc', 'def'] | ++-----------------------------------+ +> select string_to_array('abc def', ' ', 'def'); ++---------------------------------------------+ +| string_to_array(Utf8('abc def'), Utf8(' '), Utf8('def')) | ++---------------------------------------------+ +| ['abc', NULL] | ++---------------------------------------------+ +```"#, + ) + .with_argument( + "str", + "String expression to split.", + ) + .with_argument( + "delimiter", + "Delimiter string to split on.", + ) + .with_argument( + "null_str", + "Substring values to be replaced with `NULL`.", + ) + .build() + .unwrap() + }) } /// Array_to_string SQL function diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index c5995bab3d9a..d1f816898d93 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -625,1416 +625,7 @@ to_unixtime(expression[, ..., format_n]) ## Array Functions -- [array_any_value](#array_any_value) -- [array_append](#array_append) -- [array_sort](#array_sort) -- [array_cat](#array_cat) -- [array_concat](#array_concat) -- [array_contains](#array_contains) -- [array_dims](#array_dims) -- [array_distance](#array_distance) -- [array_distinct](#array_distinct) -- [array_has](#array_has) -- [array_has_all](#array_has_all) -- [array_has_any](#array_has_any) -- [array_element](#array_element) -- [array_empty](#array_empty) -- [array_except](#array_except) -- [array_extract](#array_extract) -- [array_fill](#array_fill) -- [array_indexof](#array_indexof) -- [array_intersect](#array_intersect) -- [array_join](#array_join) -- [array_length](#array_length) -- [array_ndims](#array_ndims) -- [array_prepend](#array_prepend) -- [array_pop_front](#array_pop_front) -- [array_pop_back](#array_pop_back) -- [array_position](#array_position) -- [array_positions](#array_positions) -- [array_push_back](#array_push_back) -- [array_push_front](#array_push_front) -- [array_repeat](#array_repeat) -- [array_resize](#array_resize) -- [array_remove](#array_remove) -- [array_remove_n](#array_remove_n) -- [array_remove_all](#array_remove_all) -- [array_replace](#array_replace) -- [array_replace_n](#array_replace_n) -- [array_replace_all](#array_replace_all) -- [array_reverse](#array_reverse) -- [array_slice](#array_slice) -- [array_to_string](#array_to_string) -- [array_union](#array_union) -- [cardinality](#cardinality) -- [empty](#empty) -- [flatten](#flatten) -- [generate_series](#generate_series) -- [list_any_value](#list_any_value) -- [list_append](#list_append) -- [list_sort](#list_sort) -- [list_cat](#list_cat) -- [list_concat](#list_concat) -- [list_dims](#list_dims) -- [list_distance](#list_distance) -- [list_distinct](#list_distinct) -- [list_element](#list_element) -- [list_except](#list_except) -- [list_extract](#list_extract) -- [list_has](#list_has) -- [list_has_all](#list_has_all) -- [list_has_any](#list_has_any) -- [list_indexof](#list_indexof) -- [list_intersect](#list_intersect) -- [list_join](#list_join) -- [list_length](#list_length) -- [list_ndims](#list_ndims) -- [list_prepend](#list_prepend) -- [list_pop_back](#list_pop_back) -- [list_pop_front](#list_pop_front) -- [list_position](#list_position) -- [list_positions](#list_positions) -- [list_push_back](#list_push_back) -- [list_push_front](#list_push_front) -- [list_repeat](#list_repeat) -- [list_resize](#list_resize) -- [list_remove](#list_remove) -- [list_remove_n](#list_remove_n) -- [list_remove_all](#list_remove_all) -- [list_replace](#list_replace) -- [list_replace_n](#list_replace_n) -- [list_replace_all](#list_replace_all) -- [list_slice](#list_slice) -- [list_to_string](#list_to_string) -- [list_union](#list_union) -- [make_array](#make_array) -- [make_list](#make_list) -- [string_to_array](#string_to_array) -- [string_to_list](#string_to_list) -- [trim_array](#trim_array) - [unnest](#unnest) -- [range](#range) - -### `array_any_value` - -Returns the first non-null element in the array. - -``` -array_any_value(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_any_value([NULL, 1, 2, 3]); -+--------------------------------------------------------------+ -| array_any_value(List([NULL,1,2,3])) | -+--------------------------------------------------------------+ -| 1 | -+--------------------------------------------------------------+ -``` - -### `array_append` - -Appends an element to the end of an array. - -``` -array_append(array, element) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to append to the array. - -#### Example - -``` -> select array_append([1, 2, 3], 4); -+--------------------------------------+ -| array_append(List([1,2,3]),Int64(4)) | -+--------------------------------------+ -| [1, 2, 3, 4] | -+--------------------------------------+ -``` - -#### Aliases - -- array_push_back -- list_append -- list_push_back - -### `array_sort` - -Sort array. - -``` -array_sort(array, desc, nulls_first) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **desc**: Whether to sort in descending order(`ASC` or `DESC`). -- **nulls_first**: Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`). - -#### Example - -``` -> select array_sort([3, 1, 2]); -+-----------------------------+ -| array_sort(List([3,1,2])) | -+-----------------------------+ -| [1, 2, 3] | -+-----------------------------+ -``` - -#### Aliases - -- list_sort - -### `array_resize` - -Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set. - -``` -array_resize(array, size, value) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **size**: New size of given array. -- **value**: Defines new elements' value or empty if value is not set. - -#### Example - -``` -> select array_resize([1, 2, 3], 5, 0); -+-------------------------------------+ -| array_resize(List([1,2,3],5,0)) | -+-------------------------------------+ -| [1, 2, 3, 0, 0] | -+-------------------------------------+ -``` - -#### Aliases - -- list_resize - -### `array_cat` - -_Alias of [array_concat](#array_concat)._ - -### `array_concat` - -Concatenates arrays. - -``` -array_concat(array[, ..., array_n]) -``` - -#### Arguments - -- **array**: Array expression to concatenate. - Can be a constant, column, or function, and any combination of array operators. -- **array_n**: Subsequent array column or literal array to concatenate. - -#### Example - -``` -> select array_concat([1, 2], [3, 4], [5, 6]); -+---------------------------------------------------+ -| array_concat(List([1,2]),List([3,4]),List([5,6])) | -+---------------------------------------------------+ -| [1, 2, 3, 4, 5, 6] | -+---------------------------------------------------+ -``` - -#### Aliases - -- array_cat -- list_cat -- list_concat - -### `array_contains` - -_Alias of [array_has](#array_has)._ - -### `array_has` - -Returns true if the array contains the element - -``` -array_has(array, element) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Scalar or Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Aliases - -- list_has - -### `array_has_all` - -Returns true if all elements of sub-array exist in array - -``` -array_has_all(array, sub-array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **sub-array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Aliases - -- list_has_all - -### `array_has_any` - -Returns true if any elements exist in both arrays - -``` -array_has_any(array, sub-array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **sub-array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Aliases - -- list_has_any - -### `array_dims` - -Returns an array of the array's dimensions. - -``` -array_dims(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_dims([[1, 2, 3], [4, 5, 6]]); -+---------------------------------+ -| array_dims(List([1,2,3,4,5,6])) | -+---------------------------------+ -| [2, 3] | -+---------------------------------+ -``` - -#### Aliases - -- list_dims - -### `array_distance` - -Returns the Euclidean distance between two input arrays of equal length. - -``` -array_distance(array1, array2) -``` - -#### Arguments - -- **array1**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **array2**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_distance([1, 2], [1, 4]); -+------------------------------------+ -| array_distance(List([1,2], [1,4])) | -+------------------------------------+ -| 2.0 | -+------------------------------------+ -``` - -#### Aliases - -- list_distance - -### `array_distinct` - -Returns distinct values from the array after removing duplicates. - -``` -array_distinct(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_distinct([1, 3, 2, 3, 1, 2, 4]); -+---------------------------------+ -| array_distinct(List([1,2,3,4])) | -+---------------------------------+ -| [1, 2, 3, 4] | -+---------------------------------+ -``` - -#### Aliases - -- list_distinct - -### `array_element` - -Extracts the element with the index n from the array. - -``` -array_element(array, index) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **index**: Index to extract the element from the array. - -#### Example - -``` -> select array_element([1, 2, 3, 4], 3); -+-----------------------------------------+ -| array_element(List([1,2,3,4]),Int64(3)) | -+-----------------------------------------+ -| 3 | -+-----------------------------------------+ -``` - -#### Aliases - -- array_extract -- list_element -- list_extract - -### `array_extract` - -_Alias of [array_element](#array_element)._ - -### `array_fill` - -Returns an array filled with copies of the given value. - -DEPRECATED: use `array_repeat` instead! - -``` -array_fill(element, array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to copy to the array. - -### `flatten` - -Converts an array of arrays to a flat array - -- Applies to any depth of nested arrays -- Does not change arrays that are already flat - -The flattened array contains all the elements from all source arrays. - -#### Arguments - -- **array**: Array expression - Can be a constant, column, or function, and any combination of array operators. - -``` -flatten(array) -``` - -### `array_indexof` - -_Alias of [array_position](#array_position)._ - -### `array_intersect` - -Returns an array of elements in the intersection of array1 and array2. - -``` -array_intersect(array1, array2) -``` - -#### Arguments - -- **array1**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **array2**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); -+----------------------------------------------------+ -| array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); | -+----------------------------------------------------+ -| [3, 4] | -+----------------------------------------------------+ -> select array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); -+----------------------------------------------------+ -| array_intersect([1, 2, 3, 4], [5, 6, 7, 8]); | -+----------------------------------------------------+ -| [] | -+----------------------------------------------------+ -``` - ---- - -#### Aliases - -- list_intersect - -### `array_join` - -_Alias of [array_to_string](#array_to_string)._ - -### `array_length` - -Returns the length of the array dimension. - -``` -array_length(array, dimension) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **dimension**: Array dimension. - -#### Example - -``` -> select array_length([1, 2, 3, 4, 5]); -+---------------------------------+ -| array_length(List([1,2,3,4,5])) | -+---------------------------------+ -| 5 | -+---------------------------------+ -``` - -#### Aliases - -- list_length - -### `array_ndims` - -Returns the number of dimensions of the array. - -``` -array_ndims(array, element) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_ndims([[1, 2, 3], [4, 5, 6]]); -+----------------------------------+ -| array_ndims(List([1,2,3,4,5,6])) | -+----------------------------------+ -| 2 | -+----------------------------------+ -``` - -#### Aliases - -- list_ndims - -### `array_prepend` - -Prepends an element to the beginning of an array. - -``` -array_prepend(element, array) -``` - -#### Arguments - -- **element**: Element to prepend to the array. -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_prepend(1, [2, 3, 4]); -+---------------------------------------+ -| array_prepend(Int64(1),List([2,3,4])) | -+---------------------------------------+ -| [1, 2, 3, 4] | -+---------------------------------------+ -``` - -#### Aliases - -- array_push_front -- list_prepend -- list_push_front - -### `array_pop_front` - -Returns the array without the first element. - -``` -array_pop_front(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_pop_front([1, 2, 3]); -+-------------------------------+ -| array_pop_front(List([1,2,3])) | -+-------------------------------+ -| [2, 3] | -+-------------------------------+ -``` - -#### Aliases - -- list_pop_front - -### `array_pop_back` - -Returns the array without the last element. - -``` -array_pop_back(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_pop_back([1, 2, 3]); -+-------------------------------+ -| array_pop_back(List([1,2,3])) | -+-------------------------------+ -| [1, 2] | -+-------------------------------+ -``` - -#### Aliases - -- list_pop_back - -### `array_position` - -Returns the position of the first occurrence of the specified element in the array. - -``` -array_position(array, element) -array_position(array, element, index) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to search for position in the array. -- **index**: Index at which to start searching. - -#### Example - -``` -> select array_position([1, 2, 2, 3, 1, 4], 2); -+----------------------------------------------+ -| array_position(List([1,2,2,3,1,4]),Int64(2)) | -+----------------------------------------------+ -| 2 | -+----------------------------------------------+ -``` - -#### Aliases - -- array_indexof -- list_indexof -- list_position - -### `array_positions` - -Searches for an element in the array, returns all occurrences. - -``` -array_positions(array, element) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to search for positions in the array. - -#### Example - -``` -> select array_positions([1, 2, 2, 3, 1, 4], 2); -+-----------------------------------------------+ -| array_positions(List([1,2,2,3,1,4]),Int64(2)) | -+-----------------------------------------------+ -| [2, 3] | -+-----------------------------------------------+ -``` - -#### Aliases - -- list_positions - -### `array_push_back` - -_Alias of [array_append](#array_append)._ - -### `array_push_front` - -_Alias of [array_prepend](#array_prepend)._ - -### `array_repeat` - -Returns an array containing element `count` times. - -``` -array_repeat(element, count) -``` - -#### Arguments - -- **element**: Element expression. - Can be a constant, column, or function, and any combination of array operators. -- **count**: Value of how many times to repeat the element. - -#### Example - -``` -> select array_repeat(1, 3); -+---------------------------------+ -| array_repeat(Int64(1),Int64(3)) | -+---------------------------------+ -| [1, 1, 1] | -+---------------------------------+ -``` - -``` -> select array_repeat([1, 2], 2); -+------------------------------------+ -| array_repeat(List([1,2]),Int64(2)) | -+------------------------------------+ -| [[1, 2], [1, 2]] | -+------------------------------------+ -``` - -#### Aliases - -- list_repeat - -### `array_remove` - -Removes the first element from the array equal to the given value. - -``` -array_remove(array, element) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to be removed from the array. - -#### Example - -``` -> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); -+----------------------------------------------+ -| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | -+----------------------------------------------+ -| [1, 2, 3, 2, 1, 4] | -+----------------------------------------------+ -``` - -#### Aliases - -- list_remove - -### `array_remove_n` - -Removes the first `max` elements from the array equal to the given value. - -``` -array_remove_n(array, element, max) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to be removed from the array. -- **max**: Number of first occurrences to remove. - -#### Example - -``` -> select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2); -+---------------------------------------------------------+ -| array_remove_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(2)) | -+---------------------------------------------------------+ -| [1, 3, 2, 1, 4] | -+---------------------------------------------------------+ -``` - -#### Aliases - -- list_remove_n - -### `array_remove_all` - -Removes all elements from the array equal to the given value. - -``` -array_remove_all(array, element) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **element**: Element to be removed from the array. - -#### Example - -``` -> select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2); -+--------------------------------------------------+ -| array_remove_all(List([1,2,2,3,2,1,4]),Int64(2)) | -+--------------------------------------------------+ -| [1, 3, 1, 4] | -+--------------------------------------------------+ -``` - -#### Aliases - -- list_remove_all - -### `array_replace` - -Replaces the first occurrence of the specified element with another specified element. - -``` -array_replace(array, from, to) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **from**: Initial element. -- **to**: Final element. - -#### Example - -``` -> select array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5); -+--------------------------------------------------------+ -| array_replace(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | -+--------------------------------------------------------+ -| [1, 5, 2, 3, 2, 1, 4] | -+--------------------------------------------------------+ -``` - -#### Aliases - -- list_replace - -### `array_replace_n` - -Replaces the first `max` occurrences of the specified element with another specified element. - -``` -array_replace_n(array, from, to, max) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **from**: Initial element. -- **to**: Final element. -- **max**: Number of first occurrences to replace. - -#### Example - -``` -> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); -+-------------------------------------------------------------------+ -| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | -+-------------------------------------------------------------------+ -| [1, 5, 5, 3, 2, 1, 4] | -+-------------------------------------------------------------------+ -``` - -#### Aliases - -- list_replace_n - -### `array_replace_all` - -Replaces all occurrences of the specified element with another specified element. - -``` -array_replace_all(array, from, to) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **from**: Initial element. -- **to**: Final element. - -#### Example - -``` -> select array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5); -+------------------------------------------------------------+ -| array_replace_all(List([1,2,2,3,2,1,4]),Int64(2),Int64(5)) | -+------------------------------------------------------------+ -| [1, 5, 5, 3, 5, 1, 4] | -+------------------------------------------------------------+ -``` - -#### Aliases - -- list_replace_all - -### `array_reverse` - -Returns the array with the order of the elements reversed. - -``` -array_reverse(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_reverse([1, 2, 3, 4]); -+------------------------------------------------------------+ -| array_reverse(List([1, 2, 3, 4])) | -+------------------------------------------------------------+ -| [4, 3, 2, 1] | -+------------------------------------------------------------+ -``` - -#### Aliases - -- list_reverse - -### `array_slice` - -Returns a slice of the array based on 1-indexed start and end positions. - -``` -array_slice(array, begin, end) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **begin**: Index of the first element. - If negative, it counts backward from the end of the array. -- **end**: Index of the last element. - If negative, it counts backward from the end of the array. -- **stride**: Stride of the array slice. The default is 1. - -#### Example - -``` -> select array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6); -+--------------------------------------------------------+ -| array_slice(List([1,2,3,4,5,6,7,8]),Int64(3),Int64(6)) | -+--------------------------------------------------------+ -| [3, 4, 5, 6] | -+--------------------------------------------------------+ -``` - -#### Aliases - -- list_slice - -### `array_to_string` - -Converts each element to its text representation. - -``` -array_to_string(array, delimiter) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **delimiter**: Array element separator. - -#### Example - -``` -> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); -+----------------------------------------------------+ -| array_to_string(List([1,2,3,4,5,6,7,8]),Utf8(",")) | -+----------------------------------------------------+ -| 1,2,3,4,5,6,7,8 | -+----------------------------------------------------+ -``` - -#### Aliases - -- array_join -- list_join -- list_to_string - -### `array_union` - -Returns an array of elements that are present in both arrays (all elements from both arrays) with out duplicates. - -``` -array_union(array1, array2) -``` - -#### Arguments - -- **array1**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **array2**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_union([1, 2, 3, 4], [5, 6, 3, 4]); -+----------------------------------------------------+ -| array_union([1, 2, 3, 4], [5, 6, 3, 4]); | -+----------------------------------------------------+ -| [1, 2, 3, 4, 5, 6] | -+----------------------------------------------------+ -> select array_union([1, 2, 3, 4], [5, 6, 7, 8]); -+----------------------------------------------------+ -| array_union([1, 2, 3, 4], [5, 6, 7, 8]); | -+----------------------------------------------------+ -| [1, 2, 3, 4, 5, 6, 7, 8] | -+----------------------------------------------------+ -``` - ---- - -#### Aliases - -- list_union - -### `array_except` - -Returns an array of the elements that appear in the first array but not in the second. - -``` -array_except(array1, array2) -``` - -#### Arguments - -- **array1**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **array2**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select array_except([1, 2, 3, 4], [5, 6, 3, 4]); -+----------------------------------------------------+ -| array_except([1, 2, 3, 4], [5, 6, 3, 4]); | -+----------------------------------------------------+ -| [1, 2] | -+----------------------------------------------------+ -> select array_except([1, 2, 3, 4], [3, 4, 5, 6]); -+----------------------------------------------------+ -| array_except([1, 2, 3, 4], [3, 4, 5, 6]); | -+----------------------------------------------------+ -| [1, 2] | -+----------------------------------------------------+ -``` - ---- - -#### Aliases - -- list_except - -### `cardinality` - -Returns the total number of elements in the array. - -``` -cardinality(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]); -+--------------------------------------+ -| cardinality(List([1,2,3,4,5,6,7,8])) | -+--------------------------------------+ -| 8 | -+--------------------------------------+ -``` - -### `empty` - -Returns 1 for an empty array or 0 for a non-empty array. - -``` -empty(array) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. - -#### Example - -``` -> select empty([1]); -+------------------+ -| empty(List([1])) | -+------------------+ -| 0 | -+------------------+ -``` - -#### Aliases - -- array_empty, -- list_empty - -### `generate_series` - -Similar to the range function, but it includes the upper bound. - -``` -generate_series(start, stop, step) -``` - -#### Arguments - -- **start**: start of the series. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. -- **end**: end of the series (included). Type must be the same as start. -- **step**: increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges. - -#### Example - -``` -> select generate_series(1,3); -+------------------------------------+ -| generate_series(Int64(1),Int64(3)) | -+------------------------------------+ -| [1, 2, 3] | -+------------------------------------+ -``` - -### `list_any_value` - -_Alias of [array_any_value](#array_any_value)._ - -### `list_append` - -_Alias of [array_append](#array_append)._ - -### `list_cat` - -_Alias of [array_concat](#array_concat)._ - -### `list_concat` - -_Alias of [array_concat](#array_concat)._ - -### `list_dims` - -_Alias of [array_dims](#array_dims)._ - -### `list_distance` - -_Alias of [array_distance](#array_distance)._ - -### `list_distinct` - -_Alias of [array_distinct](#array_distinct)._ - -### `list_element` - -_Alias of [array_element](#array_element)._ - -### `list_empty` - -_Alias of [empty](#empty)._ - -### `list_except` - -_Alias of [array_element](#array_except)._ - -### `list_extract` - -_Alias of [array_element](#array_element)._ - -### `list_has` - -_Alias of [array_has](#array_has)._ - -### `list_has_all` - -_Alias of [array_has_all](#array_has_all)._ - -### `list_has_any` - -_Alias of [array_has_any](#array_has_any)._ - -### `list_indexof` - -_Alias of [array_position](#array_position)._ - -### `list_intersect` - -_Alias of [array_position](#array_intersect)._ - -### `list_join` - -_Alias of [array_to_string](#array_to_string)._ - -### `list_length` - -_Alias of [array_length](#array_length)._ - -### `list_ndims` - -_Alias of [array_ndims](#array_ndims)._ - -### `list_prepend` - -_Alias of [array_prepend](#array_prepend)._ - -### `list_pop_back` - -_Alias of [array_pop_back](#array_pop_back)._ - -### `list_pop_front` - -_Alias of [array_pop_front](#array_pop_front)._ - -### `list_position` - -_Alias of [array_position](#array_position)._ - -### `list_positions` - -_Alias of [array_positions](#array_positions)._ - -### `list_push_back` - -_Alias of [array_append](#array_append)._ - -### `list_push_front` - -_Alias of [array_prepend](#array_prepend)._ - -### `list_repeat` - -_Alias of [array_repeat](#array_repeat)._ - -### `list_resize` - -_Alias of [array_resize](#array_resize)._ - -### `list_remove` - -_Alias of [array_remove](#array_remove)._ - -### `list_remove_n` - -_Alias of [array_remove_n](#array_remove_n)._ - -### `list_remove_all` - -_Alias of [array_remove_all](#array_remove_all)._ - -### `list_replace` - -_Alias of [array_replace](#array_replace)._ - -### `list_replace_n` - -_Alias of [array_replace_n](#array_replace_n)._ - -### `list_replace_all` - -_Alias of [array_replace_all](#array_replace_all)._ - -### `list_reverse` - -_Alias of [array_reverse](#array_reverse)._ - -### `list_slice` - -_Alias of [array_slice](#array_slice)._ - -### `list_sort` - -_Alias of [array_sort](#array_sort)._ - -### `list_to_string` - -_Alias of [array_to_string](#array_to_string)._ - -### `list_union` - -_Alias of [array_union](#array_union)._ - -### `make_array` - -Returns an Arrow array using the specified input expressions. - -``` -make_array(expression1[, ..., expression_n]) -``` - -### `array_empty` - -_Alias of [empty](#empty)._ - -#### Arguments - -- **expression_n**: Expression to include in the output array. - Can be a constant, column, or function, and any combination of arithmetic or - string operators. - -#### Example - -``` -> select make_array(1, 2, 3, 4, 5); -+----------------------------------------------------------+ -| make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5)) | -+----------------------------------------------------------+ -| [1, 2, 3, 4, 5] | -+----------------------------------------------------------+ -``` - -#### Aliases - -- make_list - -### `make_list` - -_Alias of [make_array](#make_array)._ - -### `string_to_array` - -Splits a string in to an array of substrings based on a delimiter. Any substrings matching the optional `null_str` argument are replaced with NULL. -`SELECT string_to_array('abc##def', '##')` or `SELECT string_to_array('abc def', ' ', 'def')` - -``` -starts_with(str, delimiter[, null_str]) -``` - -#### Arguments - -- **str**: String expression to split. -- **delimiter**: Delimiter string to split on. -- **null_str**: Substring values to be replaced with `NULL` - -#### Aliases - -- string_to_list - -### `string_to_list` - -_Alias of [string_to_array](#string_to_array)._ - -### `trim_array` - -Removes the last n elements from the array. - -DEPRECATED: use `array_slice` instead! - -``` -trim_array(array, n) -``` - -#### Arguments - -- **array**: Array expression. - Can be a constant, column, or function, and any combination of array operators. -- **n**: Element to trim the array. ### `unnest` @@ -2078,52 +669,6 @@ Transforms an array into rows. +-----------------------------------+ ``` -### `range` - -Returns an Arrow array between start and stop with step. `SELECT range(2, 10, 3) -> [2, 5, 8]` or `SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH);` - -The range start..end contains all values with start <= x < end. It is empty if start >= end. - -Step can not be 0 (then the range will be nonsense.). - -Note that when the required range is a number, it accepts (stop), (start, stop), and (start, stop, step) as parameters, but when the required range is a date or timestamp, it must be 3 non-NULL parameters. -For example, - -``` -SELECT range(3); -SELECT range(1,5); -SELECT range(1,5,1); -``` - -are allowed in number ranges - -but in date and timestamp ranges, only - -``` -SELECT range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH); -SELECT range(TIMESTAMP '1992-09-01', TIMESTAMP '1993-03-01', INTERVAL '1' MONTH); -``` - -is allowed, and - -``` -SELECT range(DATE '1992-09-01', DATE '1993-03-01', NULL); -SELECT range(NULL, DATE '1993-03-01', INTERVAL '1' MONTH); -SELECT range(DATE '1992-09-01', NULL, INTERVAL '1' MONTH); -``` - -are not allowed - -#### Arguments - -- **start**: start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. -- **end**: end of the range (not included). Type must be the same as start. -- **step**: increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges. - -#### Aliases - -- generate_series - ## Struct Functions - [unnest](#unnest-struct) diff --git a/docs/source/user-guide/sql/scalar_functions_new.md b/docs/source/user-guide/sql/scalar_functions_new.md index 499fd7cd07a8..0a073db543b0 100644 --- a/docs/source/user-guide/sql/scalar_functions_new.md +++ b/docs/source/user-guide/sql/scalar_functions_new.md @@ -1842,6 +1842,1436 @@ to_date('2017-05-31', '%Y-%m-%d') Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs) +## Array Functions + +- [array_any_value](#array_any_value) +- [array_append](#array_append) +- [array_cat](#array_cat) +- [array_concat](#array_concat) +- [array_contains](#array_contains) +- [array_dims](#array_dims) +- [array_distance](#array_distance) +- [array_distinct](#array_distinct) +- [array_element](#array_element) +- [array_empty](#array_empty) +- [array_except](#array_except) +- [array_extract](#array_extract) +- [array_has](#array_has) +- [array_has_all](#array_has_all) +- [array_has_any](#array_has_any) +- [array_indexof](#array_indexof) +- [array_intersect](#array_intersect) +- [array_join](#array_join) +- [array_length](#array_length) +- [array_ndims](#array_ndims) +- [array_pop_back](#array_pop_back) +- [array_pop_front](#array_pop_front) +- [array_position](#array_position) +- [array_positions](#array_positions) +- [array_prepend](#array_prepend) +- [array_push_back](#array_push_back) +- [array_push_front](#array_push_front) +- [array_remove](#array_remove) +- [array_remove_all](#array_remove_all) +- [array_remove_n](#array_remove_n) +- [array_repeat](#array_repeat) +- [array_replace](#array_replace) +- [array_replace_all](#array_replace_all) +- [array_replace_n](#array_replace_n) +- [array_resize](#array_resize) +- [array_reverse](#array_reverse) +- [array_slice](#array_slice) +- [array_sort](#array_sort) +- [array_to_string](#array_to_string) +- [array_union](#array_union) +- [cardinality](#cardinality) +- [empty](#empty) +- [flatten](#flatten) +- [generate_series](#generate_series) +- [list_any_value](#list_any_value) +- [list_append](#list_append) +- [list_cat](#list_cat) +- [list_concat](#list_concat) +- [list_contains](#list_contains) +- [list_dims](#list_dims) +- [list_distance](#list_distance) +- [list_distinct](#list_distinct) +- [list_element](#list_element) +- [list_empty](#list_empty) +- [list_except](#list_except) +- [list_extract](#list_extract) +- [list_has](#list_has) +- [list_has_all](#list_has_all) +- [list_has_any](#list_has_any) +- [list_indexof](#list_indexof) +- [list_intersect](#list_intersect) +- [list_join](#list_join) +- [list_length](#list_length) +- [list_ndims](#list_ndims) +- [list_pop_back](#list_pop_back) +- [list_pop_front](#list_pop_front) +- [list_position](#list_position) +- [list_positions](#list_positions) +- [list_prepend](#list_prepend) +- [list_push_back](#list_push_back) +- [list_push_front](#list_push_front) +- [list_remove](#list_remove) +- [list_remove_all](#list_remove_all) +- [list_remove_n](#list_remove_n) +- [list_repeat](#list_repeat) +- [list_replace](#list_replace) +- [list_replace_all](#list_replace_all) +- [list_replace_n](#list_replace_n) +- [list_resize](#list_resize) +- [list_reverse](#list_reverse) +- [list_slice](#list_slice) +- [list_sort](#list_sort) +- [list_to_string](#list_to_string) +- [list_union](#list_union) +- [make_array](#make_array) +- [make_list](#make_list) +- [range](#range) +- [string_to_array](#string_to_array) +- [string_to_list](#string_to_list) + +### `array_any_value` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +#### Example + +```sql +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +#### Aliases + +- list_any_value + +### `array_append` + +Appends an element to the end of an array. + +``` +array_append(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to append to the array. + +#### Example + +```sql +> select array_append([1, 2, 3], 4); ++--------------------------------------+ +| array_append(List([1,2,3]),Int64(4)) | ++--------------------------------------+ +| [1, 2, 3, 4] | ++--------------------------------------+ +``` + +#### Aliases + +- list_append +- array_push_back +- list_push_back + +### `array_cat` + +_Alias of [array_concat](#array_concat)._ + +### `array_concat` + +Appends an element to the end of an array. + +``` +array_append(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to append to the array. + +#### Example + +```sql +> select array_append([1, 2, 3], 4); ++--------------------------------------+ +| array_append(List([1,2,3]),Int64(4)) | ++--------------------------------------+ +| [1, 2, 3, 4] | ++--------------------------------------+ +``` + +#### Aliases + +- array_cat +- list_concat +- list_cat + +### `array_contains` + +_Alias of [array_has](#array_has)._ + +### `array_dims` + +Returns an array of the array's dimensions. + +``` +array_dims(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_dims([[1, 2, 3], [4, 5, 6]]); ++---------------------------------+ +| array_dims(List([1,2,3,4,5,6])) | ++---------------------------------+ +| [2, 3] | ++---------------------------------+ +``` + +#### Aliases + +- list_dims + +### `array_distance` + +Returns the Euclidean distance between two input arrays of equal length. + +``` +array_distance(array1, array2) +``` + +#### Arguments + +- **array1**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_distance([1, 2], [1, 4]); ++------------------------------------+ +| array_distance(List([1,2], [1,4])) | ++------------------------------------+ +| 2.0 | ++------------------------------------+ +``` + +#### Aliases + +- list_distance + +### `array_distinct` + +Returns distinct values from the array after removing duplicates. + +``` +array_distinct(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_distinct([1, 3, 2, 3, 1, 2, 4]); ++---------------------------------+ +| array_distinct(List([1,2,3,4])) | ++---------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------+ +``` + +#### Aliases + +- list_distinct + +### `array_element` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +#### Example + +```sql +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +#### Aliases + +- array_extract +- list_element +- list_extract + +### `array_empty` + +_Alias of [empty](#empty)._ + +### `array_except` + +Returns an array of the elements that appear in the first array but not in the second. + +``` +array_except(array1, array2) +``` + +#### Arguments + +- **array1**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **array2**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_except([1, 2, 3, 4], [5, 6, 3, 4]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [5, 6, 3, 4]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +> select array_except([1, 2, 3, 4], [3, 4, 5, 6]); ++----------------------------------------------------+ +| array_except([1, 2, 3, 4], [3, 4, 5, 6]); | ++----------------------------------------------------+ +| [1, 2] | ++----------------------------------------------------+ +``` + +#### Aliases + +- list_except + +### `array_extract` + +_Alias of [array_element](#array_element)._ + +### `array_has` + +Returns true if the array contains the element. + +``` +array_has(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Scalar or Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_has([1, 2, 3], 2); ++-----------------------------+ +| array_has(List([1,2,3]), 2) | ++-----------------------------+ +| true | ++-----------------------------+ +``` + +#### Aliases + +- list_has +- array_contains +- list_contains + +### `array_has_all` + +Returns true if the array contains the element. + +``` +array_has(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Scalar or Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_has([1, 2, 3], 2); ++-----------------------------+ +| array_has(List([1,2,3]), 2) | ++-----------------------------+ +| true | ++-----------------------------+ +``` + +#### Aliases + +- list_has_all + +### `array_has_any` + +Returns true if the array contains the element. + +``` +array_has(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Scalar or Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_has([1, 2, 3], 2); ++-----------------------------+ +| array_has(List([1,2,3]), 2) | ++-----------------------------+ +| true | ++-----------------------------+ +``` + +#### Aliases + +- list_has_any + +### `array_indexof` + +_Alias of [array_position](#array_position)._ + +### `array_intersect` + +Returns distinct values from the array after removing duplicates. + +``` +array_distinct(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_distinct([1, 3, 2, 3, 1, 2, 4]); ++---------------------------------+ +| array_distinct(List([1,2,3,4])) | ++---------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------+ +``` + +#### Aliases + +- list_intersect + +### `array_join` + +_Alias of [array_to_string](#array_to_string)._ + +### `array_length` + +Returns the length of the array dimension. + +``` +array_length(array, dimension) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **dimension**: Array dimension. + +#### Example + +```sql +> select array_length([1, 2, 3, 4, 5], 1); ++-------------------------------------------+ +| array_length(List([1,2,3,4,5]), 1) | ++-------------------------------------------+ +| 5 | ++-------------------------------------------+ +``` + +#### Aliases + +- list_length + +### `array_ndims` + +Returns an array of the array's dimensions. + +``` +array_dims(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_dims([[1, 2, 3], [4, 5, 6]]); ++---------------------------------+ +| array_dims(List([1,2,3,4,5,6])) | ++---------------------------------+ +| [2, 3] | ++---------------------------------+ +``` + +#### Aliases + +- list_ndims + +### `array_pop_back` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +#### Example + +```sql +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +#### Aliases + +- list_pop_back + +### `array_pop_front` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +#### Example + +```sql +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +#### Aliases + +- list_pop_front + +### `array_position` + +Returns the position of the first occurrence of the specified element in the array. + +``` +array_position(array, element) +array_position(array, element, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to search for position in the array. +- **index**: Index at which to start searching. + +#### Example + +```sql +> select array_position([1, 2, 2, 3, 1, 4], 2); ++----------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2)) | ++----------------------------------------------+ +| 2 | ++----------------------------------------------+ +> select array_position([1, 2, 2, 3, 1, 4], 2, 3); ++----------------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2), Int64(3)) | ++----------------------------------------------------+ +| 3 | ++----------------------------------------------------+ +``` + +#### Aliases + +- list_position +- array_indexof +- list_indexof + +### `array_positions` + +Returns the position of the first occurrence of the specified element in the array. + +``` +array_position(array, element) +array_position(array, element, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to search for position in the array. +- **index**: Index at which to start searching. + +#### Example + +```sql +> select array_position([1, 2, 2, 3, 1, 4], 2); ++----------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2)) | ++----------------------------------------------+ +| 2 | ++----------------------------------------------+ +> select array_position([1, 2, 2, 3, 1, 4], 2, 3); ++----------------------------------------------------+ +| array_position(List([1,2,2,3,1,4]),Int64(2), Int64(3)) | ++----------------------------------------------------+ +| 3 | ++----------------------------------------------------+ +``` + +#### Aliases + +- list_positions + +### `array_prepend` + +Appends an element to the end of an array. + +``` +array_append(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to append to the array. + +#### Example + +```sql +> select array_append([1, 2, 3], 4); ++--------------------------------------+ +| array_append(List([1,2,3]),Int64(4)) | ++--------------------------------------+ +| [1, 2, 3, 4] | ++--------------------------------------+ +``` + +#### Aliases + +- list_prepend +- array_push_front +- list_push_front + +### `array_push_back` + +_Alias of [array_append](#array_append)._ + +### `array_push_front` + +_Alias of [array_prepend](#array_prepend)._ + +### `array_remove` + +Removes the first element from the array equal to the given value. + +``` +array_remove(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +#### Example + +```sql +> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); ++----------------------------------------------+ +| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | ++----------------------------------------------+ +| [1, 2, 3, 2, 1, 4] | ++----------------------------------------------+ +``` + +#### Aliases + +- list_remove + +### `array_remove_all` + +Removes the first element from the array equal to the given value. + +``` +array_remove(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +#### Example + +```sql +> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); ++----------------------------------------------+ +| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | ++----------------------------------------------+ +| [1, 2, 3, 2, 1, 4] | ++----------------------------------------------+ +``` + +#### Aliases + +- list_remove_all + +### `array_remove_n` + +Removes the first element from the array equal to the given value. + +``` +array_remove(array, element) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **element**: Element to be removed from the array. + +#### Example + +```sql +> select array_remove([1, 2, 2, 3, 2, 1, 4], 2); ++----------------------------------------------+ +| array_remove(List([1,2,2,3,2,1,4]),Int64(2)) | ++----------------------------------------------+ +| [1, 2, 3, 2, 1, 4] | ++----------------------------------------------+ +``` + +#### Aliases + +- list_remove_n + +### `array_repeat` + +Returns an array containing element `count` times. + +``` +array_repeat(element, count) +``` + +#### Arguments + +- **element**: Element expression. Can be a constant, column, or function, and any combination of array operators. +- **count**: Value of how many times to repeat the element. + +#### Example + +```sql +> select array_repeat(1, 3); ++---------------------------------+ +| array_repeat(Int64(1),Int64(3)) | ++---------------------------------+ +| [1, 1, 1] | ++---------------------------------+ +> select array_repeat([1, 2], 2); ++------------------------------------+ +| array_repeat(List([1,2]),Int64(2)) | ++------------------------------------+ +| [[1, 2], [1, 2]] | ++------------------------------------+ +``` + +#### Aliases + +- list_repeat + +### `array_replace` + +Replaces the first `max` occurrences of the specified element with another specified element. + +``` +array_replace_n(array, from, to, max) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. +- **max**: Number of first occurrences to replace. + +#### Example + +```sql +> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); ++-------------------------------------------------------------------+ +| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | ++-------------------------------------------------------------------+ +| [1, 5, 5, 3, 2, 1, 4] | ++-------------------------------------------------------------------+ +``` + +#### Aliases + +- list_replace + +### `array_replace_all` + +Replaces the first `max` occurrences of the specified element with another specified element. + +``` +array_replace_n(array, from, to, max) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. +- **max**: Number of first occurrences to replace. + +#### Example + +```sql +> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); ++-------------------------------------------------------------------+ +| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | ++-------------------------------------------------------------------+ +| [1, 5, 5, 3, 2, 1, 4] | ++-------------------------------------------------------------------+ +``` + +#### Aliases + +- list_replace_all + +### `array_replace_n` + +Replaces the first `max` occurrences of the specified element with another specified element. + +``` +array_replace_n(array, from, to, max) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **from**: Initial element. +- **to**: Final element. +- **max**: Number of first occurrences to replace. + +#### Example + +```sql +> select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); ++-------------------------------------------------------------------+ +| array_replace_n(List([1,2,2,3,2,1,4]),Int64(2),Int64(5),Int64(2)) | ++-------------------------------------------------------------------+ +| [1, 5, 5, 3, 2, 1, 4] | ++-------------------------------------------------------------------+ +``` + +#### Aliases + +- list_replace_n + +### `array_resize` + +Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set. + +``` +array_resize(array, size, value) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **size**: New size of given array. +- **value**: Defines new elements' value or empty if value is not set. + +#### Example + +```sql +> select array_resize([1, 2, 3], 5, 0); ++-------------------------------------+ +| array_resize(List([1,2,3],5,0)) | ++-------------------------------------+ +| [1, 2, 3, 0, 0] | ++-------------------------------------+ +``` + +#### Aliases + +- list_resize + +### `array_reverse` + +Returns the array with the order of the elements reversed. + +``` +array_reverse(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_reverse([1, 2, 3, 4]); ++------------------------------------------------------------+ +| array_reverse(List([1, 2, 3, 4])) | ++------------------------------------------------------------+ +| [4, 3, 2, 1] | ++------------------------------------------------------------+ +``` + +#### Aliases + +- list_reverse + +### `array_slice` + +Extracts the element with the index n from the array. + +``` +array_element(array, index) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **index**: Index to extract the element from the array. + +#### Example + +```sql +> select array_element([1, 2, 3, 4], 3); ++-----------------------------------------+ +| array_element(List([1,2,3,4]),Int64(3)) | ++-----------------------------------------+ +| 3 | ++-----------------------------------------+ +``` + +#### Aliases + +- list_slice + +### `array_sort` + +Sort array. + +``` +array_sort(array, desc, nulls_first) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **desc**: Whether to sort in descending order(`ASC` or `DESC`). +- **nulls_first**: Whether to sort nulls first(`NULLS FIRST` or `NULLS LAST`). + +#### Example + +```sql +> select array_sort([3, 1, 2]); ++-----------------------------+ +| array_sort(List([3,1,2])) | ++-----------------------------+ +| [1, 2, 3] | ++-----------------------------+ +``` + +#### Aliases + +- list_sort + +### `array_to_string` + +Converts each element to its text representation. + +``` +array_to_string(array, delimiter) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **delimiter**: Array element separator. + +#### Example + +```sql +> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); ++----------------------------------------------------+ +| array_to_string(List([1,2,3,4,5,6,7,8]),Utf8(",")) | ++----------------------------------------------------+ +| 1,2,3,4,5,6,7,8 | ++----------------------------------------------------+ +``` + +#### Aliases + +- list_to_string +- array_join +- list_join + +### `array_union` + +Returns distinct values from the array after removing duplicates. + +``` +array_distinct(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select array_distinct([1, 3, 2, 3, 1, 2, 4]); ++---------------------------------+ +| array_distinct(List([1,2,3,4])) | ++---------------------------------+ +| [1, 2, 3, 4] | ++---------------------------------+ +``` + +#### Aliases + +- list_union + +### `cardinality` + +Returns the total number of elements in the array. + +``` +cardinality(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]); ++--------------------------------------+ +| cardinality(List([1,2,3,4,5,6,7,8])) | ++--------------------------------------+ +| 8 | ++--------------------------------------+ +``` + +### `empty` + +Returns 1 for an empty array or 0 for a non-empty array. + +``` +empty(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select empty([1]); ++------------------+ +| empty(List([1])) | ++------------------+ +| 0 | ++------------------+ +``` + +#### Aliases + +- array_empty +- list_empty + +### `flatten` + +Converts an array of arrays to a flat array. + +- Applies to any depth of nested arrays +- Does not change arrays that are already flat + +The flattened array contains all the elements from all source arrays. + +``` +flatten(array) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. + +#### Example + +```sql +> select flatten([[1, 2], [3, 4]]); ++------------------------------+ +| flatten(List([1,2], [3,4])) | ++------------------------------+ +| [1, 2, 3, 4] | ++------------------------------+ +``` + +### `generate_series` + +Returns an Arrow array between start and stop with step. The range start..end contains all values with start <= x < end. It is empty if start >= end. Step cannot be 0. + +``` +range(start, stop, step) +``` + +#### Arguments + +- **start**: Start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. +- **end**: End of the range (not included). Type must be the same as start. +- **step**: Increase by step (cannot be 0). Steps less than a day are supported only for timestamp ranges. + +#### Example + +```sql +> select range(2, 10, 3); ++-----------------------------------+ +| range(Int64(2),Int64(10),Int64(3))| ++-----------------------------------+ +| [2, 5, 8] | ++-----------------------------------+ + +> select range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH); ++--------------------------------------------------------------+ +| range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH) | ++--------------------------------------------------------------+ +| [1992-09-01, 1992-10-01, 1992-11-01, 1992-12-01, 1993-01-01, 1993-02-01] | ++--------------------------------------------------------------+ +``` + +### `list_any_value` + +_Alias of [array_any_value](#array_any_value)._ + +### `list_append` + +_Alias of [array_append](#array_append)._ + +### `list_cat` + +_Alias of [array_concat](#array_concat)._ + +### `list_concat` + +_Alias of [array_concat](#array_concat)._ + +### `list_contains` + +_Alias of [array_has](#array_has)._ + +### `list_dims` + +_Alias of [array_dims](#array_dims)._ + +### `list_distance` + +_Alias of [array_distance](#array_distance)._ + +### `list_distinct` + +_Alias of [array_distinct](#array_distinct)._ + +### `list_element` + +_Alias of [array_element](#array_element)._ + +### `list_empty` + +_Alias of [empty](#empty)._ + +### `list_except` + +_Alias of [array_except](#array_except)._ + +### `list_extract` + +_Alias of [array_element](#array_element)._ + +### `list_has` + +_Alias of [array_has](#array_has)._ + +### `list_has_all` + +_Alias of [array_has_all](#array_has_all)._ + +### `list_has_any` + +_Alias of [array_has_any](#array_has_any)._ + +### `list_indexof` + +_Alias of [array_position](#array_position)._ + +### `list_intersect` + +_Alias of [array_intersect](#array_intersect)._ + +### `list_join` + +_Alias of [array_to_string](#array_to_string)._ + +### `list_length` + +_Alias of [array_length](#array_length)._ + +### `list_ndims` + +_Alias of [array_ndims](#array_ndims)._ + +### `list_pop_back` + +_Alias of [array_pop_back](#array_pop_back)._ + +### `list_pop_front` + +_Alias of [array_pop_front](#array_pop_front)._ + +### `list_position` + +_Alias of [array_position](#array_position)._ + +### `list_positions` + +_Alias of [array_positions](#array_positions)._ + +### `list_prepend` + +_Alias of [array_prepend](#array_prepend)._ + +### `list_push_back` + +_Alias of [array_append](#array_append)._ + +### `list_push_front` + +_Alias of [array_prepend](#array_prepend)._ + +### `list_remove` + +_Alias of [array_remove](#array_remove)._ + +### `list_remove_all` + +_Alias of [array_remove_all](#array_remove_all)._ + +### `list_remove_n` + +_Alias of [array_remove_n](#array_remove_n)._ + +### `list_repeat` + +_Alias of [array_repeat](#array_repeat)._ + +### `list_replace` + +_Alias of [array_replace](#array_replace)._ + +### `list_replace_all` + +_Alias of [array_replace_all](#array_replace_all)._ + +### `list_replace_n` + +_Alias of [array_replace_n](#array_replace_n)._ + +### `list_resize` + +_Alias of [array_resize](#array_resize)._ + +### `list_reverse` + +_Alias of [array_reverse](#array_reverse)._ + +### `list_slice` + +_Alias of [array_slice](#array_slice)._ + +### `list_sort` + +_Alias of [array_sort](#array_sort)._ + +### `list_to_string` + +_Alias of [array_to_string](#array_to_string)._ + +### `list_union` + +_Alias of [array_union](#array_union)._ + +### `make_array` + +Returns an array using the specified input expressions. + +``` +make_array(expression1[, ..., expression_n]) +``` + +#### Arguments + +- **expression_n**: Expression to include in the output array. Can be a constant, column, or function, and any combination of arithmetic or string operators. + +#### Example + +```sql +> select make_array(1, 2, 3, 4, 5); ++----------------------------------------------------------+ +| make_array(Int64(1),Int64(2),Int64(3),Int64(4),Int64(5)) | ++----------------------------------------------------------+ +| [1, 2, 3, 4, 5] | ++----------------------------------------------------------+ +``` + +#### Aliases + +- make_list + +### `make_list` + +_Alias of [make_array](#make_array)._ + +### `range` + +Returns an Arrow array between start and stop with step. The range start..end contains all values with start <= x < end. It is empty if start >= end. Step cannot be 0. + +``` +range(start, stop, step) +``` + +#### Arguments + +- **start**: Start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported. +- **end**: End of the range (not included). Type must be the same as start. +- **step**: Increase by step (cannot be 0). Steps less than a day are supported only for timestamp ranges. + +#### Example + +```sql +> select range(2, 10, 3); ++-----------------------------------+ +| range(Int64(2),Int64(10),Int64(3))| ++-----------------------------------+ +| [2, 5, 8] | ++-----------------------------------+ + +> select range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH); ++--------------------------------------------------------------+ +| range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH) | ++--------------------------------------------------------------+ +| [1992-09-01, 1992-10-01, 1992-11-01, 1992-12-01, 1993-01-01, 1993-02-01] | ++--------------------------------------------------------------+ +``` + +### `string_to_array` + +Converts each element to its text representation. + +``` +array_to_string(array, delimiter) +``` + +#### Arguments + +- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. +- **delimiter**: Array element separator. + +#### Example + +```sql +> select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); ++----------------------------------------------------+ +| array_to_string(List([1,2,3,4,5,6,7,8]),Utf8(",")) | ++----------------------------------------------------+ +| 1,2,3,4,5,6,7,8 | ++----------------------------------------------------+ +``` + +#### Aliases + +- string_to_list + +### `string_to_list` + +_Alias of [string_to_array](#string_to_array)._ + ## Struct Functions - [named_struct](#named_struct)