This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-23212-70c26a06716eb552f0fc1d2115957a4089504f11 in repository https://gitbox.apache.org/repos/asf/datafusion.git
commit 4fcbfb1306d711163d9f7a282ea8968156bb7eb9 Author: Victorien <[email protected]> AuthorDate: Thu Aug 6 14:52:37 2026 +0200 Fix syntax examples of some functions (#23212) Almost all the datafusion functions uses a consistent format for the `syntax_example` which describes the expected signature of the function (that is, `func_name(arg1, arg2 [, optional_arg])`, apart from some functions with specific syntax, e.g. [`array_agg(expression [ORDER BY expression])`](https://datafusion.apache.org/user-guide/sql/aggregate_functions.html#array-agg)). I'm trying to programmatically parse this syntax and map it to the `argument` `user_doc` directive, but some of them weren't following the same pattern. Also properly document the `lambda` parameter of `array_transform`. --------- Co-authored-by: Jeffrey Vo <[email protected]> --- datafusion/functions-nested/src/array_transform.rs | 7 +++++-- datafusion/functions/src/datetime/to_date.rs | 2 +- datafusion/functions/src/datetime/to_time.rs | 2 +- datafusion/macros/src/user_doc.rs | 4 ++-- docs/source/user-guide/sql/scalar_functions.md | 8 ++++---- 5 files changed, 13 insertions(+), 10 deletions(-) diff --git a/datafusion/functions-nested/src/array_transform.rs b/datafusion/functions-nested/src/array_transform.rs index 1c1c507734..e07952722e 100644 --- a/datafusion/functions-nested/src/array_transform.rs +++ b/datafusion/functions-nested/src/array_transform.rs @@ -50,7 +50,7 @@ make_higher_order_function_expr_and_func!( #[user_doc( doc_section(label = "Array Functions"), description = "transforms the values of an array", - syntax_example = "array_transform(array, x -> x*2)", + syntax_example = "array_transform(array, lambda)", sql_example = r#"```sql > select array_transform([1, 2, 3, 4, 5], x -> x*2); +-------------------------------------------+ @@ -63,7 +63,10 @@ make_higher_order_function_expr_and_func!( name = "array", description = "Array expression. Can be a constant, column, or function, and any combination of array operators." ), - argument(name = "lambda", description = "Lambda") + argument( + name = "lambda", + description = "The lambda function used to transform each value of the array." + ) )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct ArrayTransform { diff --git a/datafusion/functions/src/datetime/to_date.rs b/datafusion/functions/src/datetime/to_date.rs index e0a14e056a..37190f6a4a 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('2017-05-31', '%Y-%m-%d')", + syntax_example = "to_date(expression[, ..., 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 45664e9416..696f25dad9 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('12:30:45', '%H:%M:%S')", + syntax_example = "to_time(expression[, ..., format_n])", sql_example = r#"```sql > select to_time('12:30:45'); +---------------------------+ diff --git a/datafusion/macros/src/user_doc.rs b/datafusion/macros/src/user_doc.rs index ce9e7d55ef..2dde56a4ff 100644 --- a/datafusion/macros/src/user_doc.rs +++ b/datafusion/macros/src/user_doc.rs @@ -38,7 +38,7 @@ use syn::{DeriveInput, LitStr, parse_macro_input}; /// #[user_doc( /// doc_section(label = "Time and Date Functions"), /// description = r"Converts a value to a date (`YYYY-MM-DD`).", -/// syntax_example = "to_date('2017-05-31', '%Y-%m-%d')", +/// syntax_example = "to_date(expression[, ..., format_n])", /// sql_example = r#"```sql /// > select to_date('2023-01-31'); /// +-----------------------------+ @@ -77,7 +77,7 @@ use syn::{DeriveInput, LitStr, parse_macro_input}; /// description: None, /// }, /// r"Converts a value to a date (`YYYY-MM-DD`).".to_string(), -/// "to_date('2017-05-31', '%Y-%m-%d')".to_string(), +/// "to_date(expression[, ..., format_n])".to_string(), /// ) /// .with_sql_example( /// r#"```sql diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index e63ec0654c..844fd054b0 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -2843,7 +2843,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('2017-05-31', '%Y-%m-%d') +to_date(expression[, ..., format_n]) ``` #### Arguments @@ -2944,7 +2944,7 @@ Returns the corresponding time. Note: `to_time` returns Time64(Nanosecond), which represents the time of day in nanoseconds since midnight. ```sql -to_time('12:30:45', '%H:%M:%S') +to_time(expression[, ..., format_n]) ``` #### Arguments @@ -4701,13 +4701,13 @@ array_to_string(array, delimiter[, null_string]) transforms the values of an array ```sql -array_transform(array, x -> x*2) +array_transform(array, lambda) ``` #### Arguments - **array**: Array expression. Can be a constant, column, or function, and any combination of array operators. -- **lambda**: Lambda +- **lambda**: The lambda function used to transform each value of the array. #### Example --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
