From d46f13584ce3a9f3b4a9020f3c1bfb2104fce8ca Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Mon, 14 Oct 2024 17:12:49 -0400 Subject: [PATCH 1/8] Added default value to 'with_standard_argument' --- datafusion/expr/src/udf_docs.rs | 24 +++++++++++++++---- .../functions-aggregate/src/bit_and_or_xor.rs | 6 ++--- .../functions-aggregate/src/bool_and_or.rs | 8 ++++--- .../functions-aggregate/src/nth_value.rs | 2 +- .../functions-aggregate/src/variance.rs | 4 ++-- datafusion/functions/src/crypto/digest.rs | 2 +- datafusion/functions/src/crypto/md5.rs | 2 +- datafusion/functions/src/crypto/sha224.rs | 2 +- datafusion/functions/src/crypto/sha256.rs | 2 +- datafusion/functions/src/crypto/sha384.rs | 2 +- datafusion/functions/src/datetime/to_date.rs | 2 +- datafusion/functions/src/math/log.rs | 4 ++-- datafusion/functions/src/regex/regexplike.rs | 4 ++-- datafusion/functions/src/string/ascii.rs | 2 +- datafusion/functions/src/string/bit_length.rs | 2 +- datafusion/functions/src/string/btrim.rs | 2 +- datafusion/functions/src/string/chr.rs | 2 +- datafusion/functions/src/string/concat.rs | 2 +- datafusion/functions/src/string/concat_ws.rs | 4 ++-- datafusion/functions/src/string/contains.rs | 2 +- datafusion/functions/src/string/ends_with.rs | 2 +- datafusion/functions/src/string/initcap.rs | 2 +- datafusion/functions/src/string/lower.rs | 2 +- datafusion/functions/src/string/ltrim.rs | 2 +- .../functions/src/string/octet_length.rs | 2 +- datafusion/functions/src/string/overlay.rs | 2 +- datafusion/functions/src/string/repeat.rs | 2 +- datafusion/functions/src/string/replace.rs | 6 ++--- datafusion/functions/src/string/rtrim.rs | 2 +- datafusion/functions/src/string/split_part.rs | 2 +- .../functions/src/string/starts_with.rs | 2 +- datafusion/functions/src/string/to_hex.rs | 2 +- datafusion/functions/src/string/upper.rs | 2 +- .../functions/src/unicode/character_length.rs | 2 +- datafusion/functions/src/unicode/left.rs | 2 +- datafusion/functions/src/unicode/lpad.rs | 2 +- datafusion/functions/src/unicode/reverse.rs | 2 +- datafusion/functions/src/unicode/right.rs | 2 +- datafusion/functions/src/unicode/rpad.rs | 2 +- datafusion/functions/src/unicode/strpos.rs | 2 +- datafusion/functions/src/unicode/substr.rs | 2 +- .../functions/src/unicode/substrindex.rs | 2 +- datafusion/functions/src/unicode/translate.rs | 2 +- 43 files changed, 73 insertions(+), 57 deletions(-) diff --git a/datafusion/expr/src/udf_docs.rs b/datafusion/expr/src/udf_docs.rs index e0ce7526036e..fd2225c7d3ed 100644 --- a/datafusion/expr/src/udf_docs.rs +++ b/datafusion/expr/src/udf_docs.rs @@ -149,21 +149,35 @@ impl DocumentationBuilder { /// /// This is similar to [`Self::with_argument`] except that a standard /// description is appended to the end: `"Can be a constant, column, or - /// function, and any combination of arithmetic operators."` + /// function, and any combination of arithmetic operators."` There is + /// also a default option for if the argument was "expression". /// - /// The argument is rendered like + /// The argument is rendered like below if Some() is passed through: /// /// ```text /// : /// expression to operate on. Can be a constant, column, or function, and any combination of operators. /// ``` + /// + /// The argument is rendered like below if None is passed through: + /// + /// ```text + /// : + /// The expression to operate on. Can be a constant, column, or function, and any combination of operators. + /// ``` pub fn with_standard_argument( self, arg_name: impl Into, - expression_type: impl AsRef, + expression_type: Option<&str>, // Changed from Option ) -> Self { - let expression_type = expression_type.as_ref(); - self.with_argument(arg_name, format!("{expression_type} expression to operate on. Can be a constant, column, or function, and any combination of operators.")) + let description = match expression_type { + Some(expr_type) => format!( + "{} expression to operate on. Can be a constant, column, or function, and any combination of operators.", + expr_type + ), + None => "The expression to operate on. Can be a constant, column, or function, and any combination of operators.".to_string(), + }; + self.with_argument(arg_name, description) } pub fn with_related_udf(mut self, related_udf: impl Into) -> Self { diff --git a/datafusion/functions-aggregate/src/bit_and_or_xor.rs b/datafusion/functions-aggregate/src/bit_and_or_xor.rs index c5382c168f17..0a281ad81467 100644 --- a/datafusion/functions-aggregate/src/bit_and_or_xor.rs +++ b/datafusion/functions-aggregate/src/bit_and_or_xor.rs @@ -142,7 +142,7 @@ fn get_bit_and_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_GENERAL) .with_description("Computes the bitwise AND of all non-null input values.") .with_syntax_example("bit_and(expression)") - .with_standard_argument("expression", "Integer") + .with_standard_argument("expression", Some("Integer")) .build() .unwrap() }) @@ -156,7 +156,7 @@ fn get_bit_or_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_GENERAL) .with_description("Computes the bitwise OR of all non-null input values.") .with_syntax_example("bit_or(expression)") - .with_standard_argument("expression", "Integer") + .with_standard_argument("expression", Some("Integer")) .build() .unwrap() }) @@ -172,7 +172,7 @@ fn get_bit_xor_doc() -> &'static Documentation { "Computes the bitwise exclusive OR of all non-null input values.", ) .with_syntax_example("bit_xor(expression)") - .with_standard_argument("expression", "Integer") + .with_standard_argument("expression", Some("Integer")) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/bool_and_or.rs b/datafusion/functions-aggregate/src/bool_and_or.rs index e212ba8d6172..e176177a51b2 100644 --- a/datafusion/functions-aggregate/src/bool_and_or.rs +++ b/datafusion/functions-aggregate/src/bool_and_or.rs @@ -338,15 +338,17 @@ fn get_bool_or_doc() -> &'static Documentation { "Returns true if any non-null input value is true, otherwise false.", ) .with_syntax_example("bool_or(expression)") - .with_sql_example(r#"```sql + .with_sql_example( + r#"```sql > SELECT bool_or(column_name) FROM table_name; +----------------------------+ | bool_or(column_name) | +----------------------------+ | true | +----------------------------+ -```"#) - .with_standard_argument("expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.") +```"#, + ) + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/nth_value.rs b/datafusion/functions-aggregate/src/nth_value.rs index 6d8cea8f0531..dbdd75c7b5f1 100644 --- a/datafusion/functions-aggregate/src/nth_value.rs +++ b/datafusion/functions-aggregate/src/nth_value.rs @@ -191,7 +191,7 @@ fn get_nth_value_doc() -> &'static Documentation { | 2 | 45000 | 45000 | +---------+--------+-------------------------+ ```"#) - .with_standard_argument("expression", "The column or expression to retrieve the nth value from.") + .with_standard_argument("expression", Some("The column or expression to retrieve the nth value from.")) .with_argument("n", "The position (nth) of the value to retrieve, based on the ordering.") .build() .unwrap() diff --git a/datafusion/functions-aggregate/src/variance.rs b/datafusion/functions-aggregate/src/variance.rs index 49a30344c212..8453c9d3010b 100644 --- a/datafusion/functions-aggregate/src/variance.rs +++ b/datafusion/functions-aggregate/src/variance.rs @@ -153,7 +153,7 @@ fn get_variance_sample_doc() -> &'static Documentation { "Returns the statistical sample variance of a set of numbers.", ) .with_syntax_example("var(expression)") - .with_standard_argument("expression", "Numeric") + .with_standard_argument("expression", Some("Numeric")) .build() .unwrap() }) @@ -259,7 +259,7 @@ fn get_variance_population_doc() -> &'static Documentation { "Returns the statistical population variance of a set of numbers.", ) .with_syntax_example("var_pop(expression)") - .with_standard_argument("expression", "Numeric") + .with_standard_argument("expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/crypto/digest.rs b/datafusion/functions/src/crypto/digest.rs index 9ec07b1cab53..0e43fb7785df 100644 --- a/datafusion/functions/src/crypto/digest.rs +++ b/datafusion/functions/src/crypto/digest.rs @@ -98,7 +98,7 @@ fn get_digest_doc() -> &'static Documentation { ```"#, ) .with_standard_argument( - "expression", "String") + "expression", Some("String")) .with_argument( "algorithm", "String expression specifying algorithm to use. Must be one of: diff --git a/datafusion/functions/src/crypto/md5.rs b/datafusion/functions/src/crypto/md5.rs index f273c9d28c23..062d63bcc018 100644 --- a/datafusion/functions/src/crypto/md5.rs +++ b/datafusion/functions/src/crypto/md5.rs @@ -112,7 +112,7 @@ fn get_md5_doc() -> &'static Documentation { +-------------------------------------+ ```"#, ) - .with_standard_argument("expression", "String") + .with_standard_argument("expression", Some("String")) .build() .unwrap() }) diff --git a/datafusion/functions/src/crypto/sha224.rs b/datafusion/functions/src/crypto/sha224.rs index 868c8cdc3558..39202d5bf691 100644 --- a/datafusion/functions/src/crypto/sha224.rs +++ b/datafusion/functions/src/crypto/sha224.rs @@ -68,7 +68,7 @@ fn get_sha224_doc() -> &'static Documentation { +------------------------------------------+ ```"#, ) - .with_standard_argument("expression", "String") + .with_standard_argument("expression", Some("String")) .build() .unwrap() }) diff --git a/datafusion/functions/src/crypto/sha256.rs b/datafusion/functions/src/crypto/sha256.rs index 99a470efbc1f..74deb3fc6caa 100644 --- a/datafusion/functions/src/crypto/sha256.rs +++ b/datafusion/functions/src/crypto/sha256.rs @@ -92,7 +92,7 @@ fn get_sha256_doc() -> &'static Documentation { +--------------------------------------+ ```"#, ) - .with_standard_argument("expression", "String") + .with_standard_argument("expression", Some("String")) .build() .unwrap() }) diff --git a/datafusion/functions/src/crypto/sha384.rs b/datafusion/functions/src/crypto/sha384.rs index afe2db7478f7..9b1e1ba9ec3c 100644 --- a/datafusion/functions/src/crypto/sha384.rs +++ b/datafusion/functions/src/crypto/sha384.rs @@ -92,7 +92,7 @@ fn get_sha384_doc() -> &'static Documentation { +-----------------------------------------+ ```"#, ) - .with_standard_argument("expression", "String") + .with_standard_argument("expression", Some("String")) .build() .unwrap() }) diff --git a/datafusion/functions/src/datetime/to_date.rs b/datafusion/functions/src/datetime/to_date.rs index 2803fd042b99..439686029b0b 100644 --- a/datafusion/functions/src/datetime/to_date.rs +++ b/datafusion/functions/src/datetime/to_date.rs @@ -111,7 +111,7 @@ Note: `to_date` returns Date32, which represents its values as the number of day Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs) "#) - .with_standard_argument("expression", "String") + .with_standard_argument("expression", Some("String")) .with_argument( "format_n", "Optional [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) strings to use to parse the expression. Formats will be tried in the order diff --git a/datafusion/functions/src/math/log.rs b/datafusion/functions/src/math/log.rs index 07ff8e2166ff..89ba14e32ba0 100644 --- a/datafusion/functions/src/math/log.rs +++ b/datafusion/functions/src/math/log.rs @@ -57,8 +57,8 @@ fn get_log_doc() -> &'static Documentation { .with_description("Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number.") .with_syntax_example(r#"log(base, numeric_expression) log(numeric_expression)"#) - .with_standard_argument("base", "Base numeric") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("base", Some("Base numeric")) + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/regex/regexplike.rs b/datafusion/functions/src/regex/regexplike.rs index a698913fff54..5982ce61c132 100644 --- a/datafusion/functions/src/regex/regexplike.rs +++ b/datafusion/functions/src/regex/regexplike.rs @@ -66,8 +66,8 @@ SELECT regexp_like('aBc', '(b|d)', 'i'); ``` Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) "#) - .with_standard_argument("str", "String") - .with_standard_argument("regexp","Regular") + .with_standard_argument("str", Some("String")) + .with_standard_argument("regexp", Some("Regular")) .with_argument("flags", 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 diff --git a/datafusion/functions/src/string/ascii.rs b/datafusion/functions/src/string/ascii.rs index 8d61661f97b8..b76d70d7e9d2 100644 --- a/datafusion/functions/src/string/ascii.rs +++ b/datafusion/functions/src/string/ascii.rs @@ -99,7 +99,7 @@ fn get_ascii_doc() -> &'static Documentation { +-------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("chr") .build() .unwrap() diff --git a/datafusion/functions/src/string/bit_length.rs b/datafusion/functions/src/string/bit_length.rs index 7d162e7d411b..25b56341fcaa 100644 --- a/datafusion/functions/src/string/bit_length.rs +++ b/datafusion/functions/src/string/bit_length.rs @@ -107,7 +107,7 @@ fn get_bit_length_doc() -> &'static Documentation { +--------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("length") .with_related_udf("octet_length") .build() diff --git a/datafusion/functions/src/string/btrim.rs b/datafusion/functions/src/string/btrim.rs index 82b7599f0735..f689f27d9d24 100644 --- a/datafusion/functions/src/string/btrim.rs +++ b/datafusion/functions/src/string/btrim.rs @@ -122,7 +122,7 @@ fn get_btrim_doc() -> &'static Documentation { | datafusion | +-------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("trim_str", "String expression to operate on. Can be a constant, column, or function, and any combination of operators. _Default is whitespace characters._") .with_related_udf("ltrim") .with_related_udf("rtrim") diff --git a/datafusion/functions/src/string/chr.rs b/datafusion/functions/src/string/chr.rs index ae0900af37d3..0d94cab08d91 100644 --- a/datafusion/functions/src/string/chr.rs +++ b/datafusion/functions/src/string/chr.rs @@ -125,7 +125,7 @@ fn get_chr_doc() -> &'static Documentation { +--------------------+ ```"#, ) - .with_standard_argument("expression", "String") + .with_standard_argument("expression", Some("String")) .with_related_udf("ascii") .build() .unwrap() diff --git a/datafusion/functions/src/string/concat.rs b/datafusion/functions/src/string/concat.rs index 228fcd460c97..6d6ecea0047d 100644 --- a/datafusion/functions/src/string/concat.rs +++ b/datafusion/functions/src/string/concat.rs @@ -268,7 +268,7 @@ fn get_concat_doc() -> &'static Documentation { +-------------------------------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("str_n", "Subsequent string expressions to concatenate.") .with_related_udf("concat_ws") .build() diff --git a/datafusion/functions/src/string/concat_ws.rs b/datafusion/functions/src/string/concat_ws.rs index a20cbf1a16f5..c26635a7bd9d 100644 --- a/datafusion/functions/src/string/concat_ws.rs +++ b/datafusion/functions/src/string/concat_ws.rs @@ -295,10 +295,10 @@ fn get_concat_ws_doc() -> &'static Documentation { "separator", "Separator to insert between concatenated strings.", ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_standard_argument( "str_n", - "Subsequent string expressions to concatenate.", + Some("Subsequent string expressions to concatenate."), ) .with_related_udf("concat") .build() diff --git a/datafusion/functions/src/string/contains.rs b/datafusion/functions/src/string/contains.rs index 0f75731aa1c3..b0bfc66a214c 100644 --- a/datafusion/functions/src/string/contains.rs +++ b/datafusion/functions/src/string/contains.rs @@ -95,7 +95,7 @@ fn get_contains_doc() -> &'static Documentation { +---------------------------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("search_str", "The string to search for in str.") .build() .unwrap() diff --git a/datafusion/functions/src/string/ends_with.rs b/datafusion/functions/src/string/ends_with.rs index 8c90cbc3b146..88978a35c0b7 100644 --- a/datafusion/functions/src/string/ends_with.rs +++ b/datafusion/functions/src/string/ends_with.rs @@ -103,7 +103,7 @@ fn get_ends_with_doc() -> &'static Documentation { +--------------------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("substr", "Substring to test for.") .build() .unwrap() diff --git a/datafusion/functions/src/string/initcap.rs b/datafusion/functions/src/string/initcap.rs index 78c95b9a5e35..5fd1e7929881 100644 --- a/datafusion/functions/src/string/initcap.rs +++ b/datafusion/functions/src/string/initcap.rs @@ -96,7 +96,7 @@ fn get_initcap_doc() -> &'static Documentation { | Apache Datafusion | +------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("lower") .with_related_udf("upper") .build() diff --git a/datafusion/functions/src/string/lower.rs b/datafusion/functions/src/string/lower.rs index f82b11ca9051..b07189a832dc 100644 --- a/datafusion/functions/src/string/lower.rs +++ b/datafusion/functions/src/string/lower.rs @@ -89,7 +89,7 @@ fn get_lower_doc() -> &'static Documentation { +-------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("initcap") .with_related_udf("upper") .build() diff --git a/datafusion/functions/src/string/ltrim.rs b/datafusion/functions/src/string/ltrim.rs index b64dcda7218e..91809d691647 100644 --- a/datafusion/functions/src/string/ltrim.rs +++ b/datafusion/functions/src/string/ltrim.rs @@ -122,7 +122,7 @@ fn get_ltrim_doc() -> &'static Documentation { | datafusion___ | +-------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("trim_str", "String expression to trim from the beginning of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._") .with_related_udf("btrim") .with_related_udf("rtrim") diff --git a/datafusion/functions/src/string/octet_length.rs b/datafusion/functions/src/string/octet_length.rs index 04094396fadc..2ac2bf70da23 100644 --- a/datafusion/functions/src/string/octet_length.rs +++ b/datafusion/functions/src/string/octet_length.rs @@ -110,7 +110,7 @@ fn get_octet_length_doc() -> &'static Documentation { +--------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("bit_length") .with_related_udf("length") .build() diff --git a/datafusion/functions/src/string/overlay.rs b/datafusion/functions/src/string/overlay.rs index 3b31bc360851..796776304f4a 100644 --- a/datafusion/functions/src/string/overlay.rs +++ b/datafusion/functions/src/string/overlay.rs @@ -108,7 +108,7 @@ fn get_overlay_doc() -> &'static Documentation { | Thomas | +--------------------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("substr", "Substring to replace in str.") .with_argument("pos", "The start position to start the replace in str.") .with_argument("count", "The count of characters to be replaced from start position of str. If not specified, will use substr length instead.") diff --git a/datafusion/functions/src/string/repeat.rs b/datafusion/functions/src/string/repeat.rs index fda9c7a13df6..e0a3e78381ee 100644 --- a/datafusion/functions/src/string/repeat.rs +++ b/datafusion/functions/src/string/repeat.rs @@ -107,7 +107,7 @@ fn get_repeat_doc() -> &'static Documentation { +-------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("n", "Number of times to repeat the input string.") .build() .unwrap() diff --git a/datafusion/functions/src/string/replace.rs b/datafusion/functions/src/string/replace.rs index 612cd7276bab..d510dc6f9a80 100644 --- a/datafusion/functions/src/string/replace.rs +++ b/datafusion/functions/src/string/replace.rs @@ -96,9 +96,9 @@ fn get_replace_doc() -> &'static Documentation { | ABcdbaBA | +-------------------------------------------------+ ```"#) - .with_standard_argument("str", "String") - .with_standard_argument("substr", "Substring expression to replace in the input string. Substring expression") - .with_standard_argument("replacement", "Replacement substring") + .with_standard_argument("str", Some("String")) + .with_standard_argument("substr", Some("Substring expression to replace in the input string. Substring expression")) + .with_standard_argument("replacement", Some("Replacement substring")) .build() .unwrap() }) diff --git a/datafusion/functions/src/string/rtrim.rs b/datafusion/functions/src/string/rtrim.rs index 1a27502a2082..06c8a85c38dd 100644 --- a/datafusion/functions/src/string/rtrim.rs +++ b/datafusion/functions/src/string/rtrim.rs @@ -122,7 +122,7 @@ fn get_rtrim_doc() -> &'static Documentation { | ___datafusion | +-------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("trim_str", "String expression to trim from the end of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._") .with_related_udf("btrim") .with_related_udf("ltrim") diff --git a/datafusion/functions/src/string/split_part.rs b/datafusion/functions/src/string/split_part.rs index 2441798c38d4..6898cf4124f8 100644 --- a/datafusion/functions/src/string/split_part.rs +++ b/datafusion/functions/src/string/split_part.rs @@ -199,7 +199,7 @@ fn get_split_part_doc() -> &'static Documentation { | 3 | +--------------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("delimiter", "String or character to split on.") .with_argument("pos", "Position of the part to return.") .build() diff --git a/datafusion/functions/src/string/starts_with.rs b/datafusion/functions/src/string/starts_with.rs index 713b642d5e91..dce161a2e14b 100644 --- a/datafusion/functions/src/string/starts_with.rs +++ b/datafusion/functions/src/string/starts_with.rs @@ -102,7 +102,7 @@ fn get_starts_with_doc() -> &'static Documentation { +----------------------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("substr", "Substring to test for.") .build() .unwrap() diff --git a/datafusion/functions/src/string/to_hex.rs b/datafusion/functions/src/string/to_hex.rs index 72cd4fbffa33..e0033d2d1cb0 100644 --- a/datafusion/functions/src/string/to_hex.rs +++ b/datafusion/functions/src/string/to_hex.rs @@ -134,7 +134,7 @@ fn get_to_hex_doc() -> &'static Documentation { +-------------------------+ ```"#, ) - .with_standard_argument("int", "Integer") + .with_standard_argument("int", Some("Integer")) .build() .unwrap() }) diff --git a/datafusion/functions/src/string/upper.rs b/datafusion/functions/src/string/upper.rs index bfcb2a86994d..042c26b2e3da 100644 --- a/datafusion/functions/src/string/upper.rs +++ b/datafusion/functions/src/string/upper.rs @@ -88,7 +88,7 @@ fn get_upper_doc() -> &'static Documentation { +---------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("initcap") .with_related_udf("lower") .build() diff --git a/datafusion/functions/src/unicode/character_length.rs b/datafusion/functions/src/unicode/character_length.rs index bfb60bfbe259..17e223261dce 100644 --- a/datafusion/functions/src/unicode/character_length.rs +++ b/datafusion/functions/src/unicode/character_length.rs @@ -103,7 +103,7 @@ fn get_character_length_doc() -> &'static Documentation { +------------------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_related_udf("bit_length") .with_related_udf("octet_length") .build() diff --git a/datafusion/functions/src/unicode/left.rs b/datafusion/functions/src/unicode/left.rs index 6610cfb25e79..a6c2b9768f0b 100644 --- a/datafusion/functions/src/unicode/left.rs +++ b/datafusion/functions/src/unicode/left.rs @@ -115,7 +115,7 @@ fn get_left_doc() -> &'static Documentation { | data | +-----------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("n", "Number of characters to return.") .with_related_udf("right") .build() diff --git a/datafusion/functions/src/unicode/lpad.rs b/datafusion/functions/src/unicode/lpad.rs index 48bd583720aa..a87470b8f64f 100644 --- a/datafusion/functions/src/unicode/lpad.rs +++ b/datafusion/functions/src/unicode/lpad.rs @@ -119,7 +119,7 @@ fn get_lpad_doc() -> &'static Documentation { | helloDolly | +---------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("n", "String length to pad to.") .with_argument("padding_str", "Optional string expression to pad with. Can be a constant, column, or function, and any combination of string operators. _Default is a space._") .with_related_udf("rpad") diff --git a/datafusion/functions/src/unicode/reverse.rs b/datafusion/functions/src/unicode/reverse.rs index 32872c28a613..baf3b56636e2 100644 --- a/datafusion/functions/src/unicode/reverse.rs +++ b/datafusion/functions/src/unicode/reverse.rs @@ -105,7 +105,7 @@ fn get_reverse_doc() -> &'static Documentation { +-----------------------------+ ```"#, ) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .build() .unwrap() }) diff --git a/datafusion/functions/src/unicode/right.rs b/datafusion/functions/src/unicode/right.rs index 585611fe60e4..ab3b7ba1a27e 100644 --- a/datafusion/functions/src/unicode/right.rs +++ b/datafusion/functions/src/unicode/right.rs @@ -115,7 +115,7 @@ fn get_right_doc() -> &'static Documentation { | fusion | +------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("n", "Number of characters to return") .with_related_udf("left") .build() diff --git a/datafusion/functions/src/unicode/rpad.rs b/datafusion/functions/src/unicode/rpad.rs index 9ca65e229c0c..cf9bd769c03a 100644 --- a/datafusion/functions/src/unicode/rpad.rs +++ b/datafusion/functions/src/unicode/rpad.rs @@ -140,7 +140,7 @@ fn get_rpad_doc() -> &'static Documentation { ```"#) .with_standard_argument( "str", - "String", + Some("String"), ) .with_argument("n", "String length to pad to.") .with_argument("padding_str", diff --git a/datafusion/functions/src/unicode/strpos.rs b/datafusion/functions/src/unicode/strpos.rs index 660adc7578a5..c225f44f25c1 100644 --- a/datafusion/functions/src/unicode/strpos.rs +++ b/datafusion/functions/src/unicode/strpos.rs @@ -95,7 +95,7 @@ fn get_strpos_doc() -> &'static Documentation { | 5 | +----------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("substr", "Substring expression to search for.") .build() .unwrap() diff --git a/datafusion/functions/src/unicode/substr.rs b/datafusion/functions/src/unicode/substr.rs index 969969ef2f6f..b4afef5cacac 100644 --- a/datafusion/functions/src/unicode/substr.rs +++ b/datafusion/functions/src/unicode/substr.rs @@ -170,7 +170,7 @@ fn get_substr_doc() -> &'static Documentation { | fus | +----------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("start_pos", "Character position to start the substring at. The first character in the string has a position of 1.") .with_argument("length", "Number of characters to extract. If not specified, returns the rest of the string after the start position.") .build() diff --git a/datafusion/functions/src/unicode/substrindex.rs b/datafusion/functions/src/unicode/substrindex.rs index 436d554a49f7..c04839783f58 100644 --- a/datafusion/functions/src/unicode/substrindex.rs +++ b/datafusion/functions/src/unicode/substrindex.rs @@ -115,7 +115,7 @@ If count is negative, everything to the right of the final delimiter (counting f | org | +----------------------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("delim", "The string to find in str to split str.") .with_argument("count", "The number of times to search for the delimiter. Can be either a positive or negative number.") .build() diff --git a/datafusion/functions/src/unicode/translate.rs b/datafusion/functions/src/unicode/translate.rs index cbee9a6fe1f2..fa626b396b3b 100644 --- a/datafusion/functions/src/unicode/translate.rs +++ b/datafusion/functions/src/unicode/translate.rs @@ -101,7 +101,7 @@ fn get_translate_doc() -> &'static Documentation { | there | +--------------------------------------------------+ ```"#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("chars", "Characters to translate.") .with_argument("translation", "Translation characters. Translation characters replace only characters at the same position in the **chars** string.") .build() From fc8e8724fcba2719d5ef22b697e436fa7de71451 Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Mon, 14 Oct 2024 17:39:55 -0400 Subject: [PATCH 2/8] small fix --- datafusion/functions/src/regex/regexpmatch.rs | 2 +- datafusion/functions/src/regex/regexpreplace.rs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/datafusion/functions/src/regex/regexpmatch.rs b/datafusion/functions/src/regex/regexpmatch.rs index 443e50533268..7a7c9fc518a7 100644 --- a/datafusion/functions/src/regex/regexpmatch.rs +++ b/datafusion/functions/src/regex/regexpmatch.rs @@ -137,7 +137,7 @@ fn get_regexp_match_doc() -> &'static Documentation { ``` Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) "#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("regexp","Regular expression to match against. Can be a constant, column, or function.") .with_argument("flags", diff --git a/datafusion/functions/src/regex/regexpreplace.rs b/datafusion/functions/src/regex/regexpreplace.rs index 279e5c6ba9dd..4d8e5e5fe3e3 100644 --- a/datafusion/functions/src/regex/regexpreplace.rs +++ b/datafusion/functions/src/regex/regexpreplace.rs @@ -154,10 +154,10 @@ SELECT regexp_replace('aBc', '(b|d)', 'Ab\\1a', 'i'); ``` Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) "#) - .with_standard_argument("str", "String") + .with_standard_argument("str", Some("String")) .with_argument("regexp","Regular expression to match against. Can be a constant, column, or function.") - .with_standard_argument("replacement", "Replacement string") + .with_standard_argument("replacement", Some("Replacement string")) .with_argument("flags", 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 From 4bcbe46b0d30b9ec431a6363a2e2bdd9f808f9c8 Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Mon, 14 Oct 2024 21:18:08 -0400 Subject: [PATCH 3/8] change function --- datafusion/expr/src/udf_docs.rs | 18 +++++------------- .../functions-aggregate/src/nth_value.rs | 2 +- datafusion/functions/src/string/replace.rs | 2 +- .../user-guide/sql/aggregate_functions_new.md | 2 +- .../user-guide/sql/scalar_functions_new.md | 2 +- 5 files changed, 9 insertions(+), 17 deletions(-) diff --git a/datafusion/expr/src/udf_docs.rs b/datafusion/expr/src/udf_docs.rs index ee072575fe82..63d1a964345d 100644 --- a/datafusion/expr/src/udf_docs.rs +++ b/datafusion/expr/src/udf_docs.rs @@ -147,11 +147,6 @@ impl DocumentationBuilder { /// Add a standard "expression" argument to the documentation /// - /// This is similar to [`Self::with_argument`] except that a standard - /// description is appended to the end: `"Can be a constant, column, or - /// function, and any combination of arithmetic operators."` There is - /// also a default option for if the argument was "expression". - /// /// The argument is rendered like below if Some() is passed through: /// /// ```text @@ -168,15 +163,12 @@ impl DocumentationBuilder { pub fn with_standard_argument( self, arg_name: impl Into, - expression_type: Option<&str>, // Changed from Option + expression_type: Option<&str>, ) -> Self { - let description = match expression_type { - Some(expr_type) => format!( - "{} expression to operate on. Can be a constant, column, or function, and any combination of operators.", - expr_type - ), - None => "The expression to operate on. Can be a constant, column, or function, and any combination of operators.".to_string(), - }; + let description = format!( + "{} expression to operate on. Can be a constant, column, or function, and any combination of operators.", + expression_type.unwrap_or("The") + ); self.with_argument(arg_name, description) } diff --git a/datafusion/functions-aggregate/src/nth_value.rs b/datafusion/functions-aggregate/src/nth_value.rs index dbdd75c7b5f1..3e7f51af5265 100644 --- a/datafusion/functions-aggregate/src/nth_value.rs +++ b/datafusion/functions-aggregate/src/nth_value.rs @@ -191,7 +191,7 @@ fn get_nth_value_doc() -> &'static Documentation { | 2 | 45000 | 45000 | +---------+--------+-------------------------+ ```"#) - .with_standard_argument("expression", Some("The column or expression to retrieve the nth value from.")) + .with_argument("expression", "The column or expression to retrieve the nth value from.") .with_argument("n", "The position (nth) of the value to retrieve, based on the ordering.") .build() .unwrap() diff --git a/datafusion/functions/src/string/replace.rs b/datafusion/functions/src/string/replace.rs index d510dc6f9a80..91abc39da058 100644 --- a/datafusion/functions/src/string/replace.rs +++ b/datafusion/functions/src/string/replace.rs @@ -97,7 +97,7 @@ fn get_replace_doc() -> &'static Documentation { +-------------------------------------------------+ ```"#) .with_standard_argument("str", Some("String")) - .with_standard_argument("substr", Some("Substring expression to replace in the input string. Substring expression")) + .with_standard_argument("substr", Some("Substring expression to replace in the input string. Substring")) .with_standard_argument("replacement", Some("Replacement substring")) .build() .unwrap() diff --git a/docs/source/user-guide/sql/aggregate_functions_new.md b/docs/source/user-guide/sql/aggregate_functions_new.md index fc918c3b15ea..1bf12c74fbcd 100644 --- a/docs/source/user-guide/sql/aggregate_functions_new.md +++ b/docs/source/user-guide/sql/aggregate_functions_new.md @@ -563,7 +563,7 @@ nth_value(expression, n ORDER BY expression) #### Arguments -- **expression**: The column or expression to retrieve the nth value from. expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **expression**: The column or expression to retrieve the nth value from. - **n**: The position (nth) of the value to retrieve, based on the ordering. #### Example diff --git a/docs/source/user-guide/sql/scalar_functions_new.md b/docs/source/user-guide/sql/scalar_functions_new.md index 7d0261da0ad0..634cbe507714 100644 --- a/docs/source/user-guide/sql/scalar_functions_new.md +++ b/docs/source/user-guide/sql/scalar_functions_new.md @@ -764,7 +764,7 @@ replace(str, substr, replacement) #### Arguments - **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. -- **substr**: Substring expression to replace in the input string. Substring expression expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **substr**: Substring expression to replace in the input string. Substring expression to operate on. Can be a constant, column, or function, and any combination of operators. - **replacement**: Replacement substring expression to operate on. Can be a constant, column, or function, and any combination of operators. #### Example From 77654d7faa5616fd548b4c918363fda693660698 Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Wed, 16 Oct 2024 22:31:38 -0400 Subject: [PATCH 4/8] small changes --- .../src/approx_distinct.rs | 2 +- .../functions-aggregate/src/approx_median.rs | 2 +- .../src/approx_percentile_cont.rs | 2 +- .../src/approx_percentile_cont_with_weight.rs | 2 +- .../functions-aggregate/src/array_agg.rs | 2 +- datafusion/functions-aggregate/src/average.rs | 2 +- .../functions-aggregate/src/bool_and_or.rs | 2 +- .../functions-aggregate/src/correlation.rs | 4 +- datafusion/functions-aggregate/src/count.rs | 2 +- .../functions-aggregate/src/covariance.rs | 8 ++-- .../functions-aggregate/src/first_last.rs | 4 +- datafusion/functions-aggregate/src/median.rs | 2 +- datafusion/functions-aggregate/src/min_max.rs | 4 +- datafusion/functions-aggregate/src/stddev.rs | 4 +- datafusion/functions-aggregate/src/sum.rs | 2 +- datafusion/functions/src/math/abs.rs | 2 +- datafusion/functions/src/math/factorial.rs | 2 +- datafusion/functions/src/math/gcd.rs | 4 +- datafusion/functions/src/math/iszero.rs | 2 +- datafusion/functions/src/math/lcm.rs | 4 +- datafusion/functions/src/math/monotonicity.rs | 44 +++++++++---------- datafusion/functions/src/math/nans.rs | 2 +- datafusion/functions/src/math/power.rs | 4 +- datafusion/functions/src/math/round.rs | 2 +- datafusion/functions/src/math/signum.rs | 2 +- datafusion/functions/src/math/trunc.rs | 2 +- 26 files changed, 57 insertions(+), 57 deletions(-) diff --git a/datafusion/functions-aggregate/src/approx_distinct.rs b/datafusion/functions-aggregate/src/approx_distinct.rs index d6cc711147b5..1df106feb4d3 100644 --- a/datafusion/functions-aggregate/src/approx_distinct.rs +++ b/datafusion/functions-aggregate/src/approx_distinct.rs @@ -332,7 +332,7 @@ fn get_approx_distinct_doc() -> &'static Documentation { +-----------------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/approx_median.rs b/datafusion/functions-aggregate/src/approx_median.rs index 84442fa5a2e6..96609622a51e 100644 --- a/datafusion/functions-aggregate/src/approx_median.rs +++ b/datafusion/functions-aggregate/src/approx_median.rs @@ -145,7 +145,7 @@ fn get_approx_median_doc() -> &'static Documentation { +-----------------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/approx_percentile_cont.rs b/datafusion/functions-aggregate/src/approx_percentile_cont.rs index 9b8a99e977d2..83b9f714fa89 100644 --- a/datafusion/functions-aggregate/src/approx_percentile_cont.rs +++ b/datafusion/functions-aggregate/src/approx_percentile_cont.rs @@ -293,7 +293,7 @@ fn get_approx_percentile_cont_doc() -> &'static Documentation { | 65.0 | +-------------------------------------------------+ ```"#) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .with_argument("percentile", "Percentile to compute. Must be a float value between 0 and 1 (inclusive).") .with_argument("centroids", "Number of centroids to use in the t-digest algorithm. _Default is 100_. A higher number results in more accurate approximation but requires more memory.") .build() diff --git a/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs b/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs index a5362713a6fb..b86fec1e037e 100644 --- a/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs +++ b/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs @@ -179,7 +179,7 @@ fn get_approx_percentile_cont_with_weight_doc() -> &'static Documentation { +----------------------------------------------------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .with_argument("weight", "Expression to use as weight. Can be a constant, column, or function, and any combination of arithmetic operators.") .with_argument("percentile", "Percentile to compute. Must be a float value between 0 and 1 (inclusive).") .build() diff --git a/datafusion/functions-aggregate/src/array_agg.rs b/datafusion/functions-aggregate/src/array_agg.rs index 28ff6fb346e5..6f523756832e 100644 --- a/datafusion/functions-aggregate/src/array_agg.rs +++ b/datafusion/functions-aggregate/src/array_agg.rs @@ -168,7 +168,7 @@ fn get_array_agg_doc() -> &'static Documentation { +-----------------------------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/average.rs b/datafusion/functions-aggregate/src/average.rs index 8782f8cfcc7c..67b824c2ea79 100644 --- a/datafusion/functions-aggregate/src/average.rs +++ b/datafusion/functions-aggregate/src/average.rs @@ -263,7 +263,7 @@ fn get_avg_doc() -> &'static Documentation { +---------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/bool_and_or.rs b/datafusion/functions-aggregate/src/bool_and_or.rs index 0bd5c723bf7b..b410bfa139e9 100644 --- a/datafusion/functions-aggregate/src/bool_and_or.rs +++ b/datafusion/functions-aggregate/src/bool_and_or.rs @@ -201,7 +201,7 @@ fn get_bool_and_doc() -> &'static Documentation { +----------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/correlation.rs b/datafusion/functions-aggregate/src/correlation.rs index d5dc482d68d2..40429289d768 100644 --- a/datafusion/functions-aggregate/src/correlation.rs +++ b/datafusion/functions-aggregate/src/correlation.rs @@ -134,8 +134,8 @@ fn get_corr_doc() -> &'static Documentation { +--------------------------------+ ```"#, ) - .with_standard_argument("expression1", "First") - .with_standard_argument("expression2", "Second") + .with_standard_argument("expression1", Some("First")) + .with_standard_argument("expression2", Some("Second")) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/count.rs b/datafusion/functions-aggregate/src/count.rs index 2511c70c4608..61dbfd674993 100644 --- a/datafusion/functions-aggregate/src/count.rs +++ b/datafusion/functions-aggregate/src/count.rs @@ -357,7 +357,7 @@ fn get_count_doc() -> &'static Documentation { | 120 | +------------------+ ```"#) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/covariance.rs b/datafusion/functions-aggregate/src/covariance.rs index f3b323d74d30..4b2b21059d16 100644 --- a/datafusion/functions-aggregate/src/covariance.rs +++ b/datafusion/functions-aggregate/src/covariance.rs @@ -150,8 +150,8 @@ fn get_covar_samp_doc() -> &'static Documentation { +-----------------------------------+ ```"#, ) - .with_standard_argument("expression1", "First") - .with_standard_argument("expression2", "Second") + .with_standard_argument("expression1", Some("First")) + .with_standard_argument("expression2", Some("Second")) .build() .unwrap() }) @@ -248,8 +248,8 @@ fn get_covar_pop_doc() -> &'static Documentation { +-----------------------------------+ ```"#, ) - .with_standard_argument("expression1", "First") - .with_standard_argument("expression2", "Second") + .with_standard_argument("expression1", Some("First")) + .with_standard_argument("expression2", Some("Second")) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/first_last.rs b/datafusion/functions-aggregate/src/first_last.rs index f6a84c84dcb0..40d220248a3a 100644 --- a/datafusion/functions-aggregate/src/first_last.rs +++ b/datafusion/functions-aggregate/src/first_last.rs @@ -191,7 +191,7 @@ fn get_first_value_doc() -> &'static Documentation { +-----------------------------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) @@ -519,7 +519,7 @@ fn get_last_value_doc() -> &'static Documentation { +-----------------------------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/median.rs b/datafusion/functions-aggregate/src/median.rs index 5a0cac2c829e..e0011e2e0f69 100644 --- a/datafusion/functions-aggregate/src/median.rs +++ b/datafusion/functions-aggregate/src/median.rs @@ -177,7 +177,7 @@ fn get_median_doc() -> &'static Documentation { +----------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/min_max.rs b/datafusion/functions-aggregate/src/min_max.rs index d576b1fdad78..8102d0e4794b 100644 --- a/datafusion/functions-aggregate/src/min_max.rs +++ b/datafusion/functions-aggregate/src/min_max.rs @@ -357,7 +357,7 @@ fn get_max_doc() -> &'static Documentation { +----------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) @@ -1187,7 +1187,7 @@ fn get_min_doc() -> &'static Documentation { +----------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/stddev.rs b/datafusion/functions-aggregate/src/stddev.rs index 332a8efcc0f9..0d1821687524 100644 --- a/datafusion/functions-aggregate/src/stddev.rs +++ b/datafusion/functions-aggregate/src/stddev.rs @@ -158,7 +158,7 @@ fn get_stddev_doc() -> &'static Documentation { +----------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) @@ -282,7 +282,7 @@ fn get_stddev_pop_doc() -> &'static Documentation { +--------------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions-aggregate/src/sum.rs b/datafusion/functions-aggregate/src/sum.rs index 3b561f3028de..943f66a92c00 100644 --- a/datafusion/functions-aggregate/src/sum.rs +++ b/datafusion/functions-aggregate/src/sum.rs @@ -260,7 +260,7 @@ fn get_sum_doc() -> &'static Documentation { +-----------------------+ ```"#, ) - .with_standard_argument("expression", "The") + .with_standard_argument("expression", None) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/abs.rs b/datafusion/functions/src/math/abs.rs index 5dcbb99eae65..5511a57d8566 100644 --- a/datafusion/functions/src/math/abs.rs +++ b/datafusion/functions/src/math/abs.rs @@ -201,7 +201,7 @@ fn get_abs_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the absolute value of a number.") .with_syntax_example("abs(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs index ac04c03190ae..4b87284744d3 100644 --- a/datafusion/functions/src/math/factorial.rs +++ b/datafusion/functions/src/math/factorial.rs @@ -85,7 +85,7 @@ fn get_factorial_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Factorial. Returns 1 if value is less than 2.") .with_syntax_example("factorial(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs index 5e56dacb9380..f4edef3acca3 100644 --- a/datafusion/functions/src/math/gcd.rs +++ b/datafusion/functions/src/math/gcd.rs @@ -87,8 +87,8 @@ fn get_gcd_doc() -> &'static Documentation { "Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero.", ) .with_syntax_example("gcd(expression_x, expression_y)") - .with_standard_argument("expression_x", "First numeric") - .with_standard_argument("expression_y", "Second numeric") + .with_standard_argument("expression_x", Some("First numeric")) + .with_standard_argument("expression_y", Some("Second numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/iszero.rs b/datafusion/functions/src/math/iszero.rs index b8deee2c6125..7e5d4fe77ffa 100644 --- a/datafusion/functions/src/math/iszero.rs +++ b/datafusion/functions/src/math/iszero.rs @@ -90,7 +90,7 @@ fn get_iszero_doc() -> &'static Documentation { "Returns true if a given number is +0.0 or -0.0 otherwise returns false.", ) .with_syntax_example("iszero(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs index 844dbfd39d38..64b07ce606f2 100644 --- a/datafusion/functions/src/math/lcm.rs +++ b/datafusion/functions/src/math/lcm.rs @@ -88,8 +88,8 @@ fn get_lcm_doc() -> &'static Documentation { "Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero.", ) .with_syntax_example("lcm(expression_x, expression_y)") - .with_standard_argument("expression_x", "First numeric") - .with_standard_argument("expression_y", "Second numeric") + .with_standard_argument("expression_x", Some("First numeric")) + .with_standard_argument("expression_y", Some("Second numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs index 959434d74f82..19c85f4b6e3c 100644 --- a/datafusion/functions/src/math/monotonicity.rs +++ b/datafusion/functions/src/math/monotonicity.rs @@ -46,7 +46,7 @@ pub fn get_acos_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the arc cosine or inverse cosine of a number.") .with_syntax_example("acos(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -79,7 +79,7 @@ pub fn get_acosh_doc() -> &'static Documentation { "Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number.", ) .with_syntax_example("acosh(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -108,7 +108,7 @@ pub fn get_asin_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the arc sine or inverse sine of a number.") .with_syntax_example("asin(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -129,7 +129,7 @@ pub fn get_asinh_doc() -> &'static Documentation { "Returns the area hyperbolic sine or inverse hyperbolic sine of a number.", ) .with_syntax_example("asinh(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -148,7 +148,7 @@ pub fn get_atan_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the arc tangent or inverse tangent of a number.") .with_syntax_example("atan(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -179,7 +179,7 @@ pub fn get_atanh_doc() -> &'static Documentation { "Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number.", ) .with_syntax_example("atanh(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -223,7 +223,7 @@ pub fn get_cbrt_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the cube root of a number.") .with_syntax_example("cbrt(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -244,7 +244,7 @@ pub fn get_ceil_doc() -> &'static Documentation { "Returns the nearest integer greater than or equal to a number.", ) .with_syntax_example("ceil(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -265,7 +265,7 @@ pub fn get_cos_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the cosine of a number.") .with_syntax_example("cos(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -295,7 +295,7 @@ pub fn get_cosh_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the hyperbolic cosine of a number.") .with_syntax_example("cosh(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -314,7 +314,7 @@ pub fn get_degrees_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Converts radians to degrees.") .with_syntax_example("degrees(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -333,7 +333,7 @@ pub fn get_exp_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the base-e exponential of a number.") .with_syntax_example("exp(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -354,7 +354,7 @@ pub fn get_floor_doc() -> &'static Documentation { "Returns the nearest integer less than or equal to a number.", ) .with_syntax_example("floor(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -382,7 +382,7 @@ pub fn get_ln_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the natural logarithm of a number.") .with_syntax_example("ln(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -410,7 +410,7 @@ pub fn get_log2_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the base-2 logarithm of a number.") .with_syntax_example("log2(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -438,7 +438,7 @@ pub fn get_log10_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the base-10 logarithm of a number.") .with_syntax_example("log10(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -457,7 +457,7 @@ pub fn get_radians_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Converts degrees to radians.") .with_syntax_example("radians(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -478,7 +478,7 @@ pub fn get_sin_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the sine of a number.") .with_syntax_example("sin(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -497,7 +497,7 @@ pub fn get_sinh_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the hyperbolic sine of a number.") .with_syntax_example("sinh(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -525,7 +525,7 @@ pub fn get_sqrt_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the square root of a number.") .with_syntax_example("sqrt(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -546,7 +546,7 @@ pub fn get_tan_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the tangent of a number.") .with_syntax_example("tan(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) @@ -565,7 +565,7 @@ pub fn get_tanh_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Returns the hyperbolic tangent of a number.") .with_syntax_example("tanh(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs index 79e4587958dc..c1dd1aacc35a 100644 --- a/datafusion/functions/src/math/nans.rs +++ b/datafusion/functions/src/math/nans.rs @@ -107,7 +107,7 @@ fn get_isnan_doc() -> &'static Documentation { "Returns true if a given number is +NaN or -NaN otherwise returns false.", ) .with_syntax_example("isnan(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/power.rs b/datafusion/functions/src/math/power.rs index a99afaec97f7..9125f9b0fecd 100644 --- a/datafusion/functions/src/math/power.rs +++ b/datafusion/functions/src/math/power.rs @@ -181,8 +181,8 @@ fn get_power_doc() -> &'static Documentation { "Returns a base expression raised to the power of an exponent.", ) .with_syntax_example("power(base, exponent)") - .with_standard_argument("base", "Numeric") - .with_standard_argument("exponent", "Exponent numeric") + .with_standard_argument("base", Some("Numeric")) + .with_standard_argument("exponent", Some("Exponent numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/round.rs b/datafusion/functions/src/math/round.rs index ae8eee0dbba2..fec1f1ce1aee 100644 --- a/datafusion/functions/src/math/round.rs +++ b/datafusion/functions/src/math/round.rs @@ -114,7 +114,7 @@ fn get_round_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_MATH) .with_description("Rounds a number to the nearest integer.") .with_syntax_example("round(numeric_expression[, decimal_places])") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .with_argument( "decimal_places", "Optional. The number of decimal places to round to. Defaults to 0.", diff --git a/datafusion/functions/src/math/signum.rs b/datafusion/functions/src/math/signum.rs index 6c020b0ce52a..ac881eb42f26 100644 --- a/datafusion/functions/src/math/signum.rs +++ b/datafusion/functions/src/math/signum.rs @@ -101,7 +101,7 @@ Negative numbers return `-1`. Zero and positive numbers return `1`."#, ) .with_syntax_example("signum(numeric_expression)") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .build() .unwrap() }) diff --git a/datafusion/functions/src/math/trunc.rs b/datafusion/functions/src/math/trunc.rs index 17a84420318e..9a05684d238e 100644 --- a/datafusion/functions/src/math/trunc.rs +++ b/datafusion/functions/src/math/trunc.rs @@ -119,7 +119,7 @@ fn get_trunc_doc() -> &'static Documentation { "Truncates a number to a whole number or truncated to the specified decimal places.", ) .with_syntax_example("trunc(numeric_expression[, decimal_places])") - .with_standard_argument("numeric_expression", "Numeric") + .with_standard_argument("numeric_expression", Some("Numeric")) .with_argument("decimal_places", r#"Optional. The number of decimal places to truncate to. Defaults to 0 (truncate to a whole number). If `decimal_places` is a positive integer, truncates digits to the From 00d9fde5d4fbbdbe5c1be0c95a1e9d35071faeb4 Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Thu, 17 Oct 2024 11:32:18 -0400 Subject: [PATCH 5/8] with_argument change --- datafusion/functions/src/string/concat_ws.rs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/datafusion/functions/src/string/concat_ws.rs b/datafusion/functions/src/string/concat_ws.rs index 964c18cbc701..8d966f495663 100644 --- a/datafusion/functions/src/string/concat_ws.rs +++ b/datafusion/functions/src/string/concat_ws.rs @@ -296,10 +296,7 @@ fn get_concat_ws_doc() -> &'static Documentation { "Separator to insert between concatenated strings.", ) .with_standard_argument("str", Some("String")) - .with_standard_argument( - "str_n", - Some("Subsequent string expressions to concatenate."), - ) + .with_argument("str_n", "Subsequent string expressions to concatenate.") .with_related_udf("concat") .build() .unwrap() From 0a2b6936e9f69cb55559972a7c5822536f7d5c1b Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Sat, 19 Oct 2024 13:51:00 -0400 Subject: [PATCH 6/8] ran build --- docs/source/user-guide/sql/scalar_functions_new.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/user-guide/sql/scalar_functions_new.md b/docs/source/user-guide/sql/scalar_functions_new.md index 1773d7be235c..31e2f0bc3d8c 100644 --- a/docs/source/user-guide/sql/scalar_functions_new.md +++ b/docs/source/user-guide/sql/scalar_functions_new.md @@ -908,7 +908,7 @@ concat_ws(separator, str[, ..., str_n]) - **separator**: Separator to insert between concatenated strings. - **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. -- **str_n**: Subsequent string expressions to concatenate. expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **str_n**: Subsequent string expressions to concatenate. #### Example From 51860e645aaf297f8ff25353aa81f8f34caa824d Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Sun, 20 Oct 2024 02:32:27 -0400 Subject: [PATCH 7/8] small fix --- datafusion/functions/src/regex/regexpcount.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/datafusion/functions/src/regex/regexpcount.rs b/datafusion/functions/src/regex/regexpcount.rs index 880c91094555..229e6909dab5 100644 --- a/datafusion/functions/src/regex/regexpcount.rs +++ b/datafusion/functions/src/regex/regexpcount.rs @@ -127,8 +127,8 @@ fn get_regexp_count_doc() -> &'static Documentation { | 1 | +---------------------------------------------------------------+ ```"#) - .with_standard_argument("str", "String") - .with_standard_argument("regexp","Regular") + .with_standard_argument("str", Some("String")) + .with_standard_argument("regexp", Some("Regular")) .with_argument("start", "- **start**: Optional start position (the first position is 1) to search for the regular expression. Can be a constant, column, or function.") .with_argument("flags", r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: From 14ec8151af0a9433c2e57c9be8d3a093560fab5e Mon Sep 17 00:00:00 2001 From: Jonathan Chen Date: Mon, 21 Oct 2024 14:21:41 -0400 Subject: [PATCH 8/8] Added special page --- .../core/src/bin/print_functions_docs.rs | 18 ++++- datafusion/expr/src/lib.rs | 2 + datafusion/expr/src/udf.rs | 7 -- datafusion/expr/src/udsf.rs | 32 +++++++++ datafusion/functions-nested/src/map.rs | 50 +++++++++++++- dev/update_function_docs.sh | 47 +++++++++++++ .../user-guide/sql/special_functions_new.md | 66 +++++++++++++++++++ 7 files changed, 210 insertions(+), 12 deletions(-) create mode 100644 datafusion/expr/src/udsf.rs create mode 100644 docs/source/user-guide/sql/special_functions_new.md diff --git a/datafusion/core/src/bin/print_functions_docs.rs b/datafusion/core/src/bin/print_functions_docs.rs index d87c3cefe666..924f0c0e95aa 100644 --- a/datafusion/core/src/bin/print_functions_docs.rs +++ b/datafusion/core/src/bin/print_functions_docs.rs @@ -17,8 +17,8 @@ use datafusion::execution::SessionStateDefaults; use datafusion_expr::{ - aggregate_doc_sections, scalar_doc_sections, window_doc_sections, AggregateUDF, - DocSection, Documentation, ScalarUDF, WindowUDF, + aggregate_doc_sections, scalar_doc_sections, special_doc_sections, + window_doc_sections, AggregateUDF, DocSection, Documentation, ScalarUDF, WindowUDF, }; use hashbrown::HashSet; use itertools::Itertools; @@ -35,7 +35,7 @@ fn main() { if args.len() != 2 { panic!( - "Usage: {} type (one of 'aggregate', 'scalar', 'window')", + "Usage: {} type (one of 'aggregate', 'scalar', 'special', 'window')", args[0] ); } @@ -44,6 +44,7 @@ fn main() { let docs = match function_type.as_str() { "aggregate" => print_aggregate_docs(), "scalar" => print_scalar_docs(), + "special" => print_special_docs(), "window" => print_window_docs(), _ => { panic!("Unknown function type: {}", function_type) @@ -73,6 +74,17 @@ fn print_scalar_docs() -> String { print_docs(providers, scalar_doc_sections::doc_sections()) } +fn print_special_docs() -> String { + let mut providers: Vec> = vec![]; + + // Iterates through the default_scalar_functions to retrieve the special functions + for f in SessionStateDefaults::default_scalar_functions() { + providers.push(Box::new(f.as_ref().clone())); + } + + print_docs(providers, special_doc_sections::doc_sections()) +} + fn print_window_docs() -> String { let mut providers: Vec> = vec![]; diff --git a/datafusion/expr/src/lib.rs b/datafusion/expr/src/lib.rs index 849d9604808c..3291b76f8fdd 100644 --- a/datafusion/expr/src/lib.rs +++ b/datafusion/expr/src/lib.rs @@ -35,6 +35,7 @@ mod table_source; mod udaf; mod udf; mod udf_docs; +mod udsf; mod udwf; pub mod conditional_expressions; @@ -96,6 +97,7 @@ pub use udaf::{ }; pub use udf::{scalar_doc_sections, ScalarUDF, ScalarUDFImpl}; pub use udf_docs::{DocSection, Documentation, DocumentationBuilder}; +pub use udsf::special_doc_sections; pub use udwf::{window_doc_sections, ReversedUDWF, WindowUDF, WindowUDFImpl}; pub use window_frame::{WindowFrame, WindowFrameBound, WindowFrameUnits}; diff --git a/datafusion/expr/src/udf.rs b/datafusion/expr/src/udf.rs index 3759fb18f56d..2fed0bac5a60 100644 --- a/datafusion/expr/src/udf.rs +++ b/datafusion/expr/src/udf.rs @@ -767,7 +767,6 @@ pub mod scalar_doc_sections { DOC_SECTION_DATETIME, DOC_SECTION_ARRAY, DOC_SECTION_STRUCT, - DOC_SECTION_MAP, DOC_SECTION_HASHING, DOC_SECTION_OTHER, ] @@ -826,12 +825,6 @@ The following regular expression functions are supported:"#, description: None, }; - pub const DOC_SECTION_MAP: DocSection = DocSection { - include: true, - label: "Map Functions", - description: None, - }; - pub const DOC_SECTION_HASHING: DocSection = DocSection { include: true, label: "Hashing Functions", diff --git a/datafusion/expr/src/udsf.rs b/datafusion/expr/src/udsf.rs new file mode 100644 index 000000000000..41ee3b6155ae --- /dev/null +++ b/datafusion/expr/src/udsf.rs @@ -0,0 +1,32 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +//! [`SpecialUDF`]: Special User Defined Functions + +pub mod special_doc_sections { + use crate::DocSection; + + pub fn doc_sections() -> Vec { + vec![DOC_SECTION_MAP] + } + + pub const DOC_SECTION_MAP: DocSection = DocSection { + include: true, + label: "Map Functions", + description: None, + }; +} diff --git a/datafusion/functions-nested/src/map.rs b/datafusion/functions-nested/src/map.rs index 29afe4a7f3be..38eb286e9ebb 100644 --- a/datafusion/functions-nested/src/map.rs +++ b/datafusion/functions-nested/src/map.rs @@ -17,7 +17,7 @@ use std::any::Any; use std::collections::{HashSet, VecDeque}; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::ArrayData; use arrow_array::{Array, ArrayRef, MapArray, OffsetSizeTrait, StructArray}; @@ -27,7 +27,10 @@ use arrow_schema::{DataType, Field, SchemaBuilder}; use datafusion_common::utils::{fixed_size_list_to_arrays, list_to_arrays}; use datafusion_common::{exec_err, Result, ScalarValue}; use datafusion_expr::expr::ScalarFunction; -use datafusion_expr::{ColumnarValue, Expr, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::special_doc_sections::DOC_SECTION_MAP; +use datafusion_expr::{ + ColumnarValue, Documentation, Expr, ScalarUDFImpl, Signature, Volatility, +}; use crate::make_array::make_array; @@ -238,7 +241,50 @@ impl ScalarUDFImpl for MapFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_map_batch(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_map_doc()) + } } + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_map_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MAP) + .with_description( + "Returns an Arrow map with the specified key-value pairs.", + ) + .with_syntax_example("map(key, value)\nmap(key: value)") + .with_sql_example( + r#"```sql +SELECT MAP(['POST', 'HEAD', 'PATCH'], [41, 33, null]); +---- +{POST: 41, HEAD: 33, PATCH: } + +SELECT MAP([[1,2], [3,4]], ['a', 'b']); +---- +{[1, 2]: a, [3, 4]: b} + +SELECT MAP { 'a': 1, 'b': 2 }; +---- +{a: 1, b: 2} +```"#, + ) + .with_argument( + "key", + "Expression to be used for key. Can be a constant, column, or function, any combination of arithmetic or string operators, or a named expression of the previously listed.", + ) + .with_argument( + "value", + "Expression to be used for value. Can be a constant, column, or function, any combination of arithmetic or string operators, or a named expression of the previously listed.", + ) + .build() + .unwrap() +}) +} + fn get_element_type(data_type: &DataType) -> Result<&DataType> { match data_type { DataType::List(element) => Ok(element.data_type()), diff --git a/dev/update_function_docs.sh b/dev/update_function_docs.sh index f1f26c8b2f58..33ae35e84c43 100755 --- a/dev/update_function_docs.sh +++ b/dev/update_function_docs.sh @@ -298,3 +298,50 @@ npx prettier@2.3.2 --write "$TARGET_FILE" echo "'$TARGET_FILE' successfully updated!" +TARGET_FILE="docs/source/user-guide/sql/special_functions_new.md" +PRINT_SPECIAL_FUNCTION_DOCS_COMMAND="cargo run --manifest-path datafusion/core/Cargo.toml --bin print_functions_docs -- special" + +echo "Inserting header" +cat <<'EOF' > "$TARGET_FILE" + + + + +# Special Functions (NEW) + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. + +[automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 + +EOF + +echo "Running CLI and inserting special function docs table" +$PRINT_SPECIAL_FUNCTION_DOCS_COMMAND >> "$TARGET_FILE" + +echo "Running prettier" +npx prettier@2.3.2 --write "$TARGET_FILE" + +echo "'$TARGET_FILE' successfully updated!" \ No newline at end of file diff --git a/docs/source/user-guide/sql/special_functions_new.md b/docs/source/user-guide/sql/special_functions_new.md new file mode 100644 index 000000000000..90507a08714c --- /dev/null +++ b/docs/source/user-guide/sql/special_functions_new.md @@ -0,0 +1,66 @@ + + + + +# Special Functions (NEW) + +Note: this documentation is in the process of being migrated to be [automatically created from the codebase]. + +[automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 + +## Map Functions + +- [map](#map) + +### `map` + +Returns an Arrow map with the specified key-value pairs. + +``` +map(key, value) +map(key: value) +``` + +#### Arguments + +- **key**: Expression to be used for key. Can be a constant, column, or function, any combination of arithmetic or string operators, or a named expression of the previously listed. +- **value**: Expression to be used for value. Can be a constant, column, or function, any combination of arithmetic or string operators, or a named expression of the previously listed. + +#### Example + +```sql +SELECT MAP(['POST', 'HEAD', 'PATCH'], [41, 33, null]); +---- +{POST: 41, HEAD: 33, PATCH: } + +SELECT MAP([[1,2], [3,4]], ['a', 'b']); +---- +{[1, 2]: a, [3, 4]: b} + +SELECT MAP { 'a': 1, 'b': 2 }; +---- +{a: 1, b: 2} +```