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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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 defaultThe `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.mdindex 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 tinow()```+#### 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