Skip to content

Commit 4bb4b31

Browse files
TCeasonTCeason
authored
chore: add doc about time_slice (#2709)
1 parent 59c4bba commit 4bb4b31

File tree

3 files changed

+155
-47
lines changed

3 files changed

+155
-47
lines changed

‎docs/en/sql-reference/20-sql-functions/05-datetime-functions/date-trunc.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,3 +68,4 @@ SELECT
6868
## See Also
6969

7070
- [TRUNC](trunc.md): Provides similar functionality with a different syntax for better SQL standard compatibility.
71+
- [TIME_SLICE](time-slice.md): Map a single date/timestamp value to a calendar-aligned interval.

‎docs/en/sql-reference/20-sql-functions/05-datetime-functions/index.md‎

Lines changed: 48 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -6,42 +6,42 @@ This page provides a comprehensive overview of Date & Time functions in Databend
66

77
## Current Date & Time Functions
88

9-
| Function | Description | Example |
10-
|----------|-------------|---------|
11-
| [NOW](now.md) | Returns the current date and time | `NOW()` → `2024-06-04 17:42:31.123456` |
9+
| Function | Description | Example |
10+
|-------------------------------------------|-----------------------------------|------------------------------------------------------|
11+
| [NOW](now.md) | Returns the current date and time | `NOW()` → `2024-06-04 17:42:31.123456` |
1212
| [CURRENT_TIMESTAMP](current-timestamp.md) | Returns the current date and time | `CURRENT_TIMESTAMP()` → `2024-06-04 17:42:31.123456` |
13-
| [TODAY](today.md) | Returns the current date | `TODAY()` → `2024-06-04` |
14-
| [TOMORROW](tomorrow.md) | Returns tomorrow's date | `TOMORROW()` → `2024-06-05` |
15-
| [YESTERDAY](yesterday.md) | Returns yesterday's date | `YESTERDAY()` → `2024-06-03` |
13+
| [TODAY](today.md) | Returns the current date | `TODAY()` → `2024-06-04` |
14+
| [TOMORROW](tomorrow.md) | Returns tomorrow's date | `TOMORROW()` → `2024-06-05` |
15+
| [YESTERDAY](yesterday.md) | Returns yesterday's date | `YESTERDAY()` → `2024-06-03` |
1616

1717
## Date & Time Extraction Functions
1818

19-
| Function | Description | Example |
20-
|----------|-------------|---------|
21-
| [YEAR](year.md) | Extracts the year from a date | `YEAR('2024-06-04')` → `2024` |
22-
| [MONTH](month.md) | Extracts the month from a date | `MONTH('2024-06-04')` → `6` |
23-
| [DAY](day.md) | Extracts the day from a date | `DAY('2024-06-04')` → `4` |
24-
| [QUARTER](quarter.md) | Extracts the quarter from a date | `QUARTER('2024-06-04')` → `2` |
25-
| [WEEK](week.md) / [WEEKOFYEAR](weekofyear.md) | Extracts the week number from a date | `WEEK('2024-06-04')` → `23` |
26-
| [EXTRACT](extract.md) | Extracts a part from a date | `EXTRACT(MONTH FROM '2024-06-04')` → `6` |
27-
| [DATE_PART](date-part.md) | Extracts a part from a date | `DATE_PART('month', '2024-06-04')` → `6` |
28-
| [YEARWEEK](yearweek.md) | Returns year and week number | `YEARWEEK('2024-06-04')` → `202423` |
29-
| [MILLENNIUM](millennium.md) | Returns the millennium from a date | `MILLENNIUM('2024-06-04')` → `3` |
19+
| Function | Description | Example |
20+
|-----------------------------------------------|--------------------------------------|------------------------------------------|
21+
| [YEAR](year.md) | Extracts the year from a date | `YEAR('2024-06-04')` → `2024` |
22+
| [MONTH](month.md) | Extracts the month from a date | `MONTH('2024-06-04')` → `6` |
23+
| [DAY](day.md) | Extracts the day from a date | `DAY('2024-06-04')` → `4` |
24+
| [QUARTER](quarter.md) | Extracts the quarter from a date | `QUARTER('2024-06-04')` → `2` |
25+
| [WEEK](week.md) / [WEEKOFYEAR](weekofyear.md) | Extracts the week number from a date | `WEEK('2024-06-04')` → `23` |
26+
| [EXTRACT](extract.md) | Extracts a part from a date | `EXTRACT(MONTH FROM '2024-06-04')` → `6` |
27+
| [DATE_PART](date-part.md) | Extracts a part from a date | `DATE_PART('month', '2024-06-04')` → `6` |
28+
| [YEARWEEK](yearweek.md) | Returns year and week number | `YEARWEEK('2024-06-04')` → `202423` |
29+
| [MILLENNIUM](millennium.md) | Returns the millennium from a date | `MILLENNIUM('2024-06-04')` → `3` |
3030

3131
## Date & Time Conversion Functions
3232

33-
| Function | Description | Example |
34-
|----------|-------------|---------|
35-
| [DATE](date.md) | Converts a value to DATE type | `DATE('2024-06-04')` → `2024-06-04` |
36-
| [TO_DATE](to-date.md) | Converts a string to DATE type | `TO_DATE('2024-06-04')` → `2024-06-04` |
37-
| [TO_DATETIME](to-datetime.md) | Converts a string to DATETIME type | `TO_DATETIME('2024-06-04 12:30:45')` → `2024-06-04 12:30:45` |
38-
| [TO_TIMESTAMP](to-timestamp.md) | Converts a string to TIMESTAMP type | `TO_TIMESTAMP('2024-06-04 12:30:45')` → `2024-06-04 12:30:45` |
39-
| [TO_UNIX_TIMESTAMP](to-unix-timestamp.md) | Converts a date to Unix timestamp | `TO_UNIX_TIMESTAMP('2024-06-04')` → `1717516800` |
40-
| [TO_YYYYMM](to-yyyymm.md) | Formats date as YYYYMM | `TO_YYYYMM('2024-06-04')` → `202406` |
41-
| [TO_YYYYMMDD](to-yyyymmdd.md) | Formats date as YYYYMMDD | `TO_YYYYMMDD('2024-06-04')` → `20240604` |
42-
| [TO_YYYYMMDDHH](to-yyyymmddhh.md) | Formats date as YYYYMMDDHH | `TO_YYYYMMDDHH('2024-06-04 12:30:45')` → `2024060412` |
43-
| [TO_YYYYMMDDHHMMSS](to-yyyymmddhhmmss.md) | Formats date as YYYYMMDDHHMMSS | `TO_YYYYMMDDHHMMSS('2024-06-04 12:30:45')` → `20240604123045` |
44-
| [DATE_FORMAT](date-format.md) | Formats a date according to a format string | `DATE_FORMAT('2024-06-04', '%Y-%m-%d')` → `'2024-06-04'` |
33+
| Function | Description | Example |
34+
|-------------------------------------------|---------------------------------------------|---------------------------------------------------------------|
35+
| [DATE](date.md) | Converts a value to DATE type | `DATE('2024-06-04')` → `2024-06-04` |
36+
| [TO_DATE](to-date.md) | Converts a string to DATE type | `TO_DATE('2024-06-04')` → `2024-06-04` |
37+
| [TO_DATETIME](to-datetime.md) | Converts a string to DATETIME type | `TO_DATETIME('2024-06-04 12:30:45')` → `2024-06-04 12:30:45` |
38+
| [TO_TIMESTAMP](to-timestamp.md) | Converts a string to TIMESTAMP type | `TO_TIMESTAMP('2024-06-04 12:30:45')` → `2024-06-04 12:30:45` |
39+
| [TO_UNIX_TIMESTAMP](to-unix-timestamp.md) | Converts a date to Unix timestamp | `TO_UNIX_TIMESTAMP('2024-06-04')` → `1717516800` |
40+
| [TO_YYYYMM](to-yyyymm.md) | Formats date as YYYYMM | `TO_YYYYMM('2024-06-04')` → `202406` |
41+
| [TO_YYYYMMDD](to-yyyymmdd.md) | Formats date as YYYYMMDD | `TO_YYYYMMDD('2024-06-04')` → `20240604` |
42+
| [TO_YYYYMMDDHH](to-yyyymmddhh.md) | Formats date as YYYYMMDDHH | `TO_YYYYMMDDHH('2024-06-04 12:30:45')` → `2024060412` |
43+
| [TO_YYYYMMDDHHMMSS](to-yyyymmddhhmmss.md) | Formats date as YYYYMMDDHHMMSS | `TO_YYYYMMDDHHMMSS('2024-06-04 12:30:45')` → `20240604123045` |
44+
| [DATE_FORMAT](date-format.md) | Formats a date according to a format string | `DATE_FORMAT('2024-06-04', '%Y-%m-%d')` → `'2024-06-04'` |
4545

4646
## Date & Time Arithmetic Functions
4747

@@ -60,28 +60,29 @@ This page provides a comprehensive overview of Date & Time functions in Databend
6060

6161
## Date & Time Truncation Functions
6262

63-
| Function | Description | Example |
64-
|----------|-------------|---------|
65-
| [DATE_TRUNC](date-trunc.md) | Truncates a timestamp to a specified precision | `DATE_TRUNC('month', '2024-06-04')` → `2024-06-01` |
66-
| [TO_START_OF_DAY](to-start-of-day.md) | Returns the start of the day | `TO_START_OF_DAY('2024-06-04 12:30:45')` → `2024-06-04 00:00:00` |
67-
| [TO_START_OF_HOUR](to-start-of-hour.md) | Returns the start of the hour | `TO_START_OF_HOUR('2024-06-04 12:30:45')` → `2024-06-04 12:00:00` |
68-
| [TO_START_OF_MINUTE](to-start-of-minute.md) | Returns the start of the minute | `TO_START_OF_MINUTE('2024-06-04 12:30:45')` → `2024-06-04 12:30:00` |
69-
| [TO_START_OF_MONTH](to-start-of-month.md) | Returns the start of the month | `TO_START_OF_MONTH('2024-06-04')` → `2024-06-01` |
70-
| [TO_START_OF_QUARTER](to-start-of-quarter.md) | Returns the start of the quarter | `TO_START_OF_QUARTER('2024-06-04')` → `2024-04-01` |
71-
| [TO_START_OF_YEAR](to-start-of-year.md) | Returns the start of the year | `TO_START_OF_YEAR('2024-06-04')` → `2024-01-01` |
72-
| [TO_START_OF_WEEK](to-start-of-week.md) | Returns the start of the week | `TO_START_OF_WEEK('2024-06-04')` → `2024-06-03` |
63+
| Function | Description | Example |
64+
|-----------------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------------|
65+
| [DATE_TRUNC](date-trunc.md) | Truncates a timestamp to a specified precision | `DATE_TRUNC('month', '2024-06-04')` → `2024-06-01` |
66+
| [TIME_SLICE](time-slice.md) | Map a single date/timestamp value to a calendar-aligned interval | `TIME_SLICE('2024-06-04', 4, 'MONTH', 'START')` → `2024-05-01` |
67+
| [TO_START_OF_DAY](to-start-of-day.md) | Returns the start of the day | `TO_START_OF_DAY('2024-06-04 12:30:45')` → `2024-06-04 00:00:00` |
68+
| [TO_START_OF_HOUR](to-start-of-hour.md) | Returns the start of the hour | `TO_START_OF_HOUR('2024-06-04 12:30:45')` → `2024-06-04 12:00:00` |
69+
| [TO_START_OF_MINUTE](to-start-of-minute.md) | Returns the start of the minute | `TO_START_OF_MINUTE('2024-06-04 12:30:45')` → `2024-06-04 12:30:00` |
70+
| [TO_START_OF_MONTH](to-start-of-month.md) | Returns the start of the month | `TO_START_OF_MONTH('2024-06-04')` → `2024-06-01` |
71+
| [TO_START_OF_QUARTER](to-start-of-quarter.md) | Returns the start of the quarter | `TO_START_OF_QUARTER('2024-06-04')` → `2024-04-01` |
72+
| [TO_START_OF_YEAR](to-start-of-year.md) | Returns the start of the year | `TO_START_OF_YEAR('2024-06-04')` → `2024-01-01` |
73+
| [TO_START_OF_WEEK](to-start-of-week.md) | Returns the start of the week | `TO_START_OF_WEEK('2024-06-04')` → `2024-06-03` |
7374

7475
## Date & Time Navigation Functions
7576

76-
| Function | Description | Example |
77-
|----------|-------------|---------|
78-
| [LAST_DAY](last-day.md) | Returns the last day of the month | `LAST_DAY('2024-06-04')` → `2024-06-30` |
79-
| [NEXT_DAY](next-day.md) | Returns the date of the next specified day of week | `NEXT_DAY('2024-06-04', 'SUNDAY')` → `2024-06-09` |
77+
| Function | Description | Example |
78+
|---------------------------------|--------------------------------------------------------|-------------------------------------------------------|
79+
| [LAST_DAY](last-day.md) | Returns the last day of the month | `LAST_DAY('2024-06-04')` → `2024-06-30` |
80+
| [NEXT_DAY](next-day.md) | Returns the date of the next specified day of week | `NEXT_DAY('2024-06-04', 'SUNDAY')` → `2024-06-09` |
8081
| [PREVIOUS_DAY](previous-day.md) | Returns the date of the previous specified day of week | `PREVIOUS_DAY('2024-06-04', 'MONDAY')` → `2024-06-03` |
8182

8283
## Other Date & Time Functions
8384

84-
| Function | Description | Example |
85-
|----------|-------------|---------|
86-
| [TIMEZONE](timezone.md) | Returns the current timezone | `TIMEZONE()` → `'UTC'` |
87-
| [TIME_SLOT](time-slot.md) | Returns time slots | `TIME_SLOT('2024-06-04 12:30:45', 15, 'MINUTE')` → `2024-06-04 12:30:00` |
85+
| Function | Description | Example |
86+
|---------------------------|------------------------------|--------------------------------------------------------------------------|
87+
| [TIMEZONE](timezone.md) | Returns the current timezone | `TIMEZONE()` → `'UTC'` |
88+
| [TIME_SLOT](time-slot.md) | Returns time slots | `TIME_SLOT('2024-06-04 12:30:45', 15, 'MINUTE')` → `2024-06-04 12:30:00` |

‎docs/en/sql-reference/20-sql-functions/05-datetime-functions/time-slice.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: TIME_SLICE
3+
---
4+
import FunctionDescription from '@site/src/components/FunctionDescription';
5+
6+
<FunctionDescription description="Introduced or updated: v1.2.799"/>
7+
8+
TIME_SLICE is a scalar function used to map a single date/timestamp value to a fixed calendar interval (slice or bucket).
9+
10+
It returns the boundary (starting or ending point) of the calendar interval containing the time point, and is often used to group, aggregate and report time series data by custom calendar periods, such as summarizing by a 2-week, 3-month or 15-minute window.
11+
12+
## Syntax
13+
14+
```sql
15+
TIME_SLICE(<date_or_time_expr>, <slice_length>, <IntervalKind> [, <start_or_end>])
16+
```
17+
18+
| Parameter | Description |
19+
|-----------------------|-------------------------------------------------------------------------------------------------------------|
20+
| `<date_or_time_expr>` | DATE, TIME, TIMESTAMP or other date/time expression. The return type matches the input type where possible. |
21+
| `<slice_length>` | INTEGER >= 1. The number of contiguous IntervalKind units in a slice (e.g., 2 for 2-week slices). |
22+
| `<IntervalKind>` | One of the following (case-insensitive): YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND. |
23+
| `<start_or_end>` | String 'START' or 'END' (case-insensitive). If omitted, defaults to 'START'. |
24+
25+
26+
## Semantics
27+
28+
- For a given call TIME_SLICE(value, slice_length, IntervalKind, start_or_end):
29+
- START returns the exact calendar boundary that begins the slice (inclusive).
30+
- END returns the boundary immediately after the slice (an exclusive upper bound). Depending on the input type and system precision, END can also be interpreted as the last representable instant of the slice if you convert it to an inclusive endpoint by subtracting the smallest time unit.
31+
32+
- Supported IntervalKind vs input type:
33+
- DATE inputs: YEAR, QUARTER, MONTH, WEEK, DAY.
34+
- TIMESTAMP / TIMESTAMPTZ inputs: YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND (all IntervalKind values).
35+
36+
- Alignment rules (calendar boundaries):
37+
- Years start on January 1.
38+
- Quarters start on quarter boundaries (Jan 1, Apr 1, Jul 1, Oct 1).
39+
- Months start on the 1st of the month.
40+
- Weeks are aligned to the implementation’s week convention (Default uses Monday as the week start).
41+
- Days start at 00:00:00.
42+
- Hour/Minute/Second slices begin at the natural boundary for those units.
43+
44+
45+
## Return Type
46+
47+
- DATE input → returns DATE.
48+
- TIMESTAMP input → returns TIMESTAMP.
49+
50+
51+
## Examples
52+
53+
```sql
54+
SELECT
55+
'2019-02-28'::DATE AS "DATE",
56+
TIME_SLICE("DATE", 4, 'MONTH', 'START') AS "start",
57+
TIME_SLICE("DATE", 4, 'MONTH', 'END') AS "end";
58+
59+
╭──────────────────────────────────────╮
60+
│ DATE │ start │ end │
61+
├────────────┼────────────┼────────────┤
62+
│ 2019-02-28 │ 2019-01-01 │ 2019-05-01 │
63+
╰──────────────────────────────────────╯
64+
65+
```
66+
67+
```sql
68+
CREATE OR REPLACE TABLE accounts (
69+
id INT,
70+
billing_date DATE,
71+
balance_due DECIMAL(11, 2)
72+
)
73+
74+
INSERT INTO
75+
accounts (id, billing_date, balance_due)
76+
VALUES
77+
(1, '2018-07-31', 100.00),
78+
(2, '2018-08-01', 200.00),
79+
(3, '2018-08-25', 400.00);
80+
81+
-- Group by 2-week slices:
82+
SELECT
83+
TIME_SLICE(billing_date, 2, 'WEEK', 'START') AS slice_start,
84+
TIME_SLICE(billing_date, 2, 'WEEK', 'END') AS slice_end,
85+
COUNT(*) AS num_late_bills,
86+
SUM(balance_due) AS total_due
87+
FROM
88+
accounts
89+
WHERE
90+
balance_due > 0
91+
GROUP BY 1, 2
92+
ORDER BY
93+
total_due;
94+
95+
╭─────────────────────────────────────────────────────────────────────────────╮
96+
│ slice_start │ slice_end │ num_late_bills │ total_due │
97+
├────────────────┼────────────────┼────────────────┼──────────────────────────┤
98+
│ 2018-07-23 │ 2018-08-06 │ 2 │ 300.00 │
99+
│ 2018-08-20 │ 2018-09-03 │ 1 │ 400.00 │
100+
╰─────────────────────────────────────────────────────────────────────────────╯
101+
102+
```
103+
104+
## See Also
105+
106+
- [DATE_TRUNC](date-trunc.md): Provides similar functionality with a different syntax for better SQL standard compatibility.

0 commit comments

Comments
 (0)