Skip to content

Commit 27832b9

Browse files
buraksennburaksenn
committed
chore: added sql example to datetime docs
1 parent 6ef4cef commit 27832b9

6 files changed

Lines changed: 178 additions & 5 deletions

File tree

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

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

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

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

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

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

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

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

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

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,24 @@ Returns the current timestamp in the system configured timezone (None by default
3737
3838
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.
3939
"#,
40-
syntax_example = "now()"
40+
syntax_example = "now()",
41+
sql_example = r#"```sql
42+
> SELECT now();
43+
+----------------------------------+
44+
| now() |
45+
+----------------------------------+
46+
| 2024-12-23T06:30:00.123456789Z |
47+
+----------------------------------+
48+
49+
-- The timezone of the returned timestamp depends on the session time zone
50+
> SET datafusion.execution.time_zone = 'America/New_York';
51+
> SELECT now();
52+
+----------------------------------+
53+
| now() |
54+
+----------------------------------+
55+
| 2024-12-23T01:30:00.123456789Z |
56+
+----------------------------------+
57+
```"#
4158
)]
4259
#[derive(Debug, PartialEq, Eq, Hash)]
4360
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 = 'Europe/London';
2468+
> SELECT current_time();
2469+
+--------------------+
2470+
| current_time() |
2471+
+--------------------+
2472+
| 07: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.0 |
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.0 |
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.123456789Z |
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.123456789Z |
2788+
+----------------------------------+
2789+
```
2790+
26972791
#### Aliases
26982792

26992793
- current_timestamp

0 commit comments

Comments
 (0)