Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc-gen: migrate scalar functions (string) documentation 2/4 #13925

Merged
merged 7 commits into from
Jan 3, 2025
Merged

doc-gen: migrate scalar functions (string) documentation 2/4 #13925

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
683de7d
doc-gen: migrate scalar functions (string) documentation 2/4
Dec 26, 2024
7cfed4b
doc-gen: update function docs
Dec 29, 2024
f713c7a
doc: fix related udf order for upper function in documentation
Dec 30, 2024
1a45912
Update datafusion/functions/src/string/concat_ws.rs
comphead Jan 2, 2025
deb6c5d
Update datafusion/functions/src/string/concat_ws.rs
comphead Jan 2, 2025
f2318e5
Update datafusion/functions/src/string/concat_ws.rs
comphead Jan 2, 2025
8c037ad
doc-gen: update function docs
Chen-Yuan-Lai Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 22 additions & 29 deletions datafusion/functions/src/string/concat.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ use arrow::array::{as_largestring_array, Array};
use arrow::datatypes::DataType;
use datafusion_expr::sort_properties::ExprProperties;
use std::any::Any;
use std::sync::{Arc, OnceLock};
use std::sync::Arc;

use crate::string::concat;
use crate::strings::{
Expand All @@ -28,11 +28,30 @@ use crate::strings::{
use datafusion_common::cast::{as_string_array, as_string_view_array};
use datafusion_common::{internal_err, plan_err, Result, ScalarValue};
use datafusion_expr::expr::ScalarFunction;
use datafusion_expr::scalar_doc_sections::DOC_SECTION_STRING;
use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo};
use datafusion_expr::{lit, ColumnarValue, Documentation, Expr, Volatility};
use datafusion_expr::{ScalarUDFImpl, Signature};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "String Functions"),
description = "Concatenates multiple strings together.",
syntax_example = "concat(str[, ..., str_n])",
sql_example = r#"```sql
> select concat('data', 'f', 'us', 'ion');
+-------------------------------------------------------+
| concat(Utf8("data"),Utf8("f"),Utf8("us"),Utf8("ion")) |
+-------------------------------------------------------+
| datafusion |
+-------------------------------------------------------+
```"#,
standard_argument(name = "str", prefix = "String"),
argument(
name = "str_n",
description = "Subsequent string expressions to concatenate."
),
related_udf(name = "concat_ws")
)]
#[derive(Debug)]
pub struct ConcatFunc {
signature: Signature,
Expand Down Expand Up @@ -264,40 +283,14 @@ impl ScalarUDFImpl for ConcatFunc {
}

fn documentation(&self) -> Option<&Documentation> {
Some(get_concat_doc())
self.doc()
}

fn preserves_lex_ordering(&self, _inputs: &[ExprProperties]) -> Result<bool> {
Ok(true)
}
}

static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();

fn get_concat_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_STRING,
"Concatenates multiple strings together.",
"concat(str[, ..., str_n])",
)
.with_sql_example(
r#"```sql
> select concat('data', 'f', 'us', 'ion');
+-------------------------------------------------------+
| concat(Utf8("data"),Utf8("f"),Utf8("us"),Utf8("ion")) |
+-------------------------------------------------------+
| datafusion |
+-------------------------------------------------------+
```"#,
)
.with_standard_argument("str", Some("String"))
.with_argument("str_n", "Subsequent string expressions to concatenate.")
.with_related_udf("concat_ws")
.build()
})
}

pub fn simplify_concat(args: Vec<Expr>) -> Result<ExprSimplifyResult> {
let mut new_args = Vec::with_capacity(args.len());
let mut contiguous_scalar = "".to_string();
Expand Down
62 changes: 29 additions & 33 deletions datafusion/functions/src/string/concat_ws.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

use arrow::array::{as_largestring_array, Array, StringArray};
use std::any::Any;
use std::sync::{Arc, OnceLock};
use std::sync::Arc;

use arrow::datatypes::DataType;

Expand All @@ -27,11 +27,37 @@ use crate::strings::{ColumnarValueRef, StringArrayBuilder};
use datafusion_common::cast::{as_string_array, as_string_view_array};
use datafusion_common::{exec_err, internal_err, plan_err, Result, ScalarValue};
use datafusion_expr::expr::ScalarFunction;
use datafusion_expr::scalar_doc_sections::DOC_SECTION_STRING;
use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo};
use datafusion_expr::{lit, ColumnarValue, Documentation, Expr, Volatility};
use datafusion_expr::{ScalarUDFImpl, Signature};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "String Functions"),
description = "Concatenates multiple strings together with a specified separator.",
syntax_example = "concat_ws(separator, str[, ..., str_n])",
sql_example = r#"```sql
> select concat_ws('_', 'data', 'fusion');
+--------------------------------------------------+
| concat_ws(Utf8("_"),Utf8("data"),Utf8("fusion")) |
+--------------------------------------------------+
| data_fusion |
+--------------------------------------------------+
```"#,
argument(
name = "separator",
description = "Separator to insert between concatenated strings."
),
argument(
name = "str",
description = "String expression to operate on. Can be a constant, column, or function, and any combination of operators."
),
argument(
name = "str_n",
description = "Subsequent string expressions to concatenate."
),
related_udf(name = "concat")
)]
#[derive(Debug)]
pub struct ConcatWsFunc {
signature: Signature,
Expand Down Expand Up @@ -271,40 +297,10 @@ impl ScalarUDFImpl for ConcatWsFunc {
}

fn documentation(&self) -> Option<&Documentation> {
Some(get_concat_ws_doc())
self.doc()
}
}

static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();

fn get_concat_ws_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_STRING,
"Concatenates multiple strings together with a specified separator.",
"concat_ws(separator, str[, ..., str_n])",
)
.with_sql_example(
r#"```sql
> select concat_ws('_', 'data', 'fusion');
+--------------------------------------------------+
| concat_ws(Utf8("_"),Utf8("data"),Utf8("fusion")) |
+--------------------------------------------------+
| data_fusion |
+--------------------------------------------------+
```"#,
)
.with_argument(
"separator",
"Separator to insert between concatenated strings.",
)
.with_standard_argument("str", Some("String"))
.with_argument("str_n", "Subsequent string expressions to concatenate.")
.with_related_udf("concat")
.build()
})
}

fn simplify_concat_ws(delimiter: &Expr, args: &[Expr]) -> Result<ExprSimplifyResult> {
match delimiter {
Expr::Literal(
Expand Down
58 changes: 24 additions & 34 deletions datafusion/functions/src/string/ends_with.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,38 @@
// under the License.

use std::any::Any;
use std::sync::{Arc, OnceLock};
use std::sync::Arc;

use arrow::array::ArrayRef;
use arrow::datatypes::DataType;

use crate::utils::make_scalar_function;
use datafusion_common::{internal_err, Result};
use datafusion_expr::scalar_doc_sections::DOC_SECTION_STRING;
use datafusion_expr::{ColumnarValue, Documentation, Volatility};
use datafusion_expr::{ScalarUDFImpl, Signature};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "String Functions"),
description = "Tests if a string ends with a substring.",
syntax_example = "ends_with(str, substr)",
sql_example = r#"```sql
> select ends_with('datafusion', 'soin');
+--------------------------------------------+
| ends_with(Utf8("datafusion"),Utf8("soin")) |
+--------------------------------------------+
| false |
+--------------------------------------------+
> select ends_with('datafusion', 'sion');
+--------------------------------------------+
| ends_with(Utf8("datafusion"),Utf8("sion")) |
+--------------------------------------------+
| true |
+--------------------------------------------+
```"#,
standard_argument(name = "str", prefix = "String"),
argument(name = "substr", description = "Substring to test for.")
)]
#[derive(Debug)]
pub struct EndsWithFunc {
signature: Signature,
Expand Down Expand Up @@ -79,41 +100,10 @@ impl ScalarUDFImpl for EndsWithFunc {
}

fn documentation(&self) -> Option<&Documentation> {
Some(get_ends_with_doc())
self.doc()
}
}

static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();

fn get_ends_with_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_STRING,
"Tests if a string ends with a substring.",
"ends_with(str, substr)",
)
.with_sql_example(
r#"```sql
> select ends_with('datafusion', 'soin');
+--------------------------------------------+
| ends_with(Utf8("datafusion"),Utf8("soin")) |
+--------------------------------------------+
| false |
+--------------------------------------------+
> select ends_with('datafusion', 'sion');
+--------------------------------------------+
| ends_with(Utf8("datafusion"),Utf8("sion")) |
+--------------------------------------------+
| true |
+--------------------------------------------+
```"#,
)
.with_standard_argument("str", Some("String"))
.with_argument("substr", "Substring to test for.")
.build()
})
}

/// Returns true if string ends with suffix.
/// ends_with('alphabet', 'abet') = 't'
pub fn ends_with(args: &[ArrayRef]) -> Result<ArrayRef> {
Expand Down
49 changes: 24 additions & 25 deletions datafusion/functions/src/string/levenshtein.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
// under the License.

use std::any::Any;
use std::sync::{Arc, OnceLock};
use std::sync::Arc;

use arrow::array::{ArrayRef, Int32Array, Int64Array, OffsetSizeTrait};
use arrow::datatypes::DataType;
Expand All @@ -25,10 +25,31 @@ use crate::utils::{make_scalar_function, utf8_to_int_type};
use datafusion_common::cast::{as_generic_string_array, as_string_view_array};
use datafusion_common::utils::datafusion_strsim;
use datafusion_common::{exec_err, Result};
use datafusion_expr::scalar_doc_sections::DOC_SECTION_STRING;
use datafusion_expr::{ColumnarValue, Documentation};
use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "String Functions"),
description = "Returns the [`Levenshtein distance`](https://en.wikipedia.org/wiki/Levenshtein_distance) between the two given strings.",
syntax_example = "levenshtein(str1, str2)",
sql_example = r#"```sql
> select levenshtein('kitten', 'sitting');
+---------------------------------------------+
| levenshtein(Utf8("kitten"),Utf8("sitting")) |
+---------------------------------------------+
| 3 |
+---------------------------------------------+
```"#,
argument(
name = "str1",
description = "String expression to compute Levenshtein distance with str2."
),
argument(
name = "str2",
description = "String expression to compute Levenshtein distance with str1."
)
)]
#[derive(Debug)]
pub struct LevenshteinFunc {
signature: Signature,
Expand Down Expand Up @@ -82,32 +103,10 @@ impl ScalarUDFImpl for LevenshteinFunc {
}

fn documentation(&self) -> Option<&Documentation> {
Some(get_levenshtein_doc())
self.doc()
}
}

static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();

fn get_levenshtein_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_STRING,
"Returns the [`Levenshtein distance`](https://en.wikipedia.org/wiki/Levenshtein_distance) between the two given strings.",
"levenshtein(str1, str2)")
.with_sql_example(r#"```sql
> select levenshtein('kitten', 'sitting');
+---------------------------------------------+
| levenshtein(Utf8("kitten"),Utf8("sitting")) |
+---------------------------------------------+
| 3 |
+---------------------------------------------+
```"#)
.with_argument("str1", "String expression to compute Levenshtein distance with str2.")
.with_argument("str2", "String expression to compute Levenshtein distance with str1.")
.build()
})
}

///Returns the Levenshtein distance between the two given strings.
/// LEVENSHTEIN('kitten', 'sitting') = 3
pub fn levenshtein<T: OffsetSizeTrait>(args: &[ArrayRef]) -> Result<ArrayRef> {
Expand Down
Loading
Loading