Skip to content

Commit 9eca7d1

Browse files
Chen-Yuan-LaiCheng-Yuan-Lai
Chen-Yuan-Lai
and
Cheng-Yuan-Lai
authored
doc-gen: migrate scalar functions (datetime) documentation 2/2 (apache#13921)
* doc-gen: migrate scalar functions (datetime) documentation 2/2 * fix: fix typo and update function docs * doc: update function docs * doc-gen: remove slash --------- Co-authored-by: Cheng-Yuan-Lai <a186235@g,ail.com>
1 parent 9d39358 commit 9eca7d1

File tree

8 files changed

+351
-411
lines changed

8 files changed

+351
-411
lines changed

‎datafusion/functions/src/datetime/make_date.rs

+37-40
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::{Arc, OnceLock};
19+
use std::sync::Arc;
2020

2121
use arrow::array::builder::PrimitiveBuilder;
2222
use arrow::array::cast::AsArray;
@@ -27,11 +27,45 @@ use arrow::datatypes::DataType::{Date32, Int32, Int64, UInt32, UInt64, Utf8, Utf
2727
use chrono::prelude::*;
2828

2929
use datafusion_common::{exec_err, Result, ScalarValue};
30-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_DATETIME;
3130
use datafusion_expr::{
3231
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
3332
};
33+
use datafusion_macros::user_doc;
3434

35+
#[user_doc(
36+
doc_section(label = "Time and Date Functions"),
37+
description = "Make a date from year/month/day component parts.",
38+
syntax_example = "make_date(year, month, day)",
39+
sql_example = r#"```sql
40+
> select make_date(2023, 1, 31);
41+
+-------------------------------------------+
42+
| make_date(Int64(2023),Int64(1),Int64(31)) |
43+
+-------------------------------------------+
44+
| 2023-01-31 |
45+
+-------------------------------------------+
46+
> select make_date('2023', '01', '31');
47+
+-----------------------------------------------+
48+
| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) |
49+
+-----------------------------------------------+
50+
| 2023-01-31 |
51+
+-----------------------------------------------+
52+
```
53+
54+
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/make_date.rs)
55+
"#,
56+
argument(
57+
name = "year",
58+
description = "Year to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
59+
),
60+
argument(
61+
name = "month",
62+
description = "Month to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
63+
),
64+
argument(
65+
name = "day",
66+
description = "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
67+
)
68+
)]
3569
#[derive(Debug)]
3670
pub struct MakeDateFunc {
3771
signature: Signature,
@@ -156,47 +190,10 @@ impl ScalarUDFImpl for MakeDateFunc {
156190
Ok(value)
157191
}
158192
fn documentation(&self) -> Option<&Documentation> {
159-
Some(get_make_date_doc())
193+
self.doc()
160194
}
161195
}
162196

163-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
164-
165-
fn get_make_date_doc() -> &'static Documentation {
166-
DOCUMENTATION.get_or_init(|| {
167-
Documentation::builder(
168-
DOC_SECTION_DATETIME,
169-
"Make a date from year/month/day component parts.",
170-
"make_date(year, month, day)")
171-
.with_argument(
172-
"year",
173-
" Year to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.", )
174-
.with_argument(
175-
"month",
176-
"Month to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.",
177-
)
178-
.with_argument("day", "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.")
179-
.with_sql_example(r#"```sql
180-
> select make_date(2023, 1, 31);
181-
+-------------------------------------------+
182-
| make_date(Int64(2023),Int64(1),Int64(31)) |
183-
+-------------------------------------------+
184-
| 2023-01-31 |
185-
+-------------------------------------------+
186-
> select make_date('2023', '01', '31');
187-
+-----------------------------------------------+
188-
| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) |
189-
+-----------------------------------------------+
190-
| 2023-01-31 |
191-
+-----------------------------------------------+
192-
```
193-
194-
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/make_date.rs)
195-
"#)
196-
.build()
197-
})
198-
}
199-
200197
/// Converts the year/month/day fields to an `i32` representing the days from
201198
/// the unix epoch and invokes `date_consumer_fn` with the value
202199
fn make_date_inner<F: FnMut(i32)>(

‎datafusion/functions/src/datetime/now.rs

+13-20
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,23 @@ use arrow::datatypes::DataType;
1919
use arrow::datatypes::DataType::Timestamp;
2020
use arrow::datatypes::TimeUnit::Nanosecond;
2121
use std::any::Any;
22-
use std::sync::OnceLock;
2322

2423
use datafusion_common::{internal_err, ExprSchema, Result, ScalarValue};
25-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_DATETIME;
2624
use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo};
2725
use datafusion_expr::{
2826
ColumnarValue, Documentation, Expr, ScalarUDFImpl, Signature, Volatility,
2927
};
28+
use datafusion_macros::user_doc;
3029

30+
#[user_doc(
31+
doc_section(label = "Time and Date Functions"),
32+
description = r#"
33+
Returns the current UTC timestamp.
34+
35+
The `now()` return value is determined at query time and will return the same timestamp, no matter when in the query plan the function executes.
36+
"#,
37+
syntax_example = "now()"
38+
)]
3139
#[derive(Debug)]
3240
pub struct NowFunc {
3341
signature: Signature,
@@ -93,9 +101,6 @@ impl ScalarUDFImpl for NowFunc {
93101
ScalarValue::TimestampNanosecond(now_ts, Some("+00:00".into())),
94102
)))
95103
}
96-
fn documentation(&self) -> Option<&Documentation> {
97-
Some(get_to_unixtime_doc())
98-
}
99104

100105
fn aliases(&self) -> &[String] {
101106
&self.aliases
@@ -104,20 +109,8 @@ impl ScalarUDFImpl for NowFunc {
104109
fn is_nullable(&self, _args: &[Expr], _schema: &dyn ExprSchema) -> bool {
105110
false
106111
}
107-
}
108112

109-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
110-
111-
fn get_to_unixtime_doc() -> &'static Documentation {
112-
DOCUMENTATION.get_or_init(|| {
113-
Documentation::builder(
114-
DOC_SECTION_DATETIME,
115-
r#"
116-
Returns the current UTC timestamp.
117-
118-
The `now()` return value is determined at query time and will return the same timestamp, no matter when in the query plan the function executes.
119-
"#,
120-
"now()")
121-
.build()
122-
})
113+
fn documentation(&self) -> Option<&Documentation> {
114+
self.doc()
115+
}
123116
}

‎datafusion/functions/src/datetime/to_char.rs

+31-35
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::{Arc, OnceLock};
19+
use std::sync::Arc;
2020

2121
use arrow::array::cast::AsArray;
2222
use arrow::array::{new_null_array, Array, ArrayRef, StringArray};
@@ -29,12 +29,40 @@ use arrow::error::ArrowError;
2929
use arrow::util::display::{ArrayFormatter, DurationFormat, FormatOptions};
3030

3131
use datafusion_common::{exec_err, Result, ScalarValue};
32-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_DATETIME;
3332
use datafusion_expr::TypeSignature::Exact;
3433
use datafusion_expr::{
3534
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, TIMEZONE_WILDCARD,
3635
};
36+
use datafusion_macros::user_doc;
3737

38+
#[user_doc(
39+
doc_section(label = "Time and Date Functions"),
40+
description = "Returns a string representation of a date, time, timestamp or duration based on a [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). Unlike the PostgreSQL equivalent of this function numerical formatting is not supported.",
41+
syntax_example = "to_char(expression, format)",
42+
sql_example = r#"```sql
43+
> select to_char('2023-03-01'::date, '%d-%m-%Y');
44+
+----------------------------------------------+
45+
| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) |
46+
+----------------------------------------------+
47+
| 01-03-2023 |
48+
+----------------------------------------------+
49+
```
50+
51+
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_char.rs)
52+
"#,
53+
argument(
54+
name = "expression",
55+
description = "Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration."
56+
),
57+
argument(
58+
name = "format",
59+
description = "A [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) string to use to convert the expression."
60+
),
61+
argument(
62+
name = "day",
63+
description = "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
64+
)
65+
)]
3866
#[derive(Debug)]
3967
pub struct ToCharFunc {
4068
signature: Signature,
@@ -143,42 +171,10 @@ impl ScalarUDFImpl for ToCharFunc {
143171
&self.aliases
144172
}
145173
fn documentation(&self) -> Option<&Documentation> {
146-
Some(get_to_char_doc())
174+
self.doc()
147175
}
148176
}
149177

150-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
151-
152-
fn get_to_char_doc() -> &'static Documentation {
153-
DOCUMENTATION.get_or_init(|| {
154-
Documentation::builder(
155-
DOC_SECTION_DATETIME,
156-
"Returns a string representation of a date, time, timestamp or duration based on a [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). Unlike the PostgreSQL equivalent of this function numerical formatting is not supported.",
157-
"to_char(expression, format)")
158-
.with_argument(
159-
"expression",
160-
" Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration."
161-
)
162-
.with_argument(
163-
"format",
164-
"A [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) string to use to convert the expression.",
165-
)
166-
.with_argument("day", "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.")
167-
.with_sql_example(r#"```sql
168-
> select to_char('2023-03-01'::date, '%d-%m-%Y');
169-
+----------------------------------------------+
170-
| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) |
171-
+----------------------------------------------+
172-
| 01-03-2023 |
173-
+----------------------------------------------+
174-
```
175-
176-
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_char.rs)
177-
"#)
178-
.build()
179-
})
180-
}
181-
182178
fn _build_format_options<'a>(
183179
data_type: &DataType,
184180
format: Option<&'a str>,

‎datafusion/functions/src/datetime/to_date.rs

+17-15
Original file line numberDiff line numberDiff line change
@@ -38,21 +38,23 @@ Returns the corresponding date.
3838
3939
Note: `to_date` returns Date32, which represents its values as the number of days since unix epoch(`1970-01-01`) stored as signed 32 bit value. The largest supported date value is `9999-12-31`.",
4040
syntax_example = "to_date('2017-05-31', '%Y-%m-%d')",
41-
sql_example = "```sql\n\
42-
> select to_date('2023-01-31');\n\
43-
+-----------------------------+\n\
44-
| to_date(Utf8(\"2023-01-31\")) |\n\
45-
+-----------------------------+\n\
46-
| 2023-01-31 |\n\
47-
+-----------------------------+\n\
48-
> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d');\n\
49-
+---------------------------------------------------------------+\n\
50-
| to_date(Utf8(\"2023/01/31\"),Utf8(\"%Y-%m-%d\"),Utf8(\"%Y/%m/%d\")) |\n\
51-
+---------------------------------------------------------------+\n\
52-
| 2023-01-31 |\n\
53-
+---------------------------------------------------------------+\n\
54-
```\n\n\
55-
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs)",
41+
sql_example = r#"```sql
42+
> select to_date('2023-01-31');
43+
+-------------------------------+
44+
| to_date(Utf8("2023-01-31")) |
45+
+-------------------------------+
46+
| 2023-01-31 |
47+
+-------------------------------+
48+
> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d');
49+
+---------------------------------------------------------------------+
50+
| to_date(Utf8("2023/01/31"),Utf8("%Y-%m-%d"),Utf8("%Y/%m/%d")) |
51+
+---------------------------------------------------------------------+
52+
| 2023-01-31 |
53+
+---------------------------------------------------------------------+
54+
```
55+
56+
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs)
57+
"#,
5658
standard_argument(name = "expression", prefix = "String"),
5759
argument(
5860
name = "format_n",

0 commit comments

Comments
 (0)