From 27832b9092b407f59031ce173e7df552b50d2170 Mon Sep 17 00:00:00 2001 From: buraksenn Date: Fri, 20 Mar 2026 21:10:51 +0300 Subject: [PATCH] chore: added sql example to datetime docs --- .../functions/src/datetime/current_date.rs | 19 +++- .../functions/src/datetime/current_time.rs | 19 +++- .../functions/src/datetime/date_part.rs | 16 +++- .../functions/src/datetime/date_trunc.rs | 16 +++- datafusion/functions/src/datetime/now.rs | 19 +++- .../source/user-guide/sql/scalar_functions.md | 94 +++++++++++++++++++ 6 files changed, 178 insertions(+), 5 deletions(-) diff --git a/datafusion/functions/src/datetime/current_date.rs b/datafusion/functions/src/datetime/current_date.rs index f0571b94fa8d7..68c640a60dbf7 100644 --- a/datafusion/functions/src/datetime/current_date.rs +++ b/datafusion/functions/src/datetime/current_date.rs @@ -39,7 +39,24 @@ The `current_date()` return value is determined at query time and will return th "#, syntax_example = r#"current_date() (optional) SET datafusion.execution.time_zone = '+00:00'; - SELECT current_date();"# + SELECT current_date();"#, + sql_example = r#"```sql +> SELECT current_date(); ++----------------+ +| current_date() | ++----------------+ +| 2024-12-23 | ++----------------+ + +-- The current date is based on the session time zone (UTC by default) +> SET datafusion.execution.time_zone = 'Asia/Tokyo'; +> SELECT current_date(); ++----------------+ +| current_date() | ++----------------+ +| 2024-12-24 | ++----------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct CurrentDateFunc { diff --git a/datafusion/functions/src/datetime/current_time.rs b/datafusion/functions/src/datetime/current_time.rs index 2ac5cf96d0316..215b23b585868 100644 --- a/datafusion/functions/src/datetime/current_time.rs +++ b/datafusion/functions/src/datetime/current_time.rs @@ -41,7 +41,24 @@ The session time zone can be set using the statement 'SET datafusion.execution.t "#, syntax_example = r#"current_time() (optional) SET datafusion.execution.time_zone = '+00:00'; - SELECT current_time();"# + SELECT current_time();"#, + sql_example = r#"```sql +> SELECT current_time(); ++--------------------+ +| current_time() | ++--------------------+ +| 06:30:00.123456789 | ++--------------------+ + +-- The current time is based on the session time zone (UTC by default) +> SET datafusion.execution.time_zone = 'Europe/London'; +> SELECT current_time(); ++--------------------+ +| current_time() | ++--------------------+ +| 07:30:00.123456789 | ++--------------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct CurrentTimeFunc { diff --git a/datafusion/functions/src/datetime/date_part.rs b/datafusion/functions/src/datetime/date_part.rs index 7a60bb883a0d2..05b5d1473cefa 100644 --- a/datafusion/functions/src/datetime/date_part.rs +++ b/datafusion/functions/src/datetime/date_part.rs @@ -87,7 +87,21 @@ use datafusion_macros::user_doc; argument( name = "expression", description = "Time expression to operate on. Can be a constant, column, or function." - ) + ), + sql_example = r#"```sql +> SELECT date_part('year', '2024-05-01T00:00:00'); ++---------------------------------------------+ +| date_part(Utf8("year"),Utf8("2024-05-01T00:00:00")) | ++---------------------------------------------+ +| 2024.0 | ++---------------------------------------------+ +> SELECT extract(day FROM timestamp '2024-05-01T00:00:00'); ++---------------------------------------------+ +| date_part(Utf8("day"),Utf8("2024-05-01T00:00:00")) | ++---------------------------------------------+ +| 1.0 | ++---------------------------------------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct DatePartFunc { diff --git a/datafusion/functions/src/datetime/date_trunc.rs b/datafusion/functions/src/datetime/date_trunc.rs index ef9896cead5a0..09c639d4545d3 100644 --- a/datafusion/functions/src/datetime/date_trunc.rs +++ b/datafusion/functions/src/datetime/date_trunc.rs @@ -167,7 +167,21 @@ impl DateTruncGranularity { argument( name = "expression", description = "Timestamp or time expression to operate on. Can be a constant, column, or function." - ) + ), + sql_example = r#"```sql +> SELECT date_trunc('month', '2024-05-15T10:30:00'); ++-----------------------------------------------+ +| date_trunc(Utf8("month"),Utf8("2024-05-15T10:30:00")) | ++-----------------------------------------------+ +| 2024-05-01T00:00:00 | ++-----------------------------------------------+ +> SELECT date_trunc('hour', '2024-05-15T10:30:00'); ++----------------------------------------------+ +| date_trunc(Utf8("hour"),Utf8("2024-05-15T10:30:00")) | ++----------------------------------------------+ +| 2024-05-15T10:00:00 | ++----------------------------------------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct DateTruncFunc { diff --git a/datafusion/functions/src/datetime/now.rs b/datafusion/functions/src/datetime/now.rs index bd67e4cfcbba0..71e687f6910e9 100644 --- a/datafusion/functions/src/datetime/now.rs +++ b/datafusion/functions/src/datetime/now.rs @@ -37,7 +37,24 @@ Returns the current timestamp in the system configured timezone (None by default 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()" + syntax_example = "now()", + sql_example = r#"```sql +> SELECT now(); ++----------------------------------+ +| now() | ++----------------------------------+ +| 2024-12-23T06:30:00.123456789Z | ++----------------------------------+ + +-- The timezone of the returned timestamp depends on the session time zone +> SET datafusion.execution.time_zone = 'America/New_York'; +> SELECT now(); ++----------------------------------+ +| now() | ++----------------------------------+ +| 2024-12-23T01:30:00.123456789Z | ++----------------------------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct NowFunc { diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index 15ce5878808ea..b15a6cc92f4a0 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -2415,6 +2415,26 @@ current_date() SELECT current_date(); ``` +#### Example + +```sql +> SELECT current_date(); ++----------------+ +| current_date() | ++----------------+ +| 2024-12-23 | ++----------------+ + +-- The current date is based on the session time zone (UTC by default) +> SET datafusion.execution.time_zone = 'Asia/Tokyo'; +> SELECT current_date(); ++----------------+ +| current_date() | ++----------------+ +| 2024-12-24 | ++----------------+ +``` + #### Aliases - today @@ -2433,6 +2453,26 @@ current_time() SELECT current_time(); ``` +#### Example + +```sql +> SELECT current_time(); ++--------------------+ +| current_time() | ++--------------------+ +| 06:30:00.123456789 | ++--------------------+ + +-- The current time is based on the session time zone (UTC by default) +> SET datafusion.execution.time_zone = 'Europe/London'; +> SELECT current_time(); ++--------------------+ +| current_time() | ++--------------------+ +| 07:30:00.123456789 | ++--------------------+ +``` + ### `current_timestamp` _Alias of [now](#now)._ @@ -2537,6 +2577,23 @@ date_part(part, expression) - **expression**: Time expression to operate on. Can be a constant, column, or function. +#### Example + +```sql +> SELECT date_part('year', '2024-05-01T00:00:00'); ++---------------------------------------------+ +| date_part(Utf8("year"),Utf8("2024-05-01T00:00:00")) | ++---------------------------------------------+ +| 2024.0 | ++---------------------------------------------+ +> SELECT extract(day FROM timestamp '2024-05-01T00:00:00'); ++---------------------------------------------+ +| date_part(Utf8("day"),Utf8("2024-05-01T00:00:00")) | ++---------------------------------------------+ +| 1.0 | ++---------------------------------------------+ +``` + #### Alternative Syntax ```sql @@ -2582,6 +2639,23 @@ date_trunc(precision, expression) - **expression**: Timestamp or time expression to operate on. Can be a constant, column, or function. +#### Example + +```sql +> SELECT date_trunc('month', '2024-05-15T10:30:00'); ++-----------------------------------------------+ +| date_trunc(Utf8("month"),Utf8("2024-05-15T10:30:00")) | ++-----------------------------------------------+ +| 2024-05-01T00:00:00 | ++-----------------------------------------------+ +> SELECT date_trunc('hour', '2024-05-15T10:30:00'); ++----------------------------------------------+ +| date_trunc(Utf8("hour"),Utf8("2024-05-15T10:30:00")) | ++----------------------------------------------+ +| 2024-05-15T10:00:00 | ++----------------------------------------------+ +``` + #### Aliases - datetrunc @@ -2694,6 +2768,26 @@ The `now()` return value is determined at query time and will return the same ti now() ``` +#### Example + +```sql +> SELECT now(); ++----------------------------------+ +| now() | ++----------------------------------+ +| 2024-12-23T06:30:00.123456789Z | ++----------------------------------+ + +-- The timezone of the returned timestamp depends on the session time zone +> SET datafusion.execution.time_zone = 'America/New_York'; +> SELECT now(); ++----------------------------------+ +| now() | ++----------------------------------+ +| 2024-12-23T01:30:00.123456789Z | ++----------------------------------+ +``` + #### Aliases - current_timestamp