updates (#1844)

Author: soyeric128

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

@@ -3,44 +3,56 @@ title: DATE_DIFF
 ---
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced or updated: v1.2.645"/>
+<FunctionDescription description="Introduced or updated: v1.2.723"/>
 
 Calculates the difference between two dates or timestamps based on a specified time unit. The result is positive if the `<end_date>` is after the `<start_date>`, and negative if it's before.
 
 ## Syntax
 
 ```sql
-DATE_DIFF(<unit>, <start_date>, <end_date>)
+DATE_DIFF(
+  YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | SECOND |
+  DOW | DOY | EPOCH | ISODOW | YEARWEEK | MILLENNIUM,
+  <start_date_or_timestamp>,
+  <end_date_or_timestamp>
+)
 ```
 
-| Parameter      | Description                                                                                                 |
-|----------------|-------------------------------------------------------------------------------------------------------------|
-| `<unit>`       | The time unit for the difference: `YEAR`, `QUARTER`, `MONTH`, `WEEK`, `DAY`, `HOUR`, `MINUTE`, or `SECOND`. |
-| `<start_date>` | The starting date or timestamp.                                                                             |
-| `<end_date>`   | The ending date or timestamp.                                                                               |
+| Keyword      | Description                                                             |
+|--------------|-------------------------------------------------------------------------|
+| `DOW`        | Day of the Week. Sunday (0) through Saturday (6).                       |
+| `DOY`        | Day of the Year. 1 through 366.                                         |
+| `EPOCH`      | The number of seconds since 1970-01-01 00:00:00.                        |
+| `ISODOW`     | ISO Day of the Week. Monday (1) through Sunday (7).                     |
+| `YEARWEEK`   | The year and week number combined, following ISO 8601 (e.g., 202415).   |
+| `MILLENNIUM` | The millennium of the date (1 for years 1–1000, 2 for 1001–2000, etc.). |
 
 ## Examples
 
-This example calculates the difference in hours between **yesterday** and **today**:
+This example calculates the difference between a fixed timestamp (`2020-01-01 00:00:00`) and the current timestamp (`NOW()`), across various units such as year, ISO weekday, year-week, and millennium:
 
 ```sql
-SELECT DATE_DIFF(HOUR, YESTERDAY(), TODAY());
-
-┌───────────────────────────────────────┐
-│ DATE_DIFF(HOUR, yesterday(), today()) │
-├───────────────────────────────────────┤
-│                                    24 │
-└───────────────────────────────────────┘
+SELECT
+  DATE_DIFF(YEAR,        TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_year,
+  DATE_DIFF(QUARTER,     TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_quarter,
+  DATE_DIFF(MONTH,       TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_month,
+  DATE_DIFF(WEEK,        TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_week,
+  DATE_DIFF(DAY,         TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_day,
+  DATE_DIFF(HOUR,        TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_hour,
+  DATE_DIFF(MINUTE,      TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_minute,
+  DATE_DIFF(SECOND,      TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_second,
+  DATE_DIFF(DOW,         TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_dow,
+  DATE_DIFF(DOY,         TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_doy,
+  DATE_DIFF(EPOCH,       TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_epoch,
+  DATE_DIFF(ISODOW,      TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_isodow,
+  DATE_DIFF(YEARWEEK,    TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_yearweek,
+  DATE_DIFF(MILLENNIUM,  TIMESTAMP '2020-01-01 00:00:00', NOW())        AS diff_millennium;
 ```
 
-This example calculates the difference in years between the current date and January 1, 2000;
-
 ```sql
-SELECT NOW(), DATE_DIFF(YEAR, NOW(), TO_DATE('2000-01-01'));
-
-┌────────────────────────────────────────────────────────────────────────────┐
-│            now()           │ DATE_DIFF(YEAR, now(), to_date('2000-01-01')) │
-├────────────────────────────┼───────────────────────────────────────────────┤
-│ 2024-10-15 03:38:23.726599 │                                           -24 │
-└────────────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ diff_year │ diff_quarter │ diff_month │ diff_week │ diff_day │ diff_hour │ diff_minute │ diff_second │ diff_dow │ diff_doy │ diff_epoch │ diff_isodow │ diff_yearweek │ diff_millennium │
+├───────────┼──────────────┼────────────┼───────────┼──────────┼───────────┼─────────────┼─────────────┼──────────┼──────────┼────────────┼─────────────┼───────────────┼─────────────────┤
+│         5 │           21 │         63 │       276 │     1932 │     46386 │     2783184 │   166991069 │     1932 │     1932 │  166991069 │        1932 │           515 │               0 │
+└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```

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

@@ -4,66 +4,61 @@ title: DATE_PART
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced or updated: v1.2.153"/>
+<FunctionDescription description="Introduced or updated: v1.2.723"/>
 
-Retrieves the designated portion of a date, time, or timestamp.
+Retrieves the designated portion of a date or timestamp.
 
 See also: [EXTRACT](extract.md)
 
 ## Syntax
 
 ```sql
-DATE_PART( YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | SECOND | DOW | DOY, <date_or_time_expr> )
+DATE_PART(
+  YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | SECOND |
+  DOW | DOY | EPOCH | ISODOW | YEARWEEK | MILLENNIUM,
+  <date_or_timestamp_expr>
+)
 ```
 
-- DOW: Day of Week.
-- DOY: Day of Year.
+| Keyword      | Description                                                             |
+|--------------|-------------------------------------------------------------------------|
+| `DOW`        | Day of the Week. Sunday (0) through Saturday (6).                       |
+| `DOY`        | Day of the Year. 1 through 366.                                         |
+| `EPOCH`      | The number of seconds since 1970-01-01 00:00:00.                        |
+| `ISODOW`     | ISO Day of the Week. Monday (1) through Sunday (7).                     |
+| `YEARWEEK`   | The year and week number combined, following ISO 8601 (e.g., 202415).   |
+| `MILLENNIUM` | The millennium of the date (1 for years 1–1000, 2 for 1001–2000, etc.). |
 
 ## Return Type
 
 Integer.
 
 ## Examples
 
-```sql
-SELECT NOW();
-
-┌────────────────────────────┐
-│            now()           │
-├────────────────────────────┤
-│ 2024-05-22 02:55:52.954761 │
-└────────────────────────────┘
-
-SELECT DATE_PART(DAY, NOW());
-
-┌───────────────────────┐
-│ date_part(day, now()) │
-├───────────────────────┤
-│                    22 │
-└───────────────────────┘
-
-SELECT DATE_PART(DOW, NOW());
-
-┌───────────────────────┐
-│ date_part(dow, now()) │
-├───────────────────────┤
-│                     3 │
-└───────────────────────┘
+This example demonstrates how to use DATE_PART to extract various components—such as year, month, ISO week day, year-week combination, and millennium—from the current timestamp:
 
-SELECT DATE_PART(DOY, NOW());
-
-┌───────────────────────┐
-│ date_part(doy, now()) │
-├───────────────────────┤
-│                   143 │
-└───────────────────────┘
-
-SELECT DATE_PART(MONTH, TO_DATE('2024-05-21'));
+```sql
+SELECT
+  DATE_PART(YEAR, NOW())        AS year_part,
+  DATE_PART(QUARTER, NOW())     AS quarter_part,
+  DATE_PART(MONTH, NOW())       AS month_part,
+  DATE_PART(WEEK, NOW())        AS week_part,
+  DATE_PART(DAY, NOW())         AS day_part,
+  DATE_PART(HOUR, NOW())        AS hour_part,
+  DATE_PART(MINUTE, NOW())      AS minute_part,
+  DATE_PART(SECOND, NOW())      AS second_part,
+  DATE_PART(DOW, NOW())         AS dow_part,
+  DATE_PART(DOY, NOW())         AS doy_part,
+  DATE_PART(EPOCH, NOW())       AS epoch_part,
+  DATE_PART(ISODOW, NOW())      AS isodow_part,
+  DATE_PART(YEARWEEK, NOW())    AS yearweek_part,
+  DATE_PART(MILLENNIUM, NOW())  AS millennium_part;
+```
 
-┌─────────────────────────────────────────┐
-│ date_part(month, to_date('2024-05-21')) │
-│                  UInt8                  │
-├─────────────────────────────────────────┤
-│                                       5 │
-└─────────────────────────────────────────┘
+```sql
+┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ year_part │ quarter_part │ month_part │ week_part │ day_part │ hour_part │ minute_part │ second_part │ dow_part │ doy_part │     epoch_part    │ isodow_part │ yearweek_part │ millennium_part │
+├───────────┼──────────────┼────────────┼───────────┼──────────┼───────────┼─────────────┼─────────────┼──────────┼──────────┼───────────────────┼─────────────┼───────────────┼─────────────────┤
+│      2025 │            2 │          4 │        16 │       16 │        18 │          10 │          10 │        3 │      106 │ 1744827010.257671 │           3 │        202516 │               3 │
+└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```

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

@@ -4,7 +4,7 @@ title: EXTRACT
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced or updated: v1.2.697"/>
+<FunctionDescription description="Introduced or updated: v1.2.723"/>
 
 Retrieves the designated portion of a date, timestamp, or interval.
 
@@ -14,15 +14,24 @@ See also: [DATE_PART](date-part.md)
 
 ```sql
 -- Extract from a date or timestamp
-EXTRACT( YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | SECOND | DOW | DOY | EPOCH FROM <date_or_timestamp> )
+EXTRACT(
+  YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | SECOND |
+  DOW | DOY | EPOCH | ISODOW | YEARWEEK | MILLENNIUM
+  FROM <date_or_timestamp>
+)
 
 -- Extract from an interval
 EXTRACT( YEAR | MONTH | WEEK | DAY | HOUR | MINUTE | SECOND | MICROSECOND ｜ EPOCH FROM <interval> )
 ```
 
-- `DOW`: Day of the Week.
-- `DOY`: Day of the Year.
-- `EPOCH`: The number of seconds since 1970-01-01 00:00:00.
+| Keyword      | Description                                                             |
+|--------------|-------------------------------------------------------------------------|
+| `DOW`        | Day of the Week. Sunday (0) through Saturday (6).                       |
+| `DOY`        | Day of the Year. 1 through 366.                                         |
+| `EPOCH`      | The number of seconds since 1970-01-01 00:00:00.                        |
+| `ISODOW`     | ISO Day of the Week. Monday (1) through Sunday (7).                     |
+| `YEARWEEK`   | The year and week number combined, following ISO 8601 (e.g., 202415).   |
+| `MILLENNIUM` | The millennium of the date (1 for years 1–1000, 2 for 1001–2000, etc.). |
 
 ## Return Type
 
@@ -46,13 +55,20 @@ The return type depends on the field being extracted:
 This example extracts various fields from the current timestamp:
 
 ```sql
-SELECT NOW(), EXTRACT(DAY FROM NOW()), EXTRACT(DOY FROM NOW()), EXTRACT(EPOCH FROM NOW());
-
-┌────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│            now()           │ EXTRACT(DAY FROM now()) │ EXTRACT(DOY FROM now()) │ EXTRACT(EPOCH FROM now()) │
-├────────────────────────────┼─────────────────────────┼─────────────────────────┼───────────────────────────┤
-│ 2025-02-08 03:51:51.991167 │                       8 │                      39 │         1738986711.991167 │
-└────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+SELECT 
+  NOW(), 
+  EXTRACT(DAY FROM NOW()), 
+  EXTRACT(DOY FROM NOW()), 
+  EXTRACT(EPOCH FROM NOW()), 
+  EXTRACT(ISODOW FROM NOW()), 
+  EXTRACT(YEARWEEK FROM NOW()), 
+  EXTRACT(MILLENNIUM FROM NOW());
+
+┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│            now()           │ EXTRACT(DAY FROM now()) │ EXTRACT(DOY FROM now()) │ EXTRACT(EPOCH FROM now()) │ EXTRACT(ISODOW FROM now()) │ EXTRACT(YEARWEEK FROM now()) │ EXTRACT(MILLENNIUM FROM now()) │
+├────────────────────────────┼─────────────────────────┼─────────────────────────┼───────────────────────────┼────────────────────────────┼──────────────────────────────┼────────────────────────────────┤
+│ 2025-04-16 18:04:22.773888 │                      16 │                     106 │         1744826662.773888 │                          3 │                       202516 │                              3 │
+└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
 This example extracts the number of days from an interval:

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

@@ -46,6 +46,8 @@ This section provides reference information for the datetime-related functions i
 - [TO_YYYYMMDD](to-yyyymmdd)
 - [TO_YYYYMMDDHH](to-yyyymmddhh)
 - [TO_YYYYMMDDHHMMSS](to-yyyymmddhhmmss)
+- [MILLENNIUM](millennium.md)
+- [YEARWEEK](yearweek.md)
 
 ## Date Arithmetic Functions