Skip to content

Apache DataFusion SQL Query Engine

[docs] add sql example to timestamp/datetime docs for time zone (#21082)

Burak Şend86874ed3305
diff --git a/datafusion/functions/src/datetime/current_date.rs b/datafusion/functions/src/datetime/current_date.rs
index da9f6946d2..d07a3b1caf 100644
--- a/datafusion/functions/src/datetime/current_date.rs
+++ b/datafusion/functions/src/datetime/current_date.rs
@@ -37,7 +37,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 b42f3ada3f..92f4ae5e66 100644
--- a/datafusion/functions/src/datetime/current_time.rs
+++ b/datafusion/functions/src/datetime/current_time.rs
@@ -40,7 +40,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 = 'Asia/Tokyo';
+> SELECT current_time();
++--------------------+
+| current_time() |
++--------------------+
+| 15: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 24d6ff9cfb..10275f5aae 100644
--- a/datafusion/functions/src/datetime/date_part.rs
+++ b/datafusion/functions/src/datetime/date_part.rs
@@ -86,7 +86,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 |
++-----------------------------------------------------+
+> SELECT extract(day FROM timestamp '2024-05-01T00:00:00');
++----------------------------------------------------+
+| date_part(Utf8("DAY"),Utf8("2024-05-01T00:00:00")) |
++----------------------------------------------------+
+| 1 |
++----------------------------------------------------+
+```"#
)]
#[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 c952f1f392..a97fd138ec 100644
--- a/datafusion/functions/src/datetime/date_trunc.rs
+++ b/datafusion/functions/src/datetime/date_trunc.rs
@@ -166,7 +166,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 2e3cd453d2..82bb1251b2 100644
--- a/datafusion/functions/src/datetime/now.rs
+++ b/datafusion/functions/src/datetime/now.rs
@@ -36,7 +36,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.123456789 |
++----------------------------------+
+
+-- 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.123456789-05:00 |
++--------------------------------------+
+```"#
)]
#[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 022b0f9dae..c303b43fc8 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 = 'Asia/Tokyo';
+> SELECT current_time();
++--------------------+
+| current_time() |
++--------------------+
+| 15: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 |
++-----------------------------------------------------+
+> SELECT extract(day FROM timestamp '2024-05-01T00:00:00');
++----------------------------------------------------+
+| date_part(Utf8("DAY"),Utf8("2024-05-01T00:00:00")) |
++----------------------------------------------------+
+| 1 |
++----------------------------------------------------+
+```
+
#### 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.123456789 |
++----------------------------------+
+
+-- 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.123456789-05:00 |
++--------------------------------------+
+```
+
#### Aliases
- current_timestamp