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.

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 (datetime) documentation 2/2 #13921

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
77 changes: 37 additions & 40 deletions datafusion/functions/src/datetime/make_date.rs
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::builder::PrimitiveBuilder;
use arrow::array::cast::AsArray;
Expand All @@ -27,11 +27,45 @@ use arrow::datatypes::DataType::{Date32, Int32, Int64, UInt32, UInt64, Utf8, Utf
use chrono::prelude::*;

use datafusion_common::{exec_err, Result, ScalarValue};
use datafusion_expr::scalar_doc_sections::DOC_SECTION_DATETIME;
use datafusion_expr::{
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "Time and Date Functions"),
description = "Make a date from year/month/day component parts.",
syntax_example = "make_date(year, month, day)",
sql_example = r#"```sql
> select make_date(2023, 1, 31);
+-------------------------------------------+
| make_date(Int64(2023),Int64(1),Int64(31)) |
+-------------------------------------------+
| 2023-01-31 |
+-------------------------------------------+
> select make_date('2023', '01', '31');
+-----------------------------------------------+
| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) |
+-----------------------------------------------+
| 2023-01-31 |
+-----------------------------------------------+
```

Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/make_date.rs)
"#,
argument(
name = "year",
description = "Year to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
),
argument(
name = "month",
description = "Month to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
),
argument(
name = "day",
description = "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
)
)]
#[derive(Debug)]
pub struct MakeDateFunc {
signature: Signature,
Expand Down Expand Up @@ -156,47 +190,10 @@ impl ScalarUDFImpl for MakeDateFunc {
Ok(value)
}
fn documentation(&self) -> Option<&Documentation> {
Some(get_make_date_doc())
self.doc()
}
}

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

fn get_make_date_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_DATETIME,
"Make a date from year/month/day component parts.",
"make_date(year, month, day)")
.with_argument(
"year",
" Year to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.", )
.with_argument(
"month",
"Month to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.",
)
.with_argument("day", "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.")
.with_sql_example(r#"```sql
> select make_date(2023, 1, 31);
+-------------------------------------------+
| make_date(Int64(2023),Int64(1),Int64(31)) |
+-------------------------------------------+
| 2023-01-31 |
+-------------------------------------------+
> select make_date('2023', '01', '31');
+-----------------------------------------------+
| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) |
+-----------------------------------------------+
| 2023-01-31 |
+-----------------------------------------------+
```

Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/make_date.rs)
"#)
.build()
})
}

/// Converts the year/month/day fields to an `i32` representing the days from
/// the unix epoch and invokes `date_consumer_fn` with the value
fn make_date_inner<F: FnMut(i32)>(
Expand Down
33 changes: 13 additions & 20 deletions datafusion/functions/src/datetime/now.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,23 @@ use arrow::datatypes::DataType;
use arrow::datatypes::DataType::Timestamp;
use arrow::datatypes::TimeUnit::Nanosecond;
use std::any::Any;
use std::sync::OnceLock;

use datafusion_common::{internal_err, ExprSchema, Result, ScalarValue};
use datafusion_expr::scalar_doc_sections::DOC_SECTION_DATETIME;
use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo};
use datafusion_expr::{
ColumnarValue, Documentation, Expr, ScalarUDFImpl, Signature, Volatility,
};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "Time and Date Functions"),
description = r#"
Returns the current UTC timestamp.

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.
"#,
syntax_example = "now()"
)]
#[derive(Debug)]
pub struct NowFunc {
signature: Signature,
Expand Down Expand Up @@ -93,9 +101,6 @@ impl ScalarUDFImpl for NowFunc {
ScalarValue::TimestampNanosecond(now_ts, Some("+00:00".into())),
)))
}
fn documentation(&self) -> Option<&Documentation> {
Some(get_to_unixtime_doc())
}

fn aliases(&self) -> &[String] {
&self.aliases
Expand All @@ -104,20 +109,8 @@ impl ScalarUDFImpl for NowFunc {
fn is_nullable(&self, _args: &[Expr], _schema: &dyn ExprSchema) -> bool {
false
}
}

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

fn get_to_unixtime_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_DATETIME,
r#"
Returns the current UTC timestamp.

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.
"#,
"now()")
.build()
})
fn documentation(&self) -> Option<&Documentation> {
self.doc()
}
}
66 changes: 31 additions & 35 deletions datafusion/functions/src/datetime/to_char.rs
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::cast::AsArray;
use arrow::array::{new_null_array, Array, ArrayRef, StringArray};
Expand All @@ -29,12 +29,40 @@ use arrow::error::ArrowError;
use arrow::util::display::{ArrayFormatter, DurationFormat, FormatOptions};

use datafusion_common::{exec_err, Result, ScalarValue};
use datafusion_expr::scalar_doc_sections::DOC_SECTION_DATETIME;
use datafusion_expr::TypeSignature::Exact;
use datafusion_expr::{
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, TIMEZONE_WILDCARD,
};
use datafusion_macros::user_doc;

#[user_doc(
doc_section(label = "Time and Date Functions"),
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.",
syntax_example = "to_char(expression, format)",
sql_example = r#"```sql
> select to_char('2023-03-01'::date, '%d-%m-%Y');
+----------------------------------------------+
| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) |
+----------------------------------------------+
| 01-03-2023 |
+----------------------------------------------+
```

Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_char.rs)
"#,
argument(
name = "expression",
description = "Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration."
),
argument(
name = "format",
description = "A [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) string to use to convert the expression."
),
argument(
name = "day",
description = "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators."
)
)]
#[derive(Debug)]
pub struct ToCharFunc {
signature: Signature,
Expand Down Expand Up @@ -143,42 +171,10 @@ impl ScalarUDFImpl for ToCharFunc {
&self.aliases
}
fn documentation(&self) -> Option<&Documentation> {
Some(get_to_char_doc())
self.doc()
}
}

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

fn get_to_char_doc() -> &'static Documentation {
DOCUMENTATION.get_or_init(|| {
Documentation::builder(
DOC_SECTION_DATETIME,
"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.",
"to_char(expression, format)")
.with_argument(
"expression",
" Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration."
)
.with_argument(
"format",
"A [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) string to use to convert the expression.",
)
.with_argument("day", "Day to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.")
.with_sql_example(r#"```sql
> select to_char('2023-03-01'::date, '%d-%m-%Y');
+----------------------------------------------+
| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) |
+----------------------------------------------+
| 01-03-2023 |
+----------------------------------------------+
```

Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_char.rs)
"#)
.build()
})
}

fn _build_format_options<'a>(
data_type: &DataType,
format: Option<&'a str>,
Expand Down
32 changes: 17 additions & 15 deletions datafusion/functions/src/datetime/to_date.rs
Original file line number Diff line number Diff line change
Expand Up @@ -38,21 +38,23 @@ Returns the corresponding date.

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`.",
syntax_example = "to_date('2017-05-31', '%Y-%m-%d')",
sql_example = "```sql\n\
> select to_date('2023-01-31');\n\
+-----------------------------+\n\
| to_date(Utf8(\"2023-01-31\")) |\n\
+-----------------------------+\n\
| 2023-01-31 |\n\
+-----------------------------+\n\
> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d');\n\
+---------------------------------------------------------------+\n\
| to_date(Utf8(\"2023/01/31\"),Utf8(\"%Y-%m-%d\"),Utf8(\"%Y/%m/%d\")) |\n\
+---------------------------------------------------------------+\n\
| 2023-01-31 |\n\
+---------------------------------------------------------------+\n\
```\n\n\
Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs)",
sql_example = r#"```sql
> select to_date('2023-01-31');
+-------------------------------+
| to_date(Utf8("2023-01-31")) |
+-------------------------------+
| 2023-01-31 |
+-------------------------------+
> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d');
+---------------------------------------------------------------------+
| to_date(Utf8("2023/01/31"),Utf8("%Y-%m-%d"),Utf8("%Y/%m/%d")) |
+---------------------------------------------------------------------+
| 2023-01-31 |
+---------------------------------------------------------------------+
```

Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs)
"#,
standard_argument(name = "expression", prefix = "String"),
argument(
name = "format_n",
Expand Down
Loading
Loading