Skip to content

Commit

Permalink
doc-gen: migrate scalar functions (array) documentation 3/3 (#13930)
Browse files Browse the repository at this point in the history 
* doc-gen: migrate scalar functions (array) documentation 3/3

* fix: import doc and macro, fix typo and update function docs

---------

Co-authored-by: Cheng-Yuan-Lai <a186235@g,ail.com>
  • Loading branch information
@Chen-Yuan-Lai
Chen-Yuan-Lai and Cheng-Yuan-Lai authored Dec 29, 2024
1 parent fce3fb3 commit 2b4e200
Show file tree
Hide file tree
Showing 10 changed files with 486 additions and 662 deletions.
144 changes: 63 additions & 81 deletions datafusion/functions-nested/src/range.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,16 +37,16 @@ use datafusion_common::cast::{
use datafusion_common::{
exec_datafusion_err, exec_err, internal_err, not_impl_datafusion_err, Result,
};
use datafusion_expr::scalar_doc_sections::DOC_SECTION_ARRAY;
use datafusion_expr::{
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
};
use datafusion_macros::user_doc;
use itertools::Itertools;
use std::any::Any;
use std::cmp::Ordering;
use std::iter::from_fn;
use std::str::FromStr;
use std::sync::{Arc, OnceLock};
use std::sync::Arc;

make_udf_expr_and_func!(
Range,
Expand All @@ -55,6 +55,39 @@ make_udf_expr_and_func!(
"create a list of values in the range between start and stop",
range_udf
);

#[user_doc(
doc_section(label = "Array Functions"),
description = "Returns an Arrow array between start and stop with step. The range start..end contains all values with start <= x < end. It is empty if start >= end. Step cannot be 0.",
syntax_example = "range(start, stop, step)",
sql_example = r#"```sql
> select range(2, 10, 3);
+-----------------------------------+
| range(Int64(2),Int64(10),Int64(3))|
+-----------------------------------+
| [2, 5, 8] |
+-----------------------------------+
> select range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH);
+--------------------------------------------------------------+
| range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH) |
+--------------------------------------------------------------+
| [1992-09-01, 1992-10-01, 1992-11-01, 1992-12-01, 1993-01-01, 1993-02-01] |
+--------------------------------------------------------------+
```"#,
argument(
name = "start",
description = "Start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported."
),
argument(
name = "end",
description = "End of the range (not included). Type must be the same as start."
),
argument(
name = "step",
description = "Increase by step (cannot be 0). Steps less than a day are supported only for timestamp ranges."
)
)]
#[derive(Debug)]
pub(super) struct Range {
signature: Signature,
Expand Down Expand Up @@ -141,59 +174,43 @@ impl ScalarUDFImpl for Range {
}

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

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

fn get_range_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_ARRAY,
"Returns an Arrow array between start and stop with step. The range start..end contains all values with start <= x < end. It is empty if start >= end. Step cannot be 0.",

"range(start, stop, step)")
.with_sql_example(
r#"```sql
> select range(2, 10, 3);
+-----------------------------------+
| range(Int64(2),Int64(10),Int64(3))|
+-----------------------------------+
| [2, 5, 8] |
+-----------------------------------+
> select range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH);
+--------------------------------------------------------------+
| range(DATE '1992-09-01', DATE '1993-03-01', INTERVAL '1' MONTH) |
+--------------------------------------------------------------+
| [1992-09-01, 1992-10-01, 1992-11-01, 1992-12-01, 1993-01-01, 1993-02-01] |
+--------------------------------------------------------------+
```"#,
)
.with_argument(
"start",
"Start of the range. Ints, timestamps, dates or string types that can be coerced to Date32 are supported.",
)
.with_argument(
"end",
"End of the range (not included). Type must be the same as start.",
)
.with_argument(
"step",
"Increase by step (cannot be 0). Steps less than a day are supported only for timestamp ranges.",
)
.build()
})
}

make_udf_expr_and_func!(
GenSeries,
gen_series,
start stop step,
"create a list of values in the range between start and stop, include upper bound",
gen_series_udf
);

#[user_doc(
doc_section(label = "Array Functions"),
description = "Similar to the range function, but it includes the upper bound.",
syntax_example = "generate_series(start, stop, step)",
sql_example = r#"```sql
> select generate_series(1,3);
+------------------------------------+
| generate_series(Int64(1),Int64(3)) |
+------------------------------------+
| [1, 2, 3] |
+------------------------------------+
```"#,
argument(
name = "start",
description = "Start of the series. Ints, timestamps, dates or string types that can be coerced to Date32 are supported."
),
argument(
name = "end",
description = "End of the series (included). Type must be the same as start."
),
argument(
name = "step",
description = "Increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges."
)
)]
#[derive(Debug)]
pub(super) struct GenSeries {
signature: Signature,
Expand Down Expand Up @@ -283,45 +300,10 @@ impl ScalarUDFImpl for GenSeries {
}

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

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

fn get_generate_series_doc() -> &'static Documentation {
GENERATE_SERIES_DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_ARRAY,
"Similar to the range function, but it includes the upper bound.",

"generate_series(start, stop, step)")
.with_sql_example(
r#"```sql
> select generate_series(1,3);
+------------------------------------+
| generate_series(Int64(1),Int64(3)) |
+------------------------------------+
| [1, 2, 3] |
+------------------------------------+
```"#,
)
.with_argument(
"start",
"start of the series. Ints, timestamps, dates or string types that can be coerced to Date32 are supported.",
)
.with_argument(
"end",
"end of the series (included). Type must be the same as start.",
)
.with_argument(
"step",
"increase by step (can not be 0). Steps less than a day are supported only for timestamp ranges.",
)
.build()
})
}

/// Generates an array of integers from start to stop with a given step.
///
/// This function takes 1 to 3 ArrayRefs as arguments, representing start, stop, and step values.
Expand Down
Loading

0 comments on commit 2b4e200

Please sign in to comment.