diff --git a/crates/spark/src/function/string/ascii.rs b/crates/spark/src/function/string/ascii.rs index a305b069..35e1af7a 100644 --- a/crates/spark/src/function/string/ascii.rs +++ b/crates/spark/src/function/string/ascii.rs @@ -8,18 +8,37 @@ use arrow::datatypes::{DataType, Field, FieldRef}; use datafusion_common::types::{NativeType, logical_string}; use datafusion_common::{Result, internal_err}; use datafusion_expr::{ - Coercion, ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, - Signature, TypeSignatureClass, Volatility, + Coercion, ColumnarValue, Documentation, ReturnFieldArgs, ScalarFunctionArgs, + ScalarUDFImpl, Signature, TypeSignatureClass, Volatility, }; use datafusion_functions::string::ascii::ascii; use datafusion_functions::utils::make_scalar_function; +use datafusion_macros::user_doc; -/// Spark compatible version of the [ascii] function. Differs from the [default ascii function] -/// in that it is more permissive of input types, for example casting numeric input to string -/// before executing the function (default version doesn't allow numeric input). +/// Spark-compatible `ascii` expression. /// -/// [ascii]: https://spark.apache.org/docs/latest/api/sql/index.html#ascii -/// [default ascii function]: datafusion_functions::string::ascii::AsciiFunc +/// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns the numeric code point of the first character of `str`. \ + Despite the name, this is the full Unicode code point, not just ASCII (`ascii('😀')` is 128512). \ + An empty string returns 0, and NULL returns NULL. \ + Unlike DataFusion's `ascii`, numeric input is accepted and cast to a string first, \ + so `ascii(2)` is the code point of `'2'`.", + syntax_example = "ascii(str)", + sql_example = r#"```sql +> SELECT ascii('Spark'); +83 +> SELECT ascii(''); +0 +> SELECT ascii(2); +50 +```"#, + argument( + name = "str", + description = "String expression. Numeric values are cast to a string. NULL returns NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkAscii { signature: Signature, @@ -68,6 +87,10 @@ impl ScalarUDFImpl for SparkAscii { Ok(Arc::new(Field::new("ascii", DataType::Int32, nullable))) } + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result { make_scalar_function(ascii, vec![])(&args.args) } diff --git a/crates/spark/src/function/string/char.rs b/crates/spark/src/function/string/char.rs index 5666c6e4..bf378607 100644 --- a/crates/spark/src/function/string/char.rs +++ b/crates/spark/src/function/string/char.rs @@ -7,16 +7,37 @@ use arrow::array::GenericStringBuilder; use arrow::datatypes::DataType::Int64; use arrow::datatypes::DataType::Utf8; use arrow::datatypes::{DataType, Field, FieldRef}; +use datafusion_macros::user_doc; use std::sync::Arc; use datafusion_common::{Result, ScalarValue, cast::as_int64_array, exec_err}; use datafusion_expr::{ - ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, - Volatility, + ColumnarValue, Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, + Signature, Volatility, }; -/// Spark-compatible `char` expression +/// Spark-compatible `char` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns the character whose code point is `n` modulo 256, so `char(321)` is `A`. \ + A negative `n` returns an empty string, and NULL returns NULL. \ + DataFusion's `chr` instead uses `n` as a full Unicode code point and errors on negative or invalid values.", + syntax_example = "char(n)", + sql_example = r#"```sql +> SELECT char(65); +A +> SELECT char(321); +A +> SELECT char(-1); +-- empty string +```"#, + argument( + name = "n", + description = "Integer expression, cast to BIGINT. NULL returns NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct CharFunc { signature: Signature, @@ -37,6 +58,10 @@ impl CharFunc { } impl ScalarUDFImpl for CharFunc { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "char" } diff --git a/crates/spark/src/function/string/concat.rs b/crates/spark/src/function/string/concat.rs index b5f85116..bec911ba 100644 --- a/crates/spark/src/function/string/concat.rs +++ b/crates/spark/src/function/string/concat.rs @@ -7,24 +7,39 @@ use datafusion_common::arrow::datatypes::FieldRef; use datafusion_common::{Result, ScalarValue}; use datafusion_expr::ReturnFieldArgs; use datafusion_expr::{ - ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility, + ColumnarValue, Documentation, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Volatility, }; use datafusion_functions::string::concat::ConcatFunc; +use datafusion_macros::user_doc; use std::sync::Arc; use crate::function::null_utils::{ NullMaskResolution, apply_null_mask, compute_null_mask, }; -/// Spark-compatible `concat` expression -/// -/// -/// Concatenates multiple input strings into a single string. -/// Returns NULL if any input is NULL. +/// Spark-compatible `concat` expression. /// -/// Differences with DataFusion concat: -/// - Support 0 arguments -/// - Return NULL if any input is NULL +/// +#[user_doc( + doc_section(label = "String Functions"), + description = "Concatenates the arguments into a single string, or binary if all arguments are binary. \ + Returns NULL if any argument is NULL, whereas DataFusion's `concat` skips NULL arguments. \ + Unlike DataFusion's `concat`, it also accepts zero arguments and then returns an empty string.", + syntax_example = "concat([expr1[, ..., exprN]])", + sql_example = r#"```sql +> SELECT concat('Spark', 'SQL'); +SparkSQL +> SELECT concat('Spark', 'SQL', NULL); +NULL +> SELECT concat(); +-- empty string +```"#, + argument( + name = "expr", + description = "String or binary expressions to concatenate. Any NULL makes the result NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkConcat { signature: Signature, @@ -45,6 +60,10 @@ impl SparkConcat { } impl ScalarUDFImpl for SparkConcat { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "concat" } diff --git a/crates/spark/src/function/string/concat_ws.rs b/crates/spark/src/function/string/concat_ws.rs index 0de2efe3..773f42d5 100644 --- a/crates/spark/src/function/string/concat_ws.rs +++ b/crates/spark/src/function/string/concat_ws.rs @@ -3,16 +3,8 @@ // SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements //! Spark-compatible `concat_ws`: joins strings (and array elements) with a separator. -//! -//! Null scalar args and null array elements are skipped; a null separator yields a -//! null row. Non-string args are coerced to STRING; list args (`List`, `LargeList`, -//! `ListView`, `LargeListView`, `FixedSizeList`) expand their elements. -//! -//! Differences with DataFusion core `concat_ws`: -//! - Accepts list arguments and expands their elements -//! - Always returns Utf8 (Spark's `STRING` type) -//! - Coerces non-string scalars (numbers, booleans, dates, ...) to Utf8 +use datafusion_macros::user_doc; use std::fmt::Write as _; use std::sync::Arc; @@ -24,14 +16,45 @@ use arrow::datatypes::{DataType, Field}; use datafusion_common::arrow::datatypes::FieldRef; use datafusion_common::{Result, ScalarValue}; use datafusion_expr::{ - ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, - Volatility, + ColumnarValue, Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, + Signature, Volatility, }; use crate::function::error_utils::{ invalid_arg_count_exec_err, unsupported_data_type_exec_err, }; +/// Spark-compatible `concat_ws` expression. +/// +/// +#[user_doc( + doc_section(label = "String Functions"), + description = "Concatenates the arguments after the first, separated by `sep`. \ + NULL arguments and NULL array elements are skipped, so if every argument is NULL the result is an empty string. \ + A NULL separator returns NULL. With only a separator, the result is an empty string. \ + Unlike DataFusion's `concat_ws`, array arguments are expanded into their elements, \ + non-string arguments (numbers, booleans, dates, binary, array elements) are cast to strings, \ + and the result is always `Utf8`.", + syntax_example = "concat_ws(sep[, expr1[, ..., exprN]])", + sql_example = r#"```sql +> SELECT concat_ws(' ', 'Spark', 'SQL'); +Spark SQL +> SELECT concat_ws('/', 'foo', NULL, 'bar'); +foo/bar +> SELECT concat_ws(',', 'x', array('a', 'b'), 'y'); +x,a,b,y +> SELECT concat_ws(NULL, 'a', 'b'); +NULL +```"#, + argument( + name = "sep", + description = "Separator, cast to a string. NULL returns NULL." + ), + argument( + name = "expr", + description = "Values or arrays to join. Arrays contribute each element. NULL values and elements are skipped. Structs are not supported." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkConcatWs { signature: Signature, @@ -52,6 +75,10 @@ impl SparkConcatWs { } impl ScalarUDFImpl for SparkConcatWs { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "concat_ws" } diff --git a/crates/spark/src/function/string/elt.rs b/crates/spark/src/function/string/elt.rs index 1559088c..20b032d4 100644 --- a/crates/spark/src/function/string/elt.rs +++ b/crates/spark/src/function/string/elt.rs @@ -2,6 +2,7 @@ // SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership // SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements +use datafusion_macros::user_doc; use std::sync::Arc; use arrow::array::{ @@ -13,10 +14,39 @@ use arrow::datatypes::{DataType, Int64Type}; use datafusion_common::cast::as_string_array; use datafusion_common::{DataFusionError, Result, exec_err, plan_datafusion_err}; use datafusion_expr::{ - ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility, + ColumnarValue, Documentation, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Volatility, }; use datafusion_functions::utils::make_scalar_function; +/// Spark-compatible `elt` expression. +/// +/// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns the `n`-th of the following arguments as a string (1-based). \ + DataFusion has no built-in `elt`. \ + A NULL `n` returns NULL, as does picking a NULL argument. \ + If `n` is less than 1 or greater than the number of arguments, the result is NULL, \ + or an error when `datafusion.execution.enable_ansi_mode` is true.", + syntax_example = "elt(n, expr1[, ..., exprN])", + sql_example = r#"```sql +> SELECT elt(1, 'scala', 'java'); +scala +> SELECT elt(2, 'a', 1); +1 +> SELECT elt(3, 'scala', 'java'); +NULL +```"#, + argument( + name = "n", + description = "Integer index, 1-based, cast to BIGINT. NULL returns NULL." + ), + argument( + name = "expr", + description = "At least one value to choose from. Each is cast to a string." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkElt { signature: Signature, @@ -37,6 +67,10 @@ impl SparkElt { } impl ScalarUDFImpl for SparkElt { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "elt" } diff --git a/crates/spark/src/function/string/format_string.rs b/crates/spark/src/function/string/format_string.rs index 9be6b8d3..8f33e109 100644 --- a/crates/spark/src/function/string/format_string.rs +++ b/crates/spark/src/function/string/format_string.rs @@ -2,6 +2,7 @@ // SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership // SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements +use datafusion_macros::user_doc; use std::fmt::Write; use std::sync::Arc; @@ -20,12 +21,44 @@ use datafusion_common::{ DataFusionError, Result, ScalarValue, exec_datafusion_err, exec_err, plan_err, }; use datafusion_expr::{ - ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, - TypeSignature, Volatility, + ColumnarValue, Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, + Signature, TypeSignature, Volatility, }; -/// Spark-compatible `format_string` expression +/// Spark-compatible `format_string` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns a string formatted from a printf-style format string, following Java's `java.util.Formatter` \ + as Spark does. DataFusion has no built-in equivalent. \ + Supports the `%s`, `%b`, `%c`, `%d`, `%o`, `%x`, `%e`, `%f`, `%g`, `%a` and `%t` (date/time) conversions \ + and their uppercase forms, the `-`, `+`, ` `, `0`, `#`, `,` and `(` flags, width and precision, \ + and positional (`%2$s`) and relative (`% SELECT format_string('Hello World %d %s', 100, 'days'); +Hello World 100 days +> SELECT format_string('%2$s %1$d', 42, 'test'); +test 42 +> SELECT format_string('Precision: %.2f', 3.14159); +Precision: 3.14 +> SELECT format_string('Value: %s', NULL); +Value: null +```"#, + argument( + name = "format", + description = "String format specification. NULL returns NULL." + ), + argument( + name = "arg", + description = "Values to format. Each must suit the conversion that refers to it. A NULL value is formatted as `null`." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct FormatStringFunc { signature: Signature, @@ -48,6 +81,10 @@ impl FormatStringFunc { } impl ScalarUDFImpl for FormatStringFunc { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "format_string" } diff --git a/crates/spark/src/function/string/ilike.rs b/crates/spark/src/function/string/ilike.rs index 7090e420..5278210a 100644 --- a/crates/spark/src/function/string/ilike.rs +++ b/crates/spark/src/function/string/ilike.rs @@ -8,13 +8,41 @@ use arrow::datatypes::{DataType, Field}; use datafusion_common::{Result, exec_err, internal_err}; use datafusion_expr::ColumnarValue; use datafusion_expr::{ - ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility, + Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Volatility, }; use datafusion_functions::utils::make_scalar_function; +use datafusion_macros::user_doc; use std::sync::Arc; -/// ILIKE function for case-insensitive pattern matching +/// Spark-compatible `ilike` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns true if `str` matches `pattern`, ignoring case. \ + In the pattern, `_` matches any one character and `%` matches any sequence of characters. \ + Returns NULL if either argument is NULL. \ + This is the function form of the `ILIKE` operator, which DataFusion supports only as an operator. \ + Spark's optional third `escape` argument is not supported.", + syntax_example = "ilike(str, pattern)", + sql_example = r#"```sql +> SELECT ilike('Spark', '_PARK'); +true +> SELECT ilike('Spark', 'xyz'); +false +> SELECT ilike('Spark', NULL); +NULL +```"#, + argument( + name = "str", + description = "String expression to match. NULL returns NULL." + ), + argument( + name = "pattern", + description = "String pattern, using `_` and `%` as wildcards. NULL returns NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkILike { signature: Signature, @@ -35,6 +63,10 @@ impl SparkILike { } impl ScalarUDFImpl for SparkILike { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "ilike" } diff --git a/crates/spark/src/function/string/length.rs b/crates/spark/src/function/string/length.rs index 5b4e2a5d..632fbe91 100644 --- a/crates/spark/src/function/string/length.rs +++ b/crates/spark/src/function/string/length.rs @@ -8,14 +8,37 @@ use arrow::array::{ use arrow::datatypes::{DataType, Field, FieldRef, Int32Type}; use datafusion_common::exec_err; use datafusion_expr::{ - ColumnarValue, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, - Volatility, + ColumnarValue, Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, + Signature, Volatility, }; use datafusion_functions::utils::make_scalar_function; +use datafusion_macros::user_doc; use std::sync::Arc; -/// Spark-compatible `length` expression +/// Spark-compatible `length` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns the number of characters in a string, or the number of bytes in a binary value. \ + Trailing spaces and binary zeros are counted. NULL returns NULL. \ + Unlike DataFusion's `length`/`character_length`, binary input is accepted, \ + and the result is always `Int32`, including for `LargeUtf8` input.", + syntax_example = "length(expr)", + alternative_syntax = "char_length(expr)", + alternative_syntax = "character_length(expr)", + alternative_syntax = "len(expr)", + sql_example = r#"```sql +> SELECT length('Spark SQL '); +10 +> SELECT length(x'537061726b2053514c'); +9 +```"#, + argument( + name = "expr", + description = "String or binary expression. NULL returns NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkLengthFunc { signature: Signature, @@ -53,6 +76,10 @@ impl SparkLengthFunc { } impl ScalarUDFImpl for SparkLengthFunc { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "length" } diff --git a/crates/spark/src/function/string/like.rs b/crates/spark/src/function/string/like.rs index 5689f2b0..32218503 100644 --- a/crates/spark/src/function/string/like.rs +++ b/crates/spark/src/function/string/like.rs @@ -8,13 +8,41 @@ use arrow::datatypes::{DataType, Field, FieldRef}; use datafusion_common::{Result, exec_err, internal_err}; use datafusion_expr::ColumnarValue; use datafusion_expr::{ - ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility, + Documentation, ReturnFieldArgs, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Volatility, }; use datafusion_functions::utils::make_scalar_function; +use datafusion_macros::user_doc; use std::sync::Arc; -/// LIKE function for case-sensitive pattern matching +/// Spark-compatible `like` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns true if `str` matches `pattern`, case-sensitively. \ + In the pattern, `_` matches any one character and `%` matches any sequence of characters. \ + Returns NULL if either argument is NULL. \ + This is the function form of the `LIKE` operator, which DataFusion supports only as an operator. \ + Spark's optional third `escape` argument is not supported.", + syntax_example = "like(str, pattern)", + sql_example = r#"```sql +> SELECT like('Spark', '_park'); +true +> SELECT like('Spark', 'SP%'); +false +> SELECT like(NULL, '_park'); +NULL +```"#, + argument( + name = "str", + description = "String expression to match. NULL returns NULL." + ), + argument( + name = "pattern", + description = "String pattern, using `_` and `%` as wildcards. NULL returns NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkLike { signature: Signature, @@ -35,6 +63,10 @@ impl SparkLike { } impl ScalarUDFImpl for SparkLike { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "like" } diff --git a/crates/spark/src/function/string/quote.rs b/crates/spark/src/function/string/quote.rs index b81cd055..e10cfff4 100644 --- a/crates/spark/src/function/string/quote.rs +++ b/crates/spark/src/function/string/quote.rs @@ -9,16 +9,37 @@ use datafusion_common::types::{NativeType, logical_string}; use datafusion_common::utils::{offset_span_len, take_function_args}; use datafusion_common::{Result, exec_err}; use datafusion_expr::{ - Coercion, ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Coercion, ColumnarValue, Documentation, ScalarFunctionArgs, ScalarUDFImpl, Signature, TypeSignatureClass, Volatility, }; use datafusion_functions::utils::make_scalar_function; +use datafusion_macros::user_doc; use std::fmt::Write; use std::sync::Arc; -/// Spark-compatible `quote` expression +/// Spark-compatible `quote` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns `str` wrapped in single quotes, with each single quote inside it escaped with a backslash. \ + No other characters are escaped. DataFusion has no built-in equivalent. \ + Values of other types are cast to a string first. NULL returns NULL.", + syntax_example = "quote(str)", + sql_example = r#"```sql +> SELECT quote('Spark'); +'Spark' +> SELECT quote('it''s'); +'it\'s' +> SELECT quote(NULL); +NULL +```"#, + argument( + name = "str", + description = "Expression to quote. Non-string values are cast to a string. NULL returns NULL." + ) +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkQuote { signature: Signature, @@ -44,6 +65,10 @@ impl SparkQuote { } impl ScalarUDFImpl for SparkQuote { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "quote" } diff --git a/crates/spark/src/function/string/soundex.rs b/crates/spark/src/function/string/soundex.rs index ff264ef3..2b533e80 100644 --- a/crates/spark/src/function/string/soundex.rs +++ b/crates/spark/src/function/string/soundex.rs @@ -7,13 +7,32 @@ use arrow::datatypes::DataType; use datafusion_common::cast::{as_generic_string_array, as_string_view_array}; use datafusion_common::utils::take_function_args; use datafusion_common::{Result, exec_err}; -use datafusion_expr::{ColumnarValue, Signature, Volatility}; +use datafusion_expr::{ColumnarValue, Documentation, Signature, Volatility}; use datafusion_expr::{ScalarFunctionArgs, ScalarUDFImpl}; use datafusion_functions::utils::make_scalar_function; +use datafusion_macros::user_doc; use std::sync::Arc; -/// Spark-compatible `soundex` expression +/// Spark-compatible `soundex` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns the four-character Soundex code of `str`: its first letter in upper case \ + followed by three digits, padded with `0`. Letters are matched case-insensitively. \ + A string that does not start with an ASCII letter (for example a digit, space, symbol or `Ñ`) is returned unchanged, \ + as is the empty string. NULL returns NULL. DataFusion has no built-in equivalent.", + syntax_example = "soundex(str)", + sql_example = r#"```sql +> SELECT soundex('Miller'); +M460 +> SELECT soundex('Robert'); +R163 +> SELECT soundex('123'); +123 +```"#, + argument(name = "str", description = "String expression. NULL returns NULL.") +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkSoundex { signature: Signature, @@ -34,6 +53,10 @@ impl SparkSoundex { } impl ScalarUDFImpl for SparkSoundex { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "soundex" } diff --git a/crates/spark/src/function/string/space.rs b/crates/spark/src/function/string/space.rs index 0c8649f9..dea5e05e 100644 --- a/crates/spark/src/function/string/space.rs +++ b/crates/spark/src/function/string/space.rs @@ -10,12 +10,30 @@ use arrow::datatypes::{DataType, Int32Type}; use datafusion_common::cast::as_int32_array; use datafusion_common::{Result, ScalarValue, exec_err}; use datafusion_expr::{ - ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility, + ColumnarValue, Documentation, ScalarFunctionArgs, ScalarUDFImpl, Signature, + Volatility, }; +use datafusion_macros::user_doc; use std::sync::Arc; -/// Spark-compatible `space` expression +/// Spark-compatible `space` expression. +/// /// +#[user_doc( + doc_section(label = "String Functions"), + description = "Returns a string of `n` spaces. \ + A value of 0 or less returns an empty string, and NULL returns NULL. \ + DataFusion has no built-in equivalent. \ + `n` must be an INT, and integer literals are BIGINT in DataFusion, so cast them (`space(2::INT)`; see [#97](https://github.com/apache/datafusion-spark/issues/97)).", + syntax_example = "space(n)", + sql_example = r#"```sql +> SELECT concat(space(2::INT), 'Spark'); + Spark +> SELECT space(-1::INT); +-- empty string +```"#, + argument(name = "n", description = "INT number of spaces. NULL returns NULL.") +)] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SparkSpace { signature: Signature, @@ -46,6 +64,10 @@ impl SparkSpace { } impl ScalarUDFImpl for SparkSpace { + fn documentation(&self) -> Option<&Documentation> { + self.doc() + } + fn name(&self) -> &str { "space" } diff --git a/crates/sqllogictest/test_files/string/space.slt b/crates/sqllogictest/test_files/string/space.slt index bfa4e063..0102eccf 100644 --- a/crates/sqllogictest/test_files/string/space.slt +++ b/crates/sqllogictest/test_files/string/space.slt @@ -26,3 +26,7 @@ query T SELECT space(NULL); ---- NULL + +# An integer literal is BIGINT here and INT in Spark, where this works (https://github.com/apache/datafusion-spark/issues/97) +statement error Failed to coerce arguments to satisfy a call to 'space' function +SELECT space(2);