Skip to content

Commit d86874e

Browse files
buraksennburaksenn
authored
[docs] add sql example to timestamp/datetime docs for time zone (apache#21082)
## Which issue does this PR close? - Closes apache#19104. ## Rationale for this change apache#19104 explains but some datetime functions respect `execution.time_zone` config but there are no SQL examples for them. This PR adds it and also missing sql example for `date_part`, `extract` and `date_trunc` ## What changes are included in this PR? sql example changes and generated doc ## Are these changes tested? ## Are there any user-facing changes?
1 parent c8aefab commit d86874e

File tree

6 files changed

+178
-5
lines changed

6 files changed

+178
-5
lines changed

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

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,24 @@ The `current_date()` return value is determined at query time and will return th
3737
"#,
3838
syntax_example = r#"current_date()
3939
(optional) SET datafusion.execution.time_zone = '+00:00';
40-
SELECT current_date();"#
40+
SELECT current_date();"#,
41+
sql_example = r#"```sql
42+
> SELECT current_date();
43+
+----------------+
44+
| current_date() |
45+
+----------------+
46+
| 2024-12-23 |
47+
+----------------+
48+
49+
-- The current date is based on the session time zone (UTC by default)
50+
> SET datafusion.execution.time_zone = 'Asia/Tokyo';
51+
> SELECT current_date();
52+
+----------------+
53+
| current_date() |
54+
+----------------+
55+
| 2024-12-24 |
56+
+----------------+
57+
```"#
4158
)]
4259
#[derive(Debug, PartialEq, Eq, Hash)]
4360
pub struct CurrentDateFunc {

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

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,24 @@ The session time zone can be set using the statement 'SET datafusion.execution.t
4040
"#,
4141
syntax_example = r#"current_time()
4242
(optional) SET datafusion.execution.time_zone = '+00:00';
43-
SELECT current_time();"#
43+
SELECT current_time();"#,
44+
sql_example = r#"```sql
45+
> SELECT current_time();
46+
+--------------------+
47+
| current_time() |
48+
+--------------------+
49+
| 06:30:00.123456789 |
50+
+--------------------+
51+
52+
-- The current time is based on the session time zone (UTC by default)
53+
> SET datafusion.execution.time_zone = 'Asia/Tokyo';
54+
> SELECT current_time();
55+
+--------------------+
56+
| current_time() |
57+
+--------------------+
58+
| 15:30:00.123456789 |
59+
+--------------------+
60+
```"#
4461
)]
4562
#[derive(Debug, PartialEq, Eq, Hash)]
4663
pub struct CurrentTimeFunc {

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

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,21 @@ use datafusion_macros::user_doc;
8686
argument(
8787
name = "expression",
8888
description = "Time expression to operate on. Can be a constant, column, or function."
89-
)
89+
),
90+
sql_example = r#"```sql
91+
> SELECT date_part('year', '2024-05-01T00:00:00');
92+
+-----------------------------------------------------+
93+
| date_part(Utf8("year"),Utf8("2024-05-01T00:00:00")) |
94+
+-----------------------------------------------------+
95+
| 2024 |
96+
+-----------------------------------------------------+
97+
> SELECT extract(day FROM timestamp '2024-05-01T00:00:00');
98+
+----------------------------------------------------+
99+
| date_part(Utf8("DAY"),Utf8("2024-05-01T00:00:00")) |
100+
+----------------------------------------------------+
101+
| 1 |
102+
+----------------------------------------------------+
103+
```"#
90104
)]
91105
#[derive(Debug, PartialEq, Eq, Hash)]
92106
pub struct DatePartFunc {

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

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,21 @@ impl DateTruncGranularity {
166166
argument(
167167
name = "expression",
168168
description = "Timestamp or time expression to operate on. Can be a constant, column, or function."
169-
)
169+
),
170+
sql_example = r#"```sql
171+
> SELECT date_trunc('month', '2024-05-15T10:30:00');
172+
+-----------------------------------------------+
173+
| date_trunc(Utf8("month"),Utf8("2024-05-15T10:30:00")) |
174+
+-----------------------------------------------+
175+
| 2024-05-01T00:00:00 |
176+
+-----------------------------------------------+
177+
> SELECT date_trunc('hour', '2024-05-15T10:30:00');
178+
+----------------------------------------------+
179+
| date_trunc(Utf8("hour"),Utf8("2024-05-15T10:30:00")) |
180+
+----------------------------------------------+
181+
| 2024-05-15T10:00:00 |
182+
+----------------------------------------------+
183+
```"#
170184
)]
171185
#[derive(Debug, PartialEq, Eq, Hash)]
172186
pub struct DateTruncFunc {

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

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,24 @@ Returns the current timestamp in the system configured timezone (None by default
3636
3737
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.
3838
"#,
39-
syntax_example = "now()"
39+
syntax_example = "now()",
40+
sql_example = r#"```sql
41+
> SELECT now();
42+
+----------------------------------+
43+
| now() |
44+
+----------------------------------+
45+
| 2024-12-23T06:30:00.123456789 |
46+
+----------------------------------+
47+
48+
-- The timezone of the returned timestamp depends on the session time zone
49+
> SET datafusion.execution.time_zone = 'America/New_York';
50+
> SELECT now();
51+
+--------------------------------------+
52+
| now() |
53+
+--------------------------------------+
54+
| 2024-12-23T01:30:00.123456789-05:00 |
55+
+--------------------------------------+
56+
```"#
4057
)]
4158
#[derive(Debug, PartialEq, Eq, Hash)]
4259
pub struct NowFunc {

‎docs/source/user-guide/sql/scalar_functions.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2415,6 +2415,26 @@ current_date()
24152415
SELECT current_date();
24162416
```
24172417

2418+
#### Example
2419+
2420+
```sql
2421+
> SELECT current_date();
2422+
+----------------+
2423+
| current_date() |
2424+
+----------------+
2425+
| 2024-12-23 |
2426+
+----------------+
2427+
2428+
-- The current date is based on the session time zone (UTC by default)
2429+
> SET datafusion.execution.time_zone = 'Asia/Tokyo';
2430+
> SELECT current_date();
2431+
+----------------+
2432+
| current_date() |
2433+
+----------------+
2434+
| 2024-12-24 |
2435+
+----------------+
2436+
```
2437+
24182438
#### Aliases
24192439

24202440
- today
@@ -2433,6 +2453,26 @@ current_time()
24332453
SELECT current_time();
24342454
```
24352455

2456+
#### Example
2457+
2458+
```sql
2459+
> SELECT current_time();
2460+
+--------------------+
2461+
| current_time() |
2462+
+--------------------+
2463+
| 06:30:00.123456789 |
2464+
+--------------------+
2465+
2466+
-- The current time is based on the session time zone (UTC by default)
2467+
> SET datafusion.execution.time_zone = 'Asia/Tokyo';
2468+
> SELECT current_time();
2469+
+--------------------+
2470+
| current_time() |
2471+
+--------------------+
2472+
| 15:30:00.123456789 |
2473+
+--------------------+
2474+
```
2475+
24362476
### `current_timestamp`
24372477

24382478
_Alias of [now](#now)._
@@ -2537,6 +2577,23 @@ date_part(part, expression)
25372577

25382578
- **expression**: Time expression to operate on. Can be a constant, column, or function.
25392579

2580+
#### Example
2581+
2582+
```sql
2583+
> SELECT date_part('year', '2024-05-01T00:00:00');
2584+
+-----------------------------------------------------+
2585+
| date_part(Utf8("year"),Utf8("2024-05-01T00:00:00")) |
2586+
+-----------------------------------------------------+
2587+
| 2024 |
2588+
+-----------------------------------------------------+
2589+
> SELECT extract(day FROM timestamp '2024-05-01T00:00:00');
2590+
+----------------------------------------------------+
2591+
| date_part(Utf8("DAY"),Utf8("2024-05-01T00:00:00")) |
2592+
+----------------------------------------------------+
2593+
| 1 |
2594+
+----------------------------------------------------+
2595+
```
2596+
25402597
#### Alternative Syntax
25412598

25422599
```sql
@@ -2582,6 +2639,23 @@ date_trunc(precision, expression)
25822639

25832640
- **expression**: Timestamp or time expression to operate on. Can be a constant, column, or function.
25842641

2642+
#### Example
2643+
2644+
```sql
2645+
> SELECT date_trunc('month', '2024-05-15T10:30:00');
2646+
+-----------------------------------------------+
2647+
| date_trunc(Utf8("month"),Utf8("2024-05-15T10:30:00")) |
2648+
+-----------------------------------------------+
2649+
| 2024-05-01T00:00:00 |
2650+
+-----------------------------------------------+
2651+
> SELECT date_trunc('hour', '2024-05-15T10:30:00');
2652+
+----------------------------------------------+
2653+
| date_trunc(Utf8("hour"),Utf8("2024-05-15T10:30:00")) |
2654+
+----------------------------------------------+
2655+
| 2024-05-15T10:00:00 |
2656+
+----------------------------------------------+
2657+
```
2658+
25852659
#### Aliases
25862660

25872661
- datetrunc
@@ -2694,6 +2768,26 @@ The `now()` return value is determined at query time and will return the same ti
26942768
now()
26952769
```
26962770

2771+
#### Example
2772+
2773+
```sql
2774+
> SELECT now();
2775+
+----------------------------------+
2776+
| now() |
2777+
+----------------------------------+
2778+
| 2024-12-23T06:30:00.123456789 |
2779+
+----------------------------------+
2780+
2781+
-- The timezone of the returned timestamp depends on the session time zone
2782+
> SET datafusion.execution.time_zone = 'America/New_York';
2783+
> SELECT now();
2784+
+--------------------------------------+
2785+
| now() |
2786+
+--------------------------------------+
2787+
| 2024-12-23T01:30:00.123456789-05:00 |
2788+
+--------------------------------------+
2789+
```
2790+
26972791
#### Aliases
26982792

26992793
- current_timestamp

0 commit comments

Comments
 (0)