Skip to content

Apache DataFusion SQL Query Engine

chore: fix some scalar function docs (#24134)

Jeffrey Vobc48a4f7acd8
diff --git a/datafusion/doc/src/udf.rs b/datafusion/doc/src/udf.rs
index d1f51d9194..f88db631e6 100644
--- a/datafusion/doc/src/udf.rs
+++ b/datafusion/doc/src/udf.rs
@@ -84,6 +84,14 @@ pub mod scalar_doc_sections {
r#"Apache DataFusion uses a [PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions)
regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax)
(minus support for several features including look-around and backreferences).
+
+The following flags are optionally supported in functions:
+ - **i**: case-insensitive: letters match both upper and lower case
+ - **m**: multi-line mode: `^` and `$` match begin/end of line
+ - **s**: allow `.` to match `\n`
+ - **R**: enables CRLF mode: when multi-line mode is enabled, `\r\n` is used
+ - **U**: swap the meaning of `x*` and `x*?`
+
The following regular expression functions are supported:"#,
),
};
diff --git a/datafusion/functions-nested/src/array_has.rs b/datafusion/functions-nested/src/array_has.rs
index 11b8a43664..0f680469f6 100644
--- a/datafusion/functions-nested/src/array_has.rs
+++ b/datafusion/functions-nested/src/array_has.rs
@@ -994,22 +994,22 @@ fn array_has_any_with_scalar_general(
#[user_doc(
doc_section(label = "Array Functions"),
- description = "Returns true if all elements of sub-array exist in array.",
- syntax_example = "array_has_all(array, sub-array)",
+ description = "Returns true if all elements of sub_array exist in array.",
+ syntax_example = "array_has_all(array, sub_array)",
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 |
-+--------------------------------------------+
++---------------------------------------------+
+| true |
++---------------------------------------------+
```"#,
argument(
name = "array",
description = "Array expression. Can be a constant, column, or function, and any combination of array operators."
),
argument(
- name = "sub-array",
+ name = "sub_array",
description = "Array expression. Can be a constant, column, or function, and any combination of array operators."
)
)]
diff --git a/datafusion/functions-nested/src/dimension.rs b/datafusion/functions-nested/src/dimension.rs
index 01fb81d878..7e9a10f362 100644
--- a/datafusion/functions-nested/src/dimension.rs
+++ b/datafusion/functions-nested/src/dimension.rs
@@ -122,7 +122,7 @@ make_udf_expr_and_func!(
#[user_doc(
doc_section(label = "Array Functions"),
description = "Returns the number of dimensions of the array.",
- syntax_example = "array_ndims(array, element)",
+ syntax_example = "array_ndims(array)",
sql_example = r#"```sql
> select array_ndims([[1, 2, 3], [4, 5, 6]]);
+----------------------------------+
@@ -134,8 +134,7 @@ make_udf_expr_and_func!(
argument(
name = "array",
description = "Array expression. Can be a constant, column, or function, and any combination of array operators."
- ),
- argument(name = "element", description = "Array element.")
+ )
)]
#[derive(Debug, PartialEq, Eq, Hash)]
pub(super) struct ArrayNdims {
diff --git a/datafusion/functions-nested/src/extract.rs b/datafusion/functions-nested/src/extract.rs
index b1c22822df..9d367f0161 100644
--- a/datafusion/functions-nested/src/extract.rs
+++ b/datafusion/functions-nested/src/extract.rs
@@ -289,7 +289,7 @@ pub fn array_slice(array: Expr, begin: Expr, end: Expr, stride: Option<Expr>) ->
#[user_doc(
doc_section(label = "Array Functions"),
description = "Returns a slice of the array based on 1-indexed start and end positions.",
- syntax_example = "array_slice(array, begin, end)",
+ syntax_example = "array_slice(array, begin, end[, stride])",
sql_example = r#"```sql
> select array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6);
+--------------------------------------------------------+
diff --git a/datafusion/functions-nested/src/length.rs b/datafusion/functions-nested/src/length.rs
index 9579c3c9cd..24c79c40d7 100644
--- a/datafusion/functions-nested/src/length.rs
+++ b/datafusion/functions-nested/src/length.rs
@@ -49,7 +49,7 @@ make_udf_expr_and_func!(
#[user_doc(
doc_section(label = "Array Functions"),
description = "Returns the length of the array dimension.",
- syntax_example = "array_length(array, dimension)",
+ syntax_example = "array_length(array[, dimension])",
sql_example = r#"```sql
> select array_length([1, 2, 3, 4, 5], 1);
+-------------------------------------------+
@@ -62,7 +62,7 @@ make_udf_expr_and_func!(
name = "array",
description = "Array expression. Can be a constant, column, or function, and any combination of array operators."
),
- argument(name = "dimension", description = "Array dimension.")
+ argument(name = "dimension", description = "Array dimension. Default is 1")
)]
#[derive(Debug, PartialEq, Eq, Hash)]
pub struct ArrayLength {
diff --git a/datafusion/functions-nested/src/make_array.rs b/datafusion/functions-nested/src/make_array.rs
index 6f083ab700..ba746cd9cf 100644
--- a/datafusion/functions-nested/src/make_array.rs
+++ b/datafusion/functions-nested/src/make_array.rs
@@ -50,7 +50,7 @@ make_udf_expr_and_func!(
#[user_doc(
doc_section(label = "Array Functions"),
description = "Returns an array using the specified input expressions.",
- syntax_example = "make_array(expression1[, ..., expression_n])",
+ syntax_example = "make_array([expression1, ..., expression_n])",
sql_example = r#"```sql
> select make_array(1, 2, 3, 4, 5);
+----------------------------------------------------------+
diff --git a/datafusion/functions-nested/src/map.rs b/datafusion/functions-nested/src/map.rs
index 36ccd1cfb3..660442f8a3 100644
--- a/datafusion/functions-nested/src/map.rs
+++ b/datafusion/functions-nested/src/map.rs
@@ -328,7 +328,7 @@ fn make_map_batch_internal(
doc_section(label = "Map Functions"),
description = "Returns an Arrow map with the specified key-value pairs.\n\n\
The `make_map` function creates a map from two lists: one for keys and one for values. Each key must be unique and non-null.",
- syntax_example = "map(key, value)\nmap(key: value)\nmake_map(['key1', 'key2'], ['value1', 'value2'])",
+ syntax_example = "map(key, value)\nmap {key: value}\nmake_map(['key1', 'key2'], ['value1', 'value2'])",
sql_example = r#"
```sql
-- Using map function
diff --git a/datafusion/functions-nested/src/position.rs b/datafusion/functions-nested/src/position.rs
index d65620ede3..2a0134b4b9 100644
--- a/datafusion/functions-nested/src/position.rs
+++ b/datafusion/functions-nested/src/position.rs
@@ -56,7 +56,7 @@ make_udf_expr_and_func!(
#[user_doc(
doc_section(label = "Array Functions"),
description = "Returns the position of the first occurrence of the specified element in the array, or NULL if not found. Comparisons are done using `IS DISTINCT FROM` semantics, so NULL is considered to match NULL.",
- syntax_example = "array_position(array, element)\narray_position(array, element, index)",
+ syntax_example = "array_position(array, element[, index])",
sql_example = r#"```sql
> select array_position([1, 2, 2, 3, 1, 4], 2);
+----------------------------------------------+
@@ -78,7 +78,7 @@ make_udf_expr_and_func!(
argument(name = "element", description = "Element to search for in the array."),
argument(
name = "index",
- description = "Index at which to start searching (1-indexed)."
+ description = "Index at which to start searching (1-indexed). Defaults to searching from the start"
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/datafusion/functions-nested/src/resize.rs b/datafusion/functions-nested/src/resize.rs
index 832ddbdc0a..e08149ec0f 100644
--- a/datafusion/functions-nested/src/resize.rs
+++ b/datafusion/functions-nested/src/resize.rs
@@ -49,8 +49,8 @@ make_udf_expr_and_func!(
#[user_doc(
doc_section(label = "Array Functions"),
- description = "Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set.",
- syntax_example = "array_resize(array, size, value)",
+ description = "Resizes the list to contain size elements.",
+ syntax_example = "array_resize(array, size[, value])",
sql_example = r#"```sql
> select array_resize([1, 2, 3], 5, 0);
+-------------------------------------+
@@ -66,7 +66,7 @@ make_udf_expr_and_func!(
argument(name = "size", description = "New size of given array."),
argument(
name = "value",
- description = "Defines new elements' value or empty if value is not set."
+ description = "If expanding the array, defines the values to fill in. Defaults to null."
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/datafusion/functions-nested/src/sort.rs b/datafusion/functions-nested/src/sort.rs
index ca9267bb88..f4f9148f76 100644
--- a/datafusion/functions-nested/src/sort.rs
+++ b/datafusion/functions-nested/src/sort.rs
@@ -55,7 +55,7 @@ make_udf_expr_and_func!(
#[user_doc(
doc_section(label = "Array Functions"),
description = "Sort array.",
- syntax_example = "array_sort(array, desc, nulls_first)",
+ syntax_example = "array_sort(array[, order[, nulls_order]])",
sql_example = r#"```sql
> select array_sort([3, 1, 2]);
+-----------------------------+
@@ -63,17 +63,23 @@ make_udf_expr_and_func!(
+-----------------------------+
| [1, 2, 3] |
+-----------------------------+
+> select array_sort([3, 1, NULL, 2], 'desc', 'nulls last');
++--------------------------------------------------+
+| array_sort(List(3,1,NULL,2),'desc','nulls last') |
++--------------------------------------------------+
+| [3, 2, 1, NULL] |
++--------------------------------------------------+
```"#,
argument(
name = "array",
description = "Array expression. Can be a constant, column, or function, and any combination of array operators."
),
argument(
- name = "desc",
+ name = "order",
description = "Whether to sort in ascending (`ASC`) or descending (`DESC`) order. The default is `ASC`."
),
argument(
- name = "nulls_first",
+ name = "nulls_order",
description = "Whether to sort nulls first (`NULLS FIRST`) or last (`NULLS LAST`). The default is `NULLS FIRST`."
)
)]
diff --git a/datafusion/functions/src/datetime/current_date.rs b/datafusion/functions/src/datetime/current_date.rs
index d07a3b1caf..e93a64e8cc 100644
--- a/datafusion/functions/src/datetime/current_date.rs
+++ b/datafusion/functions/src/datetime/current_date.rs
@@ -35,9 +35,7 @@ Returns the current date in the session time zone.
The `current_date()` return value is determined at query time and will return the same date, no matter when in the query plan the function executes.
"#,
- syntax_example = r#"current_date()
- (optional) SET datafusion.execution.time_zone = '+00:00';
- SELECT current_date();"#,
+ syntax_example = "current_date()",
sql_example = r#"```sql
> SELECT current_date();
+----------------+
diff --git a/datafusion/functions/src/datetime/current_time.rs b/datafusion/functions/src/datetime/current_time.rs
index 92f4ae5e66..b93fb07d2b 100644
--- a/datafusion/functions/src/datetime/current_time.rs
+++ b/datafusion/functions/src/datetime/current_time.rs
@@ -38,9 +38,7 @@ The `current_time()` return value is determined at query time and will return th
The session time zone can be set using the statement 'SET datafusion.execution.time_zone = desired time zone'. The time zone can be a value like +00:00, 'Europe/London' etc.
"#,
- syntax_example = r#"current_time()
- (optional) SET datafusion.execution.time_zone = '+00:00';
- SELECT current_time();"#,
+ syntax_example = "current_time()",
sql_example = r#"```sql
> SELECT current_time();
+--------------------+
diff --git a/datafusion/functions/src/datetime/date_bin.rs b/datafusion/functions/src/datetime/date_bin.rs
index 2ce11e1daf..1338df3aa9 100644
--- a/datafusion/functions/src/datetime/date_bin.rs
+++ b/datafusion/functions/src/datetime/date_bin.rs
@@ -54,7 +54,7 @@ Calculates time intervals and returns the start of the interval nearest to the s
For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`.
"#,
- syntax_example = "date_bin(interval, expression, origin-timestamp)",
+ syntax_example = "date_bin(interval, expression[, origin_timestamp])",
sql_example = r#"```sql
-- Bin the timestamp into 1 day intervals
> SELECT date_bin(interval '1 day', time) as bin
@@ -95,7 +95,7 @@ FROM VALUES (TIME '02:18:18'), (TIME '19:00:03') t(time);
description = "Time expression to operate on. Can be a constant, column, or function."
),
argument(
- name = "origin-timestamp",
+ name = "origin_timestamp",
description = r#"Optional. Starting point used to determine bin boundaries. If not specified defaults 1970-01-01T00:00:00Z (the UNIX epoch in UTC). The following intervals are supported:
- nanoseconds
diff --git a/datafusion/functions/src/datetime/to_char.rs b/datafusion/functions/src/datetime/to_char.rs
index 5accddd07f..1d38471174 100644
--- a/datafusion/functions/src/datetime/to_char.rs
+++ b/datafusion/functions/src/datetime/to_char.rs
@@ -57,10 +57,6 @@ Additional examples can be found [here](https://github.com/apache/datafusion/blo
argument(
name = "format",
description = "A [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) string to use to convert the expression."
- ),
- argument(
- name = "day",
- description = "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/datafusion/functions/src/datetime/to_date.rs b/datafusion/functions/src/datetime/to_date.rs
index 37190f6a4a..668c6ce029 100644
--- a/datafusion/functions/src/datetime/to_date.rs
+++ b/datafusion/functions/src/datetime/to_date.rs
@@ -38,7 +38,7 @@ Integers and doubles are interpreted as days since the unix epoch (`1970-01-01T0
Returns the corresponding date.
Note: `to_date` returns Date32, which represents its values as the number of days since unix epoch(`1970-01-01`) stored as signed 32 bit value. The largest supported date value is `9999-12-31`.",
- syntax_example = "to_date(expression[, ..., format_n])",
+ syntax_example = "to_date(expression[, format1, ..., format_n])",
sql_example = r#"```sql
> select to_date('2023-01-31');
+-------------------------------+
diff --git a/datafusion/functions/src/datetime/to_time.rs b/datafusion/functions/src/datetime/to_time.rs
index 696f25dad9..f5fe59cbb8 100644
--- a/datafusion/functions/src/datetime/to_time.rs
+++ b/datafusion/functions/src/datetime/to_time.rs
@@ -47,7 +47,7 @@ Timestamps will have the time portion extracted.
Returns the corresponding time.
Note: `to_time` returns Time64(Nanosecond), which represents the time of day in nanoseconds since midnight.",
- syntax_example = "to_time(expression[, ..., format_n])",
+ syntax_example = "to_time(expression[, format1, ..., format_n])",
sql_example = r#"```sql
> select to_time('12:30:45');
+---------------------------+
diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs
index d1174d77b9..d223446d96 100644
--- a/datafusion/functions/src/math/monotonicity.rs
+++ b/datafusion/functions/src/math/monotonicity.rs
@@ -154,7 +154,7 @@ static DOCUMENTATION_ASINH: LazyLock<Documentation> = LazyLock::new(|| {
)
.with_standard_argument("numeric_expression", Some("Numeric"))
.with_sql_example(
- r#" ```sql
+ r#" ```sql
> SELECT asinh(1);
+------------+
| asinh(1) |
@@ -184,7 +184,7 @@ static DOCUMENTATION_ATAN: LazyLock<Documentation> = LazyLock::new(|| {
.with_standard_argument("numeric_expression", Some("Numeric"))
.with_sql_example(
r#"```sql
- > SELECT atan(1);
+> SELECT atan(1);
+-----------+
| atan(1) |
+-----------+
@@ -223,7 +223,7 @@ static DOCUMENTATION_ATANH: LazyLock<Documentation> =
)
.with_standard_argument("numeric_expression", Some("Numeric"))
.with_sql_example(r#"```sql
- > SELECT atanh(0.5);
+> SELECT atanh(0.5);
+-------------+
| atanh(0.5) |
+-------------+
@@ -394,7 +394,7 @@ static DOCUMENTATION_DEGREES: LazyLock<Documentation> = LazyLock::new(|| {
.with_standard_argument("numeric_expression", Some("Numeric"))
.with_sql_example(
r#"```sql
- > SELECT degrees(pi());
+> SELECT degrees(pi());
+------------+
| degrees(0) |
+------------+
@@ -719,12 +719,12 @@ static DOCUMENTATION_TANH: LazyLock<Documentation> = LazyLock::new(|| {
.with_standard_argument("numeric_expression", Some("Numeric"))
.with_sql_example(
r#"```sql
- > SELECT tanh(20);
- +----------+
- | tanh(20) |
- +----------+
- | 1.0 |
- +----------+
+> SELECT tanh(20);
++----------+
+| tanh(20) |
++----------+
+| 1.0 |
++----------+
```"#,
)
.build()
diff --git a/datafusion/functions/src/regex/regexpcount.rs b/datafusion/functions/src/regex/regexpcount.rs
index d970eccc43..40d9ba05e5 100644
--- a/datafusion/functions/src/regex/regexpcount.rs
+++ b/datafusion/functions/src/regex/regexpcount.rs
@@ -36,7 +36,7 @@ use std::sync::Arc;
#[user_doc(
doc_section(label = "Regular Expression Functions"),
description = "Returns the number of matches that a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has in a string.",
- syntax_example = "regexp_count(str, regexp[, start, flags])",
+ syntax_example = "regexp_count(str, regexp[, start[, flags]])",
sql_example = r#"```sql
> select regexp_count('abcAbAbc', 'abc', 2, 'i');
+---------------------------------------------------------------+
@@ -49,16 +49,11 @@ use std::sync::Arc;
standard_argument(name = "regexp", prefix = "Regular"),
argument(
name = "start",
- description = "- **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function."
+ description = "Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function."
),
argument(
name = "flags",
- description = r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?"#
+ description = r#"Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags."#
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/datafusion/functions/src/regex/regexpinstr.rs b/datafusion/functions/src/regex/regexpinstr.rs
index 7bbc4c4602..e8a8f5286b 100644
--- a/datafusion/functions/src/regex/regexpinstr.rs
+++ b/datafusion/functions/src/regex/regexpinstr.rs
@@ -52,20 +52,15 @@ use crate::regex::compile_regex;
standard_argument(name = "regexp", prefix = "Regular"),
argument(
name = "start",
- description = "- **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function. Defaults to 1"
+ description = "Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function. Defaults to 1"
),
argument(
name = "N",
- description = "- **N**: Optional The N-th occurrence of pattern to find. Defaults to 1 (first match). Can be a constant, column, or function."
+ description = "Optional The N-th occurrence of pattern to find. Defaults to 1 (first match). Can be a constant, column, or function."
),
argument(
name = "flags",
- description = r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?"#
+ description = r#"Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags."#
),
argument(
name = "subexpr",
diff --git a/datafusion/functions/src/regex/regexplike.rs b/datafusion/functions/src/regex/regexplike.rs
index 56754b13db..e7b31b767a 100644
--- a/datafusion/functions/src/regex/regexplike.rs
+++ b/datafusion/functions/src/regex/regexplike.rs
@@ -61,12 +61,7 @@ Additional examples can be found [here](https://github.com/apache/datafusion/blo
standard_argument(name = "regexp", prefix = "Regular"),
argument(
name = "flags",
- description = r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?"#
+ description = r#"Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags."#
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/datafusion/functions/src/regex/regexpmatch.rs b/datafusion/functions/src/regex/regexpmatch.rs
index 918de5273b..ce7c437a54 100644
--- a/datafusion/functions/src/regex/regexpmatch.rs
+++ b/datafusion/functions/src/regex/regexpmatch.rs
@@ -57,12 +57,7 @@ Additional examples can be found [here](https://github.com/apache/datafusion/blo
),
argument(
name = "flags",
- description = r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?"#
+ description = r#"Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags."#
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/datafusion/functions/src/regex/regexpreplace.rs b/datafusion/functions/src/regex/regexpreplace.rs
index 215dd33324..ec4afbad47 100644
--- a/datafusion/functions/src/regex/regexpreplace.rs
+++ b/datafusion/functions/src/regex/regexpreplace.rs
@@ -79,13 +79,7 @@ Additional examples can be found [here](https://github.com/apache/datafusion/blo
),
argument(
name = "flags",
- description = r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
-- **g**: (global) Search globally and don't return after the first match
-- **i**: case-insensitive: letters match both upper and lower case
-- **m**: multi-line mode: ^ and $ match begin/end of line
-- **s**: allow . to match \n
-- **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
-- **U**: swap the meaning of x* and x*?"#
+ description = r#"Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags."#
)
)]
#[derive(Debug, PartialEq, Eq, Hash)]
diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md
index 844fd054b0..1bfec4ce43 100644
--- a/docs/source/user-guide/sql/scalar_functions.md
+++ b/docs/source/user-guide/sql/scalar_functions.md
@@ -200,7 +200,7 @@ atan(numeric_expression)
#### Example
```sql
- > SELECT atan(1);
+> SELECT atan(1);
+-----------+
| atan(1) |
+-----------+
@@ -249,7 +249,7 @@ atanh(numeric_expression)
#### Example
```sql
- > SELECT atanh(0.5);
+> SELECT atanh(0.5);
+-------------+
| atanh(0.5) |
+-------------+
@@ -387,7 +387,7 @@ degrees(numeric_expression)
#### Example
```sql
- > SELECT degrees(pi());
+> SELECT degrees(pi());
+------------+
| degrees(0) |
+------------+
@@ -913,12 +913,12 @@ tanh(numeric_expression)
#### Example
```sql
- > SELECT tanh(20);
- +----------+
- | tanh(20) |
- +----------+
- | 1.0 |
- +----------+
+> SELECT tanh(20);
++----------+
+| tanh(20) |
++----------+
+| 1.0 |
++----------+
```
### `trunc`
@@ -2195,6 +2195,15 @@ encode(expression, format)
Apache DataFusion uses a [PCRE-like](https://en.wikibooks.org/wiki/Regular_Expressions/Perl-Compatible_Regular_Expressions)
regular expression [syntax](https://docs.rs/regex/latest/regex/#syntax)
(minus support for several features including look-around and backreferences).
+
+The following flags are optionally supported in functions:
+
+- **i**: case-insensitive: letters match both upper and lower case
+- **m**: multi-line mode: `^` and `$` match begin/end of line
+- **s**: allow `.` to match `\n`
+- **R**: enables CRLF mode: when multi-line mode is enabled, `\r\n` is used
+- **U**: swap the meaning of `x*` and `x*?`
+
The following regular expression functions are supported:
- [regexp_count](#regexp_count)
@@ -2208,20 +2217,15 @@ The following regular expression functions are supported:
Returns the number of matches that a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has in a string.
```sql
-regexp_count(str, regexp[, start, flags])
+regexp_count(str, regexp[, start[, flags]])
```
#### Arguments
- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators.
- **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators.
-- **start**: - **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function.
-- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?
+- **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function.
+- **flags**: Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags.
#### Example
@@ -2246,14 +2250,9 @@ regexp_instr(str, regexp[, start[, N[, flags[, subexpr]]]])
- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators.
- **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators.
-- **start**: - **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function. Defaults to 1
-- **N**: - **N**: Optional The N-th occurrence of pattern to find. Defaults to 1 (first match). Can be a constant, column, or function.
-- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?
+- **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function. Defaults to 1
+- **N**: Optional The N-th occurrence of pattern to find. Defaults to 1 (first match). Can be a constant, column, or function.
+- **flags**: Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags.
- **subexpr**: Optional Specifies which capture group (subexpression) to return the position for. Defaults to 0, which returns the position of the entire match.
#### Example
@@ -2279,12 +2278,7 @@ regexp_like(str, regexp[, flags])
- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators.
- **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators.
-- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?
+- **flags**: Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags.
#### Example
@@ -2318,12 +2312,7 @@ regexp_match(str, regexp[, flags])
- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators.
- **regexp**: Regular expression to match against.
Can be a constant, column, or function.
-- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
- - **i**: case-insensitive: letters match both upper and lower case
- - **m**: multi-line mode: ^ and $ match begin/end of line
- - **s**: allow . to match \n
- - **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
- - **U**: swap the meaning of x* and x*?
+- **flags**: Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags.
#### Example
@@ -2358,13 +2347,7 @@ regexp_replace(str, regexp, replacement[, flags])
- **regexp**: Regular expression to match against.
Can be a constant, column, or function.
- **replacement**: Replacement string expression to operate on. Can be a constant, column, or function, and any combination of operators.
-- **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported:
-- **g**: (global) Search globally and don't return after the first match
-- **i**: case-insensitive: letters match both upper and lower case
-- **m**: multi-line mode: ^ and $ match begin/end of line
-- **s**: allow . to match \n
-- **R**: enables CRLF mode: when multi-line mode is enabled, \r\n is used
-- **U**: swap the meaning of x* and x*?
+- **flags**: Optional regular expression flags that control the behavior of the regular expression. Refer to the flags reference above for supported flags.
#### Example
@@ -2420,8 +2403,6 @@ The `current_date()` return value is determined at query time and will return th
```sql
current_date()
- (optional) SET datafusion.execution.time_zone = '+00:00';
- SELECT current_date();
```
#### Example
@@ -2458,8 +2439,6 @@ The session time zone can be set using the statement 'SET datafusion.execution.t
```sql
current_time()
- (optional) SET datafusion.execution.time_zone = '+00:00';
- SELECT current_time();
```
#### Example
@@ -2493,14 +2472,14 @@ Calculates time intervals and returns the start of the interval nearest to the s
For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`.
```sql
-date_bin(interval, expression, origin-timestamp)
+date_bin(interval, expression[, origin_timestamp])
```
#### Arguments
- **interval**: Bin interval.
- **expression**: Time expression to operate on. Can be a constant, column, or function.
-- **origin-timestamp**: Optional. Starting point used to determine bin boundaries. If not specified defaults 1970-01-01T00:00:00Z (the UNIX epoch in UTC). The following intervals are supported:
+- **origin_timestamp**: Optional. Starting point used to determine bin boundaries. If not specified defaults 1970-01-01T00:00:00Z (the UNIX epoch in UTC). The following intervals are supported:
- nanoseconds
- microseconds
@@ -2813,7 +2792,6 @@ to_char(expression, format)
- **expression**: Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration.
- **format**: A [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) string to use to convert the expression.
-- **day**: Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.
#### Example
@@ -2843,7 +2821,7 @@ Returns the corresponding date.
Note: `to_date` returns Date32, which represents its values as the number of days since unix epoch(`1970-01-01`) stored as signed 32 bit value. The largest supported date value is `9999-12-31`.
```sql
-to_date(expression[, ..., format_n])
+to_date(expression[, format1, ..., format_n])
```
#### Arguments
@@ -2944,7 +2922,7 @@ Returns the corresponding time.
Note: `to_time` returns Time64(Nanosecond), which represents the time of day in nanoseconds since midnight.
```sql
-to_time(expression[, ..., format_n])
+to_time(expression[, format1, ..., format_n])
```
#### Arguments
@@ -3824,26 +3802,26 @@ array_has(array, element)
### `array_has_all`
-Returns true if all elements of sub-array exist in array.
+Returns true if all elements of sub_array exist in array.
```sql
-array_has_all(array, sub-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.
+- **sub_array**: Array expression. Can be a constant, column, or function, and any combination of array operators.
#### Example
```sql
> select array_has_all([1, 2, 3, 4], [2, 3]);
-+--------------------------------------------+
++---------------------------------------------+
| array_has_all(List([1,2,3,4]), List([2,3])) |
-+--------------------------------------------+
-| true |
-+--------------------------------------------+
++---------------------------------------------+
+| true |
++---------------------------------------------+
```
#### Aliases
@@ -3926,13 +3904,13 @@ _Alias of [array_to_string](#array_to_string)._
Returns the length of the array dimension.
```sql
-array_length(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.
+- **dimension**: Array dimension. Default is 1
#### Example
@@ -4004,13 +3982,12 @@ array_min(array)
Returns the number of dimensions of the array.
```sql
-array_ndims(array, element)
+array_ndims(array)
```
#### Arguments
- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators.
-- **element**: Array element.
#### Example
@@ -4113,15 +4090,14 @@ array_pop_front(array)
Returns the position of the first occurrence of the specified element in the array, or NULL if not found. Comparisons are done using `IS DISTINCT FROM` semantics, so NULL is considered to match NULL.
```sql
-array_position(array, element)
-array_position(array, element, index)
+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 in the array.
-- **index**: Index at which to start searching (1-indexed).
+- **index**: Index at which to start searching (1-indexed). Defaults to searching from the start
#### Example
@@ -4469,17 +4445,17 @@ array_replace_n(array, from, to, max)
### `array_resize`
-Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set.
+Resizes the list to contain size elements.
```sql
-array_resize(array, size, value)
+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.
+- **value**: If expanding the array, defines the values to fill in. Defaults to null.
#### Example
@@ -4556,7 +4532,7 @@ array_scale(array, scalar)
Returns a slice of the array based on 1-indexed start and end positions.
```sql
-array_slice(array, begin, end)
+array_slice(array, begin, end[, stride])
```
#### Arguments
@@ -4586,14 +4562,14 @@ array_slice(array, begin, end)
Sort array.
```sql
-array_sort(array, desc, nulls_first)
+array_sort(array[, order[, nulls_order]])
```
#### Arguments
- **array**: Array expression. Can be a constant, column, or function, and any combination of array operators.
-- **desc**: Whether to sort in ascending (`ASC`) or descending (`DESC`) order. The default is `ASC`.
-- **nulls_first**: Whether to sort nulls first (`NULLS FIRST`) or last (`NULLS LAST`). The default is `NULLS FIRST`.
+- **order**: Whether to sort in ascending (`ASC`) or descending (`DESC`) order. The default is `ASC`.
+- **nulls_order**: Whether to sort nulls first (`NULLS FIRST`) or last (`NULLS LAST`). The default is `NULLS FIRST`.
#### Example
@@ -4604,6 +4580,12 @@ array_sort(array, desc, nulls_first)
+-----------------------------+
| [1, 2, 3] |
+-----------------------------+
+> select array_sort([3, 1, NULL, 2], 'desc', 'nulls last');
++--------------------------------------------------+
+| array_sort(List(3,1,NULL,2),'desc','nulls last') |
++--------------------------------------------------+
+| [3, 2, 1, NULL] |
++--------------------------------------------------+
```
#### Aliases
@@ -5178,7 +5160,7 @@ _Alias of [arrays_zip](#arrays_zip)._
Returns an array using the specified input expressions.
```sql
-make_array(expression1[, ..., expression_n])
+make_array([expression1, ..., expression_n])
```
#### Arguments
@@ -5397,7 +5379,7 @@ The `make_map` function creates a map from two lists: one for keys and one for v
```sql
map(key, value)
-map(key: value)
+map {key: value}
make_map(['key1', 'key2'], ['value1', 'value2'])
```