This is an automated email from the ASF dual-hosted git repository.
zclll pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 19f7f86826f [fix](doc) Fix date function day to from (#2804)
19f7f86826f is described below
commit 19f7f86826f968b4e91ebdedd0b0c4ad61b64b1c
Author: dwdwqfwe <[email protected]>
AuthorDate: Thu Sep 25 18:37:58 2025 +0800
[fix](doc) Fix date function day to from (#2804)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../date-time-functions/day-ceil.md | 129 ++++++++++++++++++---
.../date-time-functions/day-floor.md | 111 +++++++++++++++---
.../scalar-functions/date-time-functions/day.md | 36 +++++-
.../date-time-functions/dayname.md | 36 +++++-
.../date-time-functions/dayofweek.md | 49 +++++---
.../date-time-functions/dayofyear.md | 44 ++++++-
.../date-time-functions/extract.md | 91 ++++++++++++---
.../date-time-functions/from-days.md | 35 ++++--
.../date-time-functions/from-iso8601-date.md | 82 +++++++++++--
.../date-time-functions/from-microsecond.md | 59 ++++++++--
.../date-time-functions/from-millisecond.md | 61 ++++++++--
.../date-time-functions/from-second.md | 48 ++++++--
.../date-time-functions/from-unixtime.md | 64 +++++++---
.../date-time-functions/day-ceil.md | 122 ++++++++++++++++---
.../date-time-functions/day-floor.md | 105 ++++++++++++++---
.../scalar-functions/date-time-functions/day.md | 37 +++++-
.../date-time-functions/dayname.md | 36 +++++-
.../date-time-functions/dayofweek.md | 51 +++++---
.../date-time-functions/dayofyear.md | 44 ++++++-
.../date-time-functions/extract.md | 91 ++++++++++++---
.../date-time-functions/from-days.md | 35 ++++--
.../date-time-functions/from-iso8601-date.md | 83 +++++++++++--
.../date-time-functions/from-microsecond.md | 51 ++++++--
.../date-time-functions/from-millisecond.md | 50 ++++++--
.../date-time-functions/from-second.md | 39 +++++--
.../date-time-functions/from-unixtime.md | 65 ++++++++---
26 files changed, 1371 insertions(+), 283 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
index 61deac7b1b9..ad060f3e466 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
@@ -1,45 +1,142 @@
---
{
- "title": "DAY_CEIL",
- "language": "en"
+ "title": "DAY_CEIL",
+ "language": "en"
}
---
## Description
-Rounds the date up to the nearest specified time interval period.
+The DAY_CEIL function is used to round up a specified date or time value to
the start of the nearest specified day period. It returns the smallest period
moment that is not less than the input date and time. The period rule is
defined jointly by period (number of days in the period) and origin (starting
reference time). If no starting reference time is specified, it defaults to
0001-01-01 00:00:00 as the calculation basis.
+
+Date calculation formula:
+
+$$
+\text{DAY\_CEIL}(\langle\text{date\_or\_time\_expr}\rangle,
\langle\text{period}\rangle, \langle\text{origin}\rangle) =
\min\{\langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times
\text{day} \mid k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times
\langle\text{period}\rangle \times \text{day} \geq
\langle\text{date\_or\_time\_expr}\rangle\}
+$$
+
+where K represents the number of periods required to reach the target time
from the reference time.
## Syntax
```sql
-DAY_CEIL(<datetime>)
-DAY_CEIL(<datetime>, <origin>)
-DAY_CEIL(<datetime>, <period>)
-DAY_CEIL(<datetime>, <period>, <origin>)
+DAY_CEIL(<date_or_time_expr>)
+DAY_CEIL(<date_or_time_expr>, <origin>)
+DAY_CEIL(<date_or_time_expr>, <period>)
+DAY_CEIL(<date_or_time_expr>, <period>, <origin>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<datetime>` | A valid date expression |
-| `<period>` | Specifies how many days make up each period |
-| `<origin>` | The starting point of time. If not provided, the default is
0001-01-01T00:00:00 |
+| `<date_or_time_expr>` | A valid date expression that supports date/datetime
types. For specific datetime and date formats, please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
+| `<period>` | Specifies the number of days in each period, of type INT. If
not specified, the default period is 1 day. |
+| `<origin>` | The starting reference time for period calculation, supports
date/datetime types |
## Return Value
-Returns the date of the nearest rounded-up timestamp.
+Returns a date or time value representing the result of rounding up the input
value to the specified day period.
+
+If the input is valid, returns a rounding result consistent with the datetime
type:
+
+When input is DATE, returns DATE;
+When input is DATETIME, returns DATETIME (including date and time, with the
time part being 00:00:00, since the period is based on days).
+
+Special cases:
+
+- When any parameter is NULL, returns NULL;
+- If period is negative or 0, returns an error;
+- If the rounding result exceeds the supported range of date types (such as
after '9999-12-31'), an error is reported.
+- For datetime input with scale, the output will truncate all decimal to 0,
and the return value will have scale
+- If the `<origin>` date and time is after the `<period>`, it will still be
calculated according to the above formula, but the period k will be negative.
## Examples
```sql
-select day_ceil("2023-07-13 22:28:18", 5);
-```
-```text
+---Round up with a period of five days
+select day_ceil( cast("2023-07-13 22:28:18" as datetime), 5);
+
++------------------------------------+
+| day_ceil("2023-07-13 22:28:18", 5) |
++------------------------------------+
+| 2023-07-15 00:00:00 |
++------------------------------------+
+
+---Datetime input with scale, return value has scale with all decimals as 0
+
+select day_ceil( "2023-07-13 22:28:18.123", 5);
++-----------------------------------------+
+| day_ceil( "2023-07-13 22:28:18.123", 5) |
++-----------------------------------------+
+| 2023-07-15 00:00:00.000 |
++-----------------------------------------+
+
+---Without specifying period, default to round up by one day
+select day_ceil("2023-07-13 22:28:18");
+
++---------------------------------+
+| day_ceil("2023-07-13 22:28:18") |
++---------------------------------+
+| 2023-07-14 00:00:00 |
++---------------------------------+
+
+---Specify period as 7 days (1 week), custom reference time as 2023-01-01
00:00:00
+select day_ceil("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00");
++-----------------------------------------------------------+
+| day_ceil("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00") |
+-----------------------------------------------------------+
-| day_ceil(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) |
+| 2023-07-16 00:00:00 |
++-----------------------------------------------------------+
+
+---Date and time is exactly at the start of the period
+select day_ceil("2023-07-16 00:00:00", 7, "2023-01-01 00:00:00");
+-----------------------------------------------------------+
-| 2023-07-17 00:00:00 |
+| day_ceil("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00") |
+-----------------------------------------------------------+
+| 2023-07-16 00:00:00 |
++-----------------------------------------------------------+
+
+---Input is DATE type, period is 3 days
+select day_ceil(cast("2023-07-13" as date), 3);
+
++-----------------------------------------+
+| day_ceil(cast("2023-07-13" as date), 3) |
++-----------------------------------------+
+| 2023-07-14 |
++-----------------------------------------+
+
+--- If the <origin> date and time is after the <period>, it will still be
calculated according to the above formula, but the period k will be negative.
+select day_ceil('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00');
++---------------------------------------------------------------+
+| day_ceil('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') |
++---------------------------------------------------------------+
+| 2023-07-17 08:00:00.000 |
++---------------------------------------------------------------+
+
+---Period time is zero, returns NULL
+select day_ceil(cast("2023-07-13" as date), 0);
++-----------------------------------------+
+| day_ceil(cast("2023-07-13" as date), 0) |
++-----------------------------------------+
+| NULL |
++-----------------------------------------+
+
+---Period is negative
+mysql> select day_ceil("2023-07-13 22:28:18", -2);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
day_ceil of 2023-07-13 22:28:18, -2 out of range
+
+---Return date exceeds maximum range, returns error
+select day_ceil("9999-12-31", 5);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
day_ceil of 9999-12-31 00:00:00, 5 out of range
+
+---Any parameter is NULL, returns NULL
+select day_ceil(NULL, 5, "2023-01-01");
+
++---------------------------------+
+| day_ceil(NULL, 5, "2023-01-01") |
++---------------------------------+
+| NULL |
++---------------------------------+
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
index 20c322fab37..24c0561f099 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
@@ -1,45 +1,126 @@
---
{
- "title": "DAY_FLOOR",
- "language": "en"
+ "title": "DAY_FLOOR",
+ "language": "en"
}
---
## Description
-Rounds the date down to the nearest timestamp of the specified time interval
period.
+The DAY_FLOOR function is used to round down a specified date or time value to
the start of the nearest specified day period. It returns the largest period
moment that is not greater than the input date and time. The period rule is
defined jointly by period (number of days in the period) and origin (starting
reference time). If no starting reference time is specified, it defaults to
0001-01-01 00:00:00 as the calculation basis.
+
+Date calculation formula:
+
+$$
+\text{DAY\_FLOOR}(\langle\text{date\_or\_time\_expr}\rangle,
\langle\text{period}\rangle, \langle\text{origin}\rangle) =
\max\{\langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times
\text{day} \mid k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times
\langle\text{period}\rangle \times \text{day} \leq
\langle\text{date\_or\_time\_expr}\rangle\}
+$$
+
+where K represents the number of periods from the reference time to the target
time.
## Syntax
```sql
-DAY_FLOOR(<datetime>)
-DAY_FLOOR(<datetime>, <origin>)
-DAY_FLOOR(<datetime>, <period>)
-DAY_FLOOR(<datetime>, <period>, <origin>)
+DAY_FLOOR(<date_or_time_expr>)
+DAY_FLOOR(<date_or_time_expr>, <origin>)
+DAY_FLOOR(<date_or_time_expr>, <period>)
+DAY_FLOOR(<date_or_time_expr>, <period>, <origin>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<datetime>` | A valid date expression |
-| `<period>` | Specifies how many days make up each period |
-| `<origin>` | The starting point of time. If not provided, the default is
0001-01-01T00:00:00 |
+| `<date_or_time_expr>` | A valid date expression that supports date/datetime
types. For specific datetime and date formats, please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
+| `<period>` | Specifies the number of days in each period, of type INT. If
negative or 0, returns NULL; if not specified, the default period is 1 day. |
+| `<origin>` | The starting reference time for period calculation, supports
date/datetime types |
## Return Value
-Returns the date of the nearest rounded-up timestamp.
+Returns a date or time value representing the result of rounding down the
input value to the specified day period.
+
+If the input is valid, returns a rounding result consistent with the datetime
type:
+
+When input is DATE, returns DATE
+When input is DATETIME, returns DATETIME (including date and time, with the
time part being 00:00:00, since the period is based on days).
+
+Special cases:
+
+- When any parameter is NULL, returns NULL;
+- If period is negative or 0, returns error;
+- For datetime input with scale, the output will have scale with all decimals
as 0
+- If the `<origin>` date and time is after the `<period>`, it will still be
calculated according to the above formula, but the period k will be negative.
## Examples
```sql
+---Round down with a period of five days
select day_floor("2023-07-13 22:28:18", 5);
-```
-```text
++-------------------------------------+
+| day_floor("2023-07-13 22:28:18", 5) |
++-------------------------------------+
+| 2023-07-10 00:00:00 |
++-------------------------------------+
+
+
+---Datetime input with scale, return value has scale with all decimals as 0
+mysql> select day_floor("2023-07-13 22:28:18.123", 5);
++-----------------------------------------+
+| day_floor("2023-07-13 22:28:18.123", 5) |
++-----------------------------------------+
+| 2023-07-10 00:00:00.000 |
++-----------------------------------------+
+
+
+---Input parameter without period, default to one day as period
+select day_floor("2023-07-13 22:28:18");
++----------------------------------+
+| day_floor("2023-07-13 22:28:18") |
++----------------------------------+
+| 2023-07-13 00:00:00 |
++----------------------------------+
+
+---Specify period as 7 days (1 week), custom reference time as 2023-01-01
00:00:00
+select day_floor("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00");
++------------------------------------------------------------+
+| day_floor("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00") |
++------------------------------------------------------------+
+| 2023-07-09 00:00:00 |
++------------------------------------------------------------+
+
+---Start time is exactly at the beginning of a period, returns input date time
+select day_floor("2023-07-09 00:00:00", 7, "2023-01-01 00:00:00");
+------------------------------------------------------------+
-| day_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) |
+| day_floor("2023-07-09 00:00:00", 7, "2023-01-01 00:00:00") |
+------------------------------------------------------------+
-| 2023-07-12 00:00:00 |
+| 2023-07-09 00:00:00 |
+------------------------------------------------------------+
+
+---Input is DATE type, period is 3 days
+select day_floor(cast("2023-07-13" as date), 3);
++------------------------------------------+
+| day_floor(cast("2023-07-13" as date), 3) |
++------------------------------------------+
+| 2023-07-11 |
++------------------------------------------+
+
+---Period is negative, returns error
+select day_floor("2023-07-13 22:28:18", -2);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
day_floor of 2023-07-13 22:28:18, -2 out of range
+
+--- If the <origin> date and time is after the <period>, it will still be
calculated according to the above formula, but the period k will be negative.
+select day_floor('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00');
++----------------------------------------------------------------+
+| day_floor('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') |
++----------------------------------------------------------------+
+| 2023-07-13 08:00:00.000 |
++----------------------------------------------------------------+
+
+---Any parameter is NULL, returns NULL
+select day_floor(NULL, 5, "2023-01-01");
++----------------------------------+
+| day_floor(NULL, 5, "2023-01-01") |
++----------------------------------+
+| NULL |
++----------------------------------+
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
index 3f5b824c4a3..82d920d8778 100644
--- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
+++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
@@ -7,7 +7,9 @@
## Description
-Obtain the day information from the date, with return values ranging from 1 to
31.
+The DAY function is used to extract the "day" part from a date or time
expression, returning an integer value ranging from 1 to 31 (depending on the
month and year).
+
+This function behaves consistently with the [day
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_day)
in MySQL
## Alias
@@ -16,29 +18,51 @@ Obtain the day information from the date, with return
values ranging from 1 to 3
## Syntax
```sql
-DAY(<dt>)
+DAY(<date_or_time_expr>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| <`dt`> | A valid date expression |
+| `<date_or_time_expr>` | A valid date expression that supports date/datetime
types. For specific datetime and date formats, please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## Return Value
-Returns the day information from the given date.
+Returns integer information (1-31) for the "day" in the date.
+
+Special cases:
+
+If `dt` is NULL, returns NULL;
## Examples
```sql
+
+--Extract day from DATE type
select day('1987-01-31');
-```
-```text
+----------------------------+
| day('1987-01-31 00:00:00') |
+----------------------------+
| 31 |
+----------------------------+
+
+---Extract day from DATETIME type (ignoring time part)
+select day('2023-07-13 22:28:18');
+
++----------------------------+
+| day('2023-07-13 22:28:18') |
++----------------------------+
+| 13 |
++----------------------------+
+
+---Input is NULL
+select day(NULL);
+
++-----------+
+| day(NULL) |
++-----------+
+| NULL |
++-----------+
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
index c3ca310269a..699a433b86b 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
@@ -7,34 +7,58 @@
## Description
-Calculates the name of the day corresponding to the given date expression.
+The DAYNAME function is used to calculate the name of the day (such as
"Tuesday", etc.) corresponding to a date or time expression, returning a string
type value.
+
+This function behaves consistently with the [dayname
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_dayname)
in MySQL
## Syntax
```sql
-DAYNAME(<dt>)
+DAYNAME(<date_or_time_expr>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<dt>` | The date expression to be calculated |
+| `<date_or_time_expr>` | A valid date expression that supports date/datetime
types and strings in date-time format. For specific datetime and date formats,
please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## Return Value
-Returns the name of the day corresponding to the given date expression.
+Returns the day name corresponding to the date (string type)
+
+Special cases:
+
+- If `date_or_time_expr` is NULL, returns NULL;
## Examples
```sql
+
+---Calculate day name corresponding to DATETIME type
select dayname('2007-02-03 00:00:00');
-```
-```text
+--------------------------------+
| dayname('2007-02-03 00:00:00') |
+--------------------------------+
| Saturday |
+--------------------------------+
+
+---Calculate day name corresponding to DATE type
+
+select dayname('2023-10-01');
++-----------------------+
+| dayname('2023-10-01') |
++-----------------------+
+| Sunday |
++-----------------------+
+
+
+---Parameter is NULL, returns NULL
+select dayname(NULL);
++---------------+
+| dayname(NULL) |
++---------------+
+| NULL |
++---------------+
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
index 0ca5a821297..b21c4a9e44f 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
@@ -7,7 +7,9 @@
## Description
-Returns the weekday index of the date, where Sunday is 1, Monday is 2, and
Saturday is 7.
+The DAYOFWEEK function is used to return the weekday index value corresponding
to a date or time expression, following the rule where Sunday is 1, Monday is
2, ..., and Saturday is 7.
+
+This function behaves consistently with the [dayofweek
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_dayofweek)
in MySQL
## Alias
@@ -16,41 +18,56 @@ Returns the weekday index of the date, where Sunday is 1,
Monday is 2, and Satur
## Syntax
```sql
-DAYOFWEEK(<dt>)
+DAYOFWEEK(<date_or_time_expr>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<dt>` | The date expression to be calculated |
+| `<date_or_time_expr>` | A valid date expression that supports date/datetime
types. For specific datetime and date formats, please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## Return Value
-Returns the weekday index of the date.
+Returns an integer representing the weekday index value corresponding to the
date (1-7, where 1 represents Sunday and 7 represents Saturday).
+
+Special cases:
+
+If `<date_or_time_expr>` is NULL, returns NULL;
## Examples
```sql
+---Calculate weekday index value for date type
select dayofweek('2019-06-25');
-```
-```text
+----------------------------------+
| dayofweek('2019-06-25 00:00:00') |
+----------------------------------+
| 3 |
+----------------------------------+
-```text
-```sql
-select dayofweek(cast(20190625 as date));
-```
+---Calculate weekday index value for datetime type
+select dayofweek('2019-06-25 15:30:45');
+
++----------------------------------+
+| dayofweek('2019-06-25 15:30:45') |
++----------------------------------+
+| 3 |
++----------------------------------+
+---Index for Sunday
+select dayofweek('2024-02-18');
++-------------------------+
+| dayofweek('2024-02-18') |
++-------------------------+
+| 1 |
++-------------------------+
-```text
-+-----------------------------------+
-| dayofweek(CAST(20190625 AS DATE)) |
-+-----------------------------------+
-| 3 |
-+-----------------------------------+
+---Input datetime is NULL, returns NULL
+select dayofweek(NULL);
++-----------------+
+| dayofweek(NULL) |
++-----------------+
+| NULL |
++-----------------+
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
index a8ce8142cd0..a448cc750c9 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
@@ -7,7 +7,9 @@
## Description
-Obtains the corresponding day of the year for the given date.
+The DAYOFYEAR function is used to calculate the number of days in the current
year corresponding to a date or time expression, i.e., which day of the year
the date is. The return value is an integer ranging from 1 (January 1st) to 366
(December 31st in a leap year).
+
+This function behaves consistently with the [dayofyear
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_dayofyear)
in MySQL
## Alias
@@ -16,29 +18,59 @@ Obtains the corresponding day of the year for the given
date.
## Syntax
```sql
-DAYOFYEAR(<dt>)
+DAYOFYEAR(<date_or_time_expr>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<dt>` | The date expression to be calculated |
+| `<date_or_time_expr>` | A valid date expression that supports date/datetime
types. For specific datetime and date formats, please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## Return Value
-Returns the day of the year corresponding to the given date.
+Returns an integer representing the number of days in the current year
(1-366), of type SMALLINT.
+
+Special cases:
+
+- If <date_or_time_expr> is NULL, returns NULL;
+- For February 29th in a leap year, it will be correctly calculated as the
60th day of the year.
## Examples
```sql
+
+---Extract the day number in the year from datetime type
select dayofyear('2007-02-03 00:00:00');
-```
-```text
+----------------------------------+
| dayofyear('2007-02-03 00:00:00') |
+----------------------------------+
| 34 |
+----------------------------------+
+
+---Extract day number from date type
+select dayofyear('2023-12-31');
++-------------------------+
+| dayofyear('2023-12-31') |
++-------------------------+
+| 365 |
++-------------------------+
+
+
+---Calculate day number in a leap year
+select dayofyear('2024-12-31');
++-------------------------+
+| dayofyear('2024-12-31') |
++-------------------------+
+| 366 |
++-------------------------+
+
+---Input is NULL, returns NULL
+select dayofyear(NULL);
++-----------------+
+| dayofyear(NULL) |
++-----------------+
+| NULL |
++-----------------+
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
index 783d3e0f866..aeebeb1c723 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
@@ -7,43 +7,100 @@
## Description
-The `extract` function is used to extract a specified part of a date or time
value, such as the year, month, day, hour, minute, second, etc. This function
is commonly used to extract specific time components from a datetime field for
calculation, comparison, or display.
+The `EXTRACT` function is used to extract specific time components from date
or time values, such as year, month, week, day, hour, minute, second, etc. This
function can precisely obtain specific parts of a datetime.
+
+This function behaves mostly consistently with the [extract
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_extract)
in MySQL. The difference is that Doris currently does not support combined
unit inputs, such as:
+
+```sql
+mysql> SELECT EXTRACT(YEAR_MONTH FROM '2019-07-02 01:02:03');
+ -> 201907
+```
## Syntax
-`EXTRACT(<unit> FROM <datetime>)`
+`EXTRACT(<unit> FROM <date_or_time_expr>)`
## Parameters
| Parameter | Description |
| -- | -- |
-| `unit` | The unit to extract from the DATETIME. Possible values are year,
month, day, hour, minute, second, microsecond, dayofyear(doy), dayofweek(dow) |
-| `datetime` | The argument is a valid date expression |
+| `<unit>` | Extract the value of a specified unit from DATETIME. The unit can
be year, month, week, day, hour, minute, second, or microsecond |
+| `<datetime_or_time_expr>` | A valid date expression that supports
date/datetime types and strings in date-time format. For specific datetime and
date formats, please refer to [datetime
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## Return Value
-The return value is the extracted part of the date or time (such as an
integer), depending on the unit being extracted.
+Returns the extracted part of the date or time, of type INT, depending on the
extracted unit.
+
+The value range for the week unit is 0-53, calculated as follows:
+
+- Sunday is the first day of the week.
+- The week containing the first Sunday of the year is week 1.
+- Dates before the first Sunday belong to week 0.
+
+When the unit is year, month, day, hour, minute, second, microsecond, it
returns the corresponding unit value in the datetime.
+
+When the unit is quarter, January-March returns 1, April-June returns 2,
July-September returns 3, October-December returns 4.
+
+Special cases:
+
+If <date_or_time_expr> is NULL, returns NULL.
+If <unit> is an unsupported unit, an error is reported.
## Examples
```sql
+
+---Extract year, month, day, hour, minute, second, microsecond time components
from datetime
select extract(year from '2022-09-22 17:01:30') as year,
extract(month from '2022-09-22 17:01:30') as month,
extract(day from '2022-09-22 17:01:30') as day,
extract(hour from '2022-09-22 17:01:30') as hour,
extract(minute from '2022-09-22 17:01:30') as minute,
extract(second from '2022-09-22 17:01:30') as second,
-extract(microsecond from cast('2022-09-22 17:01:30.000123' as datetimev2(6)))
as microsecond,
-extract(dayofyear FROM '2022-09-22 17:01:30') as dayofyear,
-extract(doy FROM '2022-09-22 17:01:30') as dayofyear_alias,
-extract(dayofweek FROM '2022-09-22 17:01:30') as dayofweek,
-extract(dow FROM '2022-09-22 17:01:30') as dayofweek_alias;
-```
+extract(microsecond from cast('2022-09-22 17:01:30.000123' as datetime(6))) as
microsecond;
+
++------+-------+------+------+--------+--------+-------------+
+| year | month | day | hour | minute | second | microsecond |
++------+-------+------+------+--------+--------+-------------+
+| 2022 | 9 | 22 | 17 | 1 | 30 | 123 |
++------+-------+------+------+--------+--------+-------------+
+
+---Extract quarter from datetime
+
+mysql> select extract(quarter from '2023-05-15') as quarter;
+
++---------+
+| quarter |
++---------+
+| 2 |
++---------+
+
+---Extract week number for the corresponding date. Since the first Sunday of
2024 is on January 7th, all dates before 01-07 return 0
+select extract(week from '2024-01-06') as week;
++------+
+| week |
++------+
+| 0 |
++------+
+
+--- January 7th is the first Sunday, returns 1
+select extract(week from '2024-01-07') as week;
++------+
+| week |
++------+
+| 1 |
++------+
+
+---Under this rule, 2024 only has weeks 0-52
+select extract(week from '2024-12-31') as week;
++------+
+| week |
++------+
+| 52 |
++------+
+
+---Input unit does not exist, reports error
+select extract(uint from '2024-01-07') as week;
-```text
-+------+-------+------+------+--------+--------+-------------+-----------+-----------------+-----------+-----------------+
-| year | month | day | hour | minute | second | microsecond | dayofyear |
dayofyear_alias | dayofweek | dayofweek_alias |
-+------+-------+------+------+--------+--------+-------------+-----------+-----------------+-----------+-----------------+
-| 2022 | 9 | 22 | 17 | 1 | 30 | 123 | 265 |
265 | 5 | 5 |
-+------+-------+------+------+--------+--------+-------------+-----------+-----------------+-----------+-----------------+
+ERROR 1105 (HY000): errCode = 2, detailMessage = Can not found function 'uint'
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
index 801e31f80e5..18176291dde 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
@@ -7,36 +7,57 @@
## Description
-Given a number of days, returns a DATE.
+The FROM_DAYS function is used to convert an integer number of days to the
corresponding date (DATE type). This function uses "January 1st, year 1" as the
reference point (i.e., day 0 corresponds to 0000-01-01), calculating the date
after the specified number of days from the reference date.
-- Note: To maintain consistent behavior with MySQL, the date 0000-02-29 does
not exist.
+Note: To maintain behavioral consistency with MySQL, the FROM_DAYS function
does not support "February 29th, year 1" (0000-02-29), even though
theoretically this year conforms to leap year rules, this date will be
automatically skipped.
+Historical date limitation: This function calculates based on the extended
Gregorian calendar, and is not suitable for dates before the Gregorian calendar
was introduced in 1582 (when the Julian calendar was actually used), which may
cause discrepancies between results and actual historical dates.
+
+This function behaves consistently with the [from_days
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_from-days)
in MySQL
## Syntax
```sql
-FROM_DAYS(<dt>)
+FROM_DAYS(<days>)
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<dt>`| Days |
+| `<days>` | Input number of days, of type `INT` |
## Return Value
-Returns the date corresponding to the given number of days.
+Returns a DATE type value in the format YYYY-MM-DD, representing the date
after days from the reference date (0000-01-01).
+If days is negative, returns NULL.
+If days exceeds the valid date range (typically 1 to 3652424, corresponding to
approximately year 10000), returns an error.
## Examples
```sql
+
+---Calculate days from the reference date
select from_days(730669),from_days(5),from_days(59), from_days(60);
-```
-```text
+-------------------+--------------+---------------+---------------+
| from_days(730669) | from_days(5) | from_days(59) | from_days(60) |
+-------------------+--------------+---------------+---------------+
| 2000-07-03 | 0000-01-05 | 0000-02-28 | 0000-03-01 |
+-------------------+--------------+---------------+---------------+
+
+---If the input parameter is negative, an error is returned
+select from_days(-60);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_days of -60 out of range
+
+---If the input is NULL, returns NULL
+select from_days(NULL);
++-----------------+
+| from_days(NULL) |
++-----------------+
+| NULL |
++-----------------+
+
+---If days exceeds the valid date range (typically 1 to 3652424, corresponding
to approximately year 10000), an error is returned
+select from_days(99999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_days of 99999999 out of range
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
index bc62c476dc4..2427b9a5dce 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
@@ -7,6 +7,13 @@
## Description
Converts an ISO8601 formatted date expression to a DATE type date expression.
+Date strings conforming to the ISO 8601 standard, supported formats include:
+- YYYY: Year only (returns January 1st of that year)
+- YYYY-MM: Year and month (returns the 1st of that month)
+- YYYY-DDD: Year + day of year (DDD range 1-366, e.g., 0000-059 represents the
59th day of year 0000)
+- YYYY-WWW: Year + week number (WWW range 1-53, returns Monday of that week)
+- YYYY-WWW-D: Year + week number + day of week (D range 1-7, 1 represents
Monday, 7 represents Sunday)
+- In this format, the first week of a year must contain Thursday of that week,
otherwise it is counted as a week of the previous year
## Syntax
@@ -18,22 +25,77 @@ from_iso8601_date(<dt>)
| Parameter | Description |
| -- | -- |
-| `<dt>` | An ISO8601 formatted date |
+| `<date>` | ISO8601 formatted date, of string type |
## Return Value
-A DATE type date expression.
+Returns DATE type in the format YYYY-MM-DD, representing the parsed specific
date.
+- If the input format is invalid (e.g., week number exceeds 53), returns NULL.
+- If the input contains time or timezone information (e.g., 2023-10-01T12:34),
returns NULL.
+- Input NULL, returns NULL
## Examples
```sql
-SELECT
from_iso8601_date('0000-01'),from_iso8601_date('0000-W01'),from_iso8601_date('0000-059');
-```
+-- Parse different ISO 8601 formatted date strings
+select
+ from_iso8601_date('2023') as year_only,
+ from_iso8601_date('2023-10') as year_month,
+ from_iso8601_date('2023-10-05') as full_date;
+
++------------+------------+------------+
+| year_only | year_month | full_date |
++------------+------------+------------+
+| 2023-01-01 | 2023-10-01 | 2023-10-05 |
++------------+------------+------------+
+
+-- Parse "year-day number" format
+select
+ from_iso8601_date('2021-001') as day_1,
+ from_iso8601_date('2021-059') as day_59,
+ from_iso8601_date('2021-060') as day_60,
+ from_iso8601_date('2024-366') as day_366;
+
++------------+------------+------------+------------+
+| day_1 | day_59 | day_60 | day_366 |
++------------+------------+------------+------------+
+| 0000-01-01 | 0000-02-28 | 0000-03-01 | 2024-12-31 |
++------------+------------+------------+------------+
+
+-- Parse "YYY-MMM-D" format (each week starts with Monday), since 0522-01-01
is Thursday, dates before the first week will return year 0521
+select from_iso8601_date('0522-W01-1') as week_1;
++------------+
+| week_1 |
++------------+
+| 0521-12-29 |
++------------+
+1 row in set (0.02 sec)
+
+select from_iso8601_date('0522-W01-4') as week_4;
++------------+
+| week_4 |
++------------+
+| 0522-01-01 |
++------------+
+
+---YYY-MMM format, Monday of the first week is in year 521
+select from_iso8601_date('0522-W01') as week_1;
+
++------------+
+| week_1 |
++------------+
+| 0521-12-29 |
++------------+
+
+---invalid style, return error
+select from_iso8601_date('2023-10-01T12:34:10');
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INVALID_ARGUMENT]Operation from_iso8601_date of
2023-10-01T12:34:10 is invalid
-```text
-+------------------------------+-------------------------------+-------------------------------+
-| from_iso8601_date('0000-01') | from_iso8601_date('0000-W01') |
from_iso8601_date('0000-059') |
-+------------------------------+-------------------------------+-------------------------------+
-| 0000-01-01 | 0000-01-03 | 0000-02-28
|
-+------------------------------+-------------------------------+-------------------------------+
+---input NULL
+select from_iso8601_date(NULL);
++-------------------------+
+| from_iso8601_date(NULL) |
++-------------------------+
+| NULL |
++-------------------------+
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
index 7f34ab3a4f7..81439076699 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
@@ -4,39 +4,74 @@
"language": "en"
}
---
-
## Description
-The function converts a Unix timestamp (in microseconds) into a `DATETIME`
value.
-
+The FROM_MICROSECOND function is used to convert a Unix timestamp (in
microseconds) to a `DATETIME` type date-time value. The reference time for Unix
timestamps is 1970-01-01 00:00:00 UTC, and this function converts the input
microseconds to the corresponding specific date and time after that reference
time (including the fractional part of seconds, accurate to microseconds).
## Syntax
```sql
FROM_MICROSECOND(<unix_timestamp>)
```
+
## Parameters
-| Parameter | Description
|
-|--------------------|-------------------------------------------------------------------------------------------------------------|
-| `<unix_timestamp>` | Required. The Unix timestamp representing the number of
microseconds elapsed since 1970-01-01 00:00:00 UTC. |
+| Parameter | Description |
+| -- | -- |
+| `<unix_timestamp>` | Input Unix timestamp, of integer type (BIGINT),
representing the number of microseconds from 1970-01-01 00:00:00 UTC |
## Return Value
-- Returns a DATETIME value representing the date and time corresponding to the
given Unix timestamp.
-- If `<unix_timestamp>` is NULL, the function returns NULL.
-- If `<unix_timestamp>` is out of valid range, the function returns an error.
+Returns a DATETIME type value representing the result of converting the UTC
timezone unix timestamp to the current timezone time
+- If <unix_timestamp> is NULL, the function returns NULL.
+- If the input <unix_timestamp> can be converted to integer seconds, the
result returns datetime without scale; if not, the result returns datetime with
scale
+- If <unix_timestamp> is less than 0, returns an error
+- If the returned datetime exceeds the maximum time 9999-12-31 23:59:59,
returns an error
-## Example
+## Examples
```sql
+
+---Current machine is in East 8th timezone, so the returned time is 8 hours
ahead of UTC
+SELECT FROM_MICROSECOND(0);
++----------------------------+
+| FROM_MICROSECOND(0) |
++----------------------------+
+| 1970-01-01 08:00:00.000000 |
++----------------------------+
+
+---Convert 1700000000000000 microseconds added to reference time to datetime
SELECT FROM_MICROSECOND(1700000000000000);
-```
-```text
+------------------------------------+
| from_microsecond(1700000000000000) |
+------------------------------------+
| 2023-11-15 06:13:20 |
+------------------------------------+
+
+-- Timestamp contains non-integer seconds (1700000000 seconds + 123456
microseconds)
+select from_microsecond(1700000000123456) as dt_with_micro;
+
++----------------------------+
+| dt_with_micro |
++----------------------------+
+| 2023-11-15 06:13:20.123456 |
++----------------------------+
+
+---Input negative number, returns error
+ select from_microsecond(-1);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_microsecond of -1 out of range
+
+
+---Input NULL, returns NULL
+select from_microsecond(NULL);
++------------------------+
+| from_microsecond(NULL) |
++------------------------+
+| NULL |
++------------------------+
+
+---Exceeds maximum time range 9999-12-31 23:59:59, returns error
+select from_microsecond(999999999999999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_microsecond of 999999999999999999 out of range
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
index 08cb7ab5e34..b3f50e9df45 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
@@ -4,38 +4,75 @@
"language": "en"
}
---
-
## Description
-The function converts a Unix timestamp (in milliseconds) into a `DATETIME`
value.
+The FROM_MILLISECOND function is used to convert a Unix timestamp (in
milliseconds) to a DATETIME type date-time value. The reference time for Unix
timestamps is 1970-01-01 00:00:00 UTC, and this function converts the input
milliseconds to the corresponding specific date and time after that reference
time (accurate to milliseconds).
## Syntax
```sql
FROM_MILLISECOND(<millisecond>)
```
+
## Parameters
-| Parameter | Description
|
-|-----------------|-------------------------------------------------------------------------------------------------------------|
-| `<millisecond>` | Required. The Unix timestamp representing the number of
milliseconds elapsed since 1970-01-01 00:00:00 UTC. |
+| Parameter | Description |
+| -- | -- |
+| `<millisecond>` | Input Unix timestamp, of integer type (BIGINT),
representing the number of milliseconds from 1970-01-01 00:00:00 UTC. |
## Return Value
-- Returns a DATETIME value representing the date and time corresponding to the
given Unix timestamp.
-- If <millisecond> is NULL, the function returns NULL.
-- If <millisecond> is out of valid range, the function returns an error.
+Returns a DATETIME type value representing the result of converting the input
UTC timezone unix timestamp to the current timezone time
+- If millisecond is NULL, the function returns NULL.
+- If millisecond exceeds the valid range (result datetime exceeds 9999-12-31
23:59:59), the function returns an error.
+- If the input millisecond can be converted to integer seconds, the result
returns datetime without scale; if not, the result returns datetime with scale
+- Input negative number, result returns error
-## Example
+## Examples
```sql
+
+----Since the current machine is in East 8th timezone, the returned time is 8
hours ahead of UTC
+SELECT FROM_MILLISECOND(0);
++-------------------------+
+| FROM_MILLISECOND(0) |
++-------------------------+
+| 1970-01-01 08:00:00.000 |
++-------------------------+
+
+-- Convert 1700000000000 milliseconds to datetime
SELECT FROM_MILLISECOND(1700000000000);
-```
-```text
+---------------------------------+
| from_millisecond(1700000000000) |
+---------------------------------+
| 2023-11-15 06:13:20 |
+---------------------------------+
-```
\ No newline at end of file
+
+-- Timestamp contains non-zero milliseconds (1700000000 seconds + 123
milliseconds)
+select from_millisecond(1700000000123) as dt_with_milli;
+
++----------------------------+
+| dt_with_milli |
++----------------------------+
+| 2023-11-15 06:13:20.123000 |
++----------------------------+
+
+---Input is NULL, result returns NULL
+select from_millisecond(NULL);
++------------------------+
+| from_millisecond(NULL) |
++------------------------+
+| NULL |
++------------------------+
+
+---Input is negative, result returns error
+ select from_millisecond(-1);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_millisecond of -1 out of range
+
+
+--Result exceeds maximum date, returns error
+select from_millisecond(999999999999999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_millisecond of 999999999999999999 out of range
+```
+
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
index 04f74d50414..2e3d17948c2 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
@@ -6,35 +6,61 @@
---
## Description
-The function converts a Unix timestamp (in seconds) into a `DATETIME` value.
-
+The FROM_SECOND function is used to convert a Unix timestamp (in seconds) to a
DATETIME type date-time value. The reference time for Unix timestamps is
1970-01-01 00:00:00 UTC, and this function converts the input seconds to the
corresponding specific date and time after that reference time (accurate to
seconds).
## Syntax
```sql
FROM_SECOND(<unix_timestamp>)
```
+
## Parameters
-| Parameter | Description
|
-|--------------------|--------------------------------------------------------------------------------------------------------|
-| `<unix_timestamp>` | Required. The Unix timestamp representing the number of
seconds elapsed since 1970-01-01 00:00:00 UTC. |
+| Parameter | Description |
+| -- | -- |
+| `<unix_timestamp>` | Input Unix timestamp, of integer type (BIGINT),
representing the number of seconds from 1970-01-01 00:00:00 UTC. |
## Return Value
-- Returns a DATETIME value representing the date and time corresponding to the
given Unix timestamp.
-- If `<unix_timestamp>` is NULL, the function returns NULL.
-- If `<unix_timestamp>` is out of valid range, the function returns an error.
-## Example
+- Returns a DATETIME type value representing the result of converting the
input UTC timezone unix timestamp to the current timezone time
+- If <unix_timestamp> is NULL, the function returns NULL.
+- If <unix_timestamp> exceeds the valid range (result datetime exceeds
9999-12-31 23:59:59), the function returns an error.
+- Input negative seconds, the function returns an error
+
+## Examples
```sql
+
+----Since the current machine is in East 8th timezone, the returned time is 8
hours ahead of UTC
+ SELECT FROM_SECOND(0);
++---------------------+
+| FROM_SECOND(0) |
++---------------------+
+| 1970-01-01 08:00:00 |
++---------------------+
+
+---Convert 1700000000 seconds to datetime
SELECT FROM_SECOND(1700000000);
-```
-```text
+-------------------------+
| from_second(1700000000) |
+-------------------------+
| 2023-11-15 06:13:20 |
+-------------------------+
+
+---Result exceeds maximum date range, returns error
+select from_second(999999999999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INTERNAL_ERROR]The function from_second Argument value is out of
DateTime range
+
+---Input parameter is NULL, returns NULL
+select from_second(NULL);
++-------------------+
+| from_second(NULL) |
++-------------------+
+| NULL |
++-------------------+
+
+--Input parameter is negative, result returns error
+ select from_second(-1);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_second of -1 out of range
```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
index f2a9f98ae85..9d314f68298 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
@@ -7,32 +7,45 @@
## Description
-Converts a Unix timestamp to the corresponding TIME format.
-Special cases:
+The FROM_UNIXTIME function is used to convert a Unix timestamp (in seconds) to
a date-time string or VARCHAR type value in a specified format. The reference
time for Unix timestamps is 1970-01-01 00:00:00 UTC, and the function generates
the corresponding date-time representation based on the input timestamp and
format string.
-- Supported input range for `unix_timestamp` is `[0, 253402271999.999999]`.
Values outside this range return `NULL`.
+This function behaves consistently with the [from_unixtime
function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_from-unixtime)
in MySQl
## Syntax
```sql
-FROM_UNIXTIME(<unix_timestamp>[, <string_format>])
+FROM_UNIXTIME(<unix_timestamp> [, <string_format>])
```
## Parameters
| Parameter | Description |
| -- | -- |
-| `<unix_timestamp>` | unix timestamp |
-| `<string_format>` | The format format, with the default being %Y-%m-%d
%H:%i:%s.|
+| `<unix_timestamp>` | Input Unix timestamp, of integer type BIGINT,
representing the number of seconds from 1970-01-01 00:00:00 UTC |
+| `<string_format>` | Format string, supports varchar and string types,
default is %Y-%m-%d %H:%i:%s. For specific formats, please refer to
[date-format](./date-format) |
## Return Value
-Returns the date in the specified format.
+Returns date in specified format, of type VARCHAR, returning the result of
converting the UTC timezone unix timestamp to the current timezone time.
+- Currently supported unix_timestamp range is [0, 253402271999] corresponding
to dates from 1970-01-01 00:00:00 to 9999-12-31 23:59:59, unix_timestamp
outside this range will return an error
+- If string_format is invalid, returns a string that does not meet
expectations.
+- If any parameter is NULL, returns NULL
+- If the format length over than 128,return error
## Examples
-```
+```sql
+
+----Since the current timezone is East 8th zone, the returned time is 8 hours
ahead of UTC
+select from_unixtime(0);
++---------------------+
+| from_unixtime(0) |
++---------------------+
+| 1970-01-01 08:00:00 |
++---------------------+
+
+---Default format %Y-%m-%d %H:%i:%s return
mysql> select from_unixtime(1196440219);
+---------------------------+
| from_unixtime(1196440219) |
@@ -40,6 +53,7 @@ mysql> select from_unixtime(1196440219);
| 2007-12-01 00:30:19 |
+---------------------------+
+---Specify yyyy-MM-dd HH:mm:ss format return
mysql> select from_unixtime(1196440219, 'yyyy-MM-dd HH:mm:ss');
+--------------------------------------------------+
| from_unixtime(1196440219, 'yyyy-MM-dd HH:mm:ss') |
@@ -47,14 +61,8 @@ mysql> select from_unixtime(1196440219, 'yyyy-MM-dd
HH:mm:ss');
| 2007-12-01 00:30:19 |
+--------------------------------------------------+
--- Maximum supported time
-mysql> select from_unixtime(253402271999.999999);
-+------------------------------------+
-| from_unixtime(253402271999.999999) |
-+------------------------------------+
-| 9999-12-31 23:59:59.999999 |
-+------------------------------------+
+---Specify %Y-%m-%d date-only format return
mysql> select from_unixtime(1196440219, '%Y-%m-%d');
+-----------------------------------------+
| from_unixtime(1196440219, '%Y-%m-%d') |
@@ -62,10 +70,36 @@ mysql> select from_unixtime(1196440219, '%Y-%m-%d');
| 2007-12-01 |
+-----------------------------------------+
+---Specify %Y-%m-%d %H:%i:%s format return
mysql> select from_unixtime(1196440219, '%Y-%m-%d %H:%i:%s');
+--------------------------------------------------+
| from_unixtime(1196440219, '%Y-%m-%d %H:%i:%s') |
+--------------------------------------------------+
| 2007-12-01 00:30:19 |
+--------------------------------------------------+
+
+---Exceeds maximum range, returns error
+select from_unixtime(253402281999);
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INVALID_ARGUMENT]Operation from_unixtime_new of 253402281999,
yyyy-MM-dd HH:mm:ss is invalid
+
+---result over max length
+select from_unixtime(32536799,repeat('a',129));
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INVALID_ARGUMENT]Operation from_unixtime_new of invalid or
oversized format is invalid
+
+---string-format does not reference any time values
+mysql> select from_unixtime(32536799,"gdaskpdp");
++------------------------------------+
+| from_unixtime(32536799,"gdaskpdp") |
++------------------------------------+
+| gdaskpdp |
++------------------------------------+
+
+---Input is NULL, returns NULL
+mysql> select from_unixtime(NULL);
++---------------------+
+| from_unixtime(NULL) |
++---------------------+
+| NULL |
++---------------------+
+
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
index b489e7396b6..6d5bd49deb6 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md
@@ -7,39 +7,133 @@
## 描述
-将日期转化为指定的时间间隔周期的最近向上取整时刻。
+DAY_CEIL 函数用于将指定的日期或时间值向上取整（ceil）到最近的指定天数周期的起点。即返回不小于输入日期时间的最小周期时刻，周期规则由
period（周期天数）和 origin（起始基准时间）共同定义。若未指定起始基准时间，默认以 0001-01-01 00:00:00 为基准计算。
+
+日期计算公式
+$$
+\text{DAY\_CEIL}(\langle\text{date\_or\_time\_expr}\rangle,
\langle\text{period}\rangle, \langle\text{origin}\rangle) =
\min\{\langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times
\text{day} \mid k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times
\langle\text{period}\rangle \times \text{day} \geq
\langle\text{date\_or\_time\_expr}\rangle\}
+$$
+K 代表基准时间到达目标时间所需的周期数
## 语法
```sql
-DAY_CEIL(<datetime>)
-DAY_CEIL(<datetime>, <origin>)
-DAY_CEIL(<datetime>, <period>)
-DAY_CEIL(<datetime>, <period>, <origin>)
+DAY_CEIL(<date_or_time_expr>)
+DAY_CEIL(<date_or_time_expr>, <origin>)
+DAY_CEIL(<date_or_time_expr>, <period>)
+DAY_CEIL(<date_or_time_expr>, <period>, <origin>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<datetime>` | 合法的日期表达式 |
-| `<period>` | 参数是指定每个周期有多少天组成 |
-| `<origin>` | 开始的时间起点，如果不填，默认是 0001-01-01T00:00:00 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime 类型,具体 datetime 和 date
格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
+| `<period>` | 参数是指定每个周期包含的天数，类型为 INT。若未指定，默认周期为 1 天。 |
+| `<origin>` | 参数是周期计算的起始基准时间，支持 date/datetime 类型|
## 返回值
-返回最近向上取整时刻的日期。
+返回的是一个日期或时间值，表示将输入值向上舍入到指定天数周期的结果。
+
+若输入有效，返回与 datetime 类型一致的取整结果：
+
+`<date_or_time_expr>` 与 `<origin>` 输入都 DATE 类型时，返回 DATE 类型, 否则返回 DATETIME 类型.
+
+特殊情况：
+
+- 任何参数为 NULL 时，返回 NULL；
+- 若 period 为负数或 0，返回错误；
+- 若取整结果超出日期类型支持的范围（如 '9999-12-31' 之后），报错。
+- 带有 scale 的输入的datetime，返回值带有 scale，小数部分为 0.
+- 若 `<origin>` 日期时间在 `<period>` 之后，也会按照上述公式计算，不过周期 k 为负数。
## 举例
```sql
-select day_ceil("2023-07-13 22:28:18", 5);
-```
-```text
+---以五天为一周期向上取整
+select day_ceil( cast("2023-07-13 22:28:18" as datetime), 5);
+
++------------------------------------+
+| day_ceil("2023-07-13 22:28:18", 5) |
++------------------------------------+
+| 2023-07-15 00:00:00 |
++------------------------------------+
+
+---带有 scale 输入的日期时间，返回值带有 scale 且全部小数为 0
+
+select day_ceil( "2023-07-13 22:28:18.123", 5);
++-----------------------------------------+
+| day_ceil( "2023-07-13 22:28:18.123", 5) |
++-----------------------------------------+
+| 2023-07-15 00:00:00.000 |
++-----------------------------------------+
+
+---不指定周期，默认一天向上取整
+select day_ceil("2023-07-13 22:28:18");
+
++---------------------------------+
+| day_ceil("2023-07-13 22:28:18") |
++---------------------------------+
+| 2023-07-14 00:00:00 |
++---------------------------------+
+
+---指定周期为 7 天（1 周），自定义基准时间为 2023-01-01 00:00:00
+select day_ceil("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00");
+-----------------------------------------------------------+
-| day_ceil(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) |
+| day_ceil("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00") |
+-----------------------------------------------------------+
-| 2023-07-17 00:00:00 |
+| 2023-07-16 00:00:00 |
+-----------------------------------------------------------+
+
+---日期时间刚好是周期的起点
+select day_ceil("2023-07-16 00:00:00", 7, "2023-01-01 00:00:00");
++-----------------------------------------------------------+
+| day_ceil("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00") |
++-----------------------------------------------------------+
+| 2023-07-16 00:00:00 |
++-----------------------------------------------------------+
+
+---输入为 DATE 类型，周期为 3 天
+select day_ceil(cast("2023-07-13" as date), 3);
+
++-----------------------------------------+
+| day_ceil(cast("2023-07-13" as date), 3) |
++-----------------------------------------+
+| 2023-07-14 |
++-----------------------------------------+
+
+---周期时间为零，返回 NULL
+select day_ceil(cast("2023-07-13" as date), 0);
++-----------------------------------------+
+| day_ceil(cast("2023-07-13" as date), 0) |
++-----------------------------------------+
+| NULL |
++-----------------------------------------+
+
+--- 若 `<origin>` 日期时间在 `<period>` 之后，也会按照上述公式计算，不过周期 k 为负数。
+select day_ceil('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00');
++---------------------------------------------------------------+
+| day_ceil('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') |
++---------------------------------------------------------------+
+| 2023-07-17 08:00:00.000 |
++---------------------------------------------------------------+
+
+---周期为负数
+mysql> select day_ceil("2023-07-13 22:28:18", -2);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
day_ceil of 2023-07-13 22:28:18, -2 out of range
+
+---返回日期超过最大范围，返回错误
+select day_ceil("9999-12-31", 5);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
day_ceil of 9999-12-31 00:00:00, 5 out of range
+
+---任意参数为 NULL，返回 NULL
+select day_ceil(NULL, 5, "2023-01-01");
+
++---------------------------------+
+| day_ceil(NULL, 5, "2023-01-01") |
++---------------------------------+
+| NULL |
++---------------------------------+
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
index 1f37b863165..180c00152eb 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-floor.md
@@ -7,39 +7,118 @@
## 描述
-将日期转化为指定的时间间隔周期的最近向下取整时刻。
+DAY_FLOOR 函数用于将指定的日期或时间值向下取整（floor）到最近的指定天数周期的起点。即返回不大于输入日期时间的最大周期时刻，周期规则由
period（周期天数）和 origin（起始基准时间）共同定义。若未指定起始基准时间，默认以 0001-01-01 00:00:00 为基准计算。
+
+日期时间的计算公式
+$
+\text{DAY\_FLOOR}(\langle\text{date\_or\_time\_expr}\rangle,
\langle\text{period}\rangle, \langle\text{origin}\rangle) =
\max\{\langle\text{origin}\rangle + k \times \langle\text{period}\rangle \times
\text{day} \mid k \in \mathbb{Z} \land \langle\text{origin}\rangle + k \times
\langle\text{period}\rangle \times \text{day} \leq
\langle\text{date\_or\_time\_expr}\rangle\}
+$
+K 代表的是基准时间到目标时间的周期数
## 语法
```sql
-DAY_FLOOR(<datetime>)
-DAY_FLOOR(<datetime>, <origin>)
-DAY_FLOOR(<datetime>, <period>)
-DAY_FLOOR(<datetime>, <period>, <origin>)
+DAY_FLOOR(<date_or_time_expr>)
+DAY_FLOOR(<date_or_time_expr>, <origin>)
+DAY_FLOOR(<date_or_time_expr>, <period>)
+DAY_FLOOR(<date_or_time_expr>, <period>, <origin>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<datetime>` | 合法的日期表达式 |
-| `<period>` | 参数是指定每个周期有多少天组成 |
-| `<origin>` | 开始的时间起点，如果不填，默认是 0001-01-01T00:00:00 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime 类型,具体 datetime 和 date
格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
+| `<period>` | 参数是指定每个周期包含的天数，类型为 INT。若为负数或 0，返回 NULL；若未指定，默认周期为 1 天。 |
+| `<origin>` | 参数是周期计算的起始基准时间，支持 date/datetime 类型。若未指定，默认值为 0001-01-01
00:00:00；若输入无效格式，返回 NULL。 |
## 返回值
-返回最近向下取整时刻的日期。
+返回的是一个日期或时间值，表示将输入值向下舍入到指定天数周期的结果。
+
+若输入有效，返回与 datetime 类型一致的取整结果：
+
+`<date_or_time_expr>` 与 `<origin>` 输入都 DATE 类型时，返回 DATE 类型, 否则返回 DATETIME 类型.
+
+
+特殊情况：
+
+- 任何参数为 NULL 时，返回 NULL；
+- 若 period 为负数或 0，返回错误
+- 带有 scale 输入的符合日期时间，返回值带有 scale 且全部小数为 0
+- 若 `<origin>` 日期时间在 `<period>` 之后，也会按照上述公式计算，不过周期 k 为负数。
## 举例
```sql
+---五天为一周期向下取整
select day_floor("2023-07-13 22:28:18", 5);
-```
-```text
++-------------------------------------+
+| day_floor("2023-07-13 22:28:18", 5) |
++-------------------------------------+
+| 2023-07-10 00:00:00 |
++-------------------------------------+
+
+
+---带有 scale 输入的符合日期时间，返回值带有 scale 且全部小数为 0
+mysql> select day_floor("2023-07-13 22:28:18.123", 5);
++-----------------------------------------+
+| day_floor("2023-07-13 22:28:18.123", 5) |
++-----------------------------------------+
+| 2023-07-10 00:00:00.000 |
++-----------------------------------------+
+
+
+---输入参数不带有周期，默认一天为一周期
+select day_floor("2023-07-13 22:28:18");
++----------------------------------+
+| day_floor("2023-07-13 22:28:18") |
++----------------------------------+
+| 2023-07-13 00:00:00 |
++----------------------------------+
+
+---指定周期为 7 天（1 周），自定义基准时间为 2023-01-01 00:00:00
+select day_floor("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00");
++------------------------------------------------------------+
+| day_floor("2023-07-13 22:28:18", 7, "2023-01-01 00:00:00") |
++------------------------------------------------------------+
+| 2023-07-09 00:00:00 |
++------------------------------------------------------------+
+
+---开始时间恰好在一个周期开始，则返回输入日期时间
+select day_floor("2023-07-09 00:00:00", 7, "2023-01-01 00:00:00");
+------------------------------------------------------------+
-| day_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) |
+| day_floor("2023-07-09 00:00:00", 7, "2023-01-01 00:00:00") |
+------------------------------------------------------------+
-| 2023-07-12 00:00:00 |
+| 2023-07-09 00:00:00 |
+------------------------------------------------------------+
+
+---输入为 DATE 类型，周期为 3 天
+select day_floor(cast("2023-07-13" as date), 3);
++------------------------------------------+
+| day_floor(cast("2023-07-13" as date), 3) |
++------------------------------------------+
+| 2023-07-11 |
++------------------------------------------+
+
+--- 若 <origin> 日期时间在 <period> 之后，也会按照上述公式计算，不过周期 k 为负数。
+select day_floor('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00');
++----------------------------------------------------------------+
+| day_floor('2023-07-13 19:30:00.123', 4, '2028-07-14 08:00:00') |
++----------------------------------------------------------------+
+| 2023-07-13 08:00:00.000 |
++----------------------------------------------------------------+
+
+---周期为负数，返回错误
+select day_floor("2023-07-13 22:28:18", -2);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
day_floor of 2023-07-13 22:28:18, -2 out of range
+
+---任意参数为 NULL ，返回 NULL
+select day_floor(NULL, 5, "2023-01-01");
++----------------------------------+
+| day_floor(NULL, 5, "2023-01-01") |
++----------------------------------+
+| NULL |
++----------------------------------+
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
index 0de896be0d6..0877e613b85 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day.md
@@ -7,7 +7,9 @@
## 描述
-获得日期中的天信息，返回值范围从 1-31。
+DAY 函数用于提取日期或时间表达式中的 “日” 部分，返回值为整数，范围从 1 到 31（具体取决于月份和年份）。
+
+该函数与 mysql 中的 [day
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_day)
行为一致
## 别名
@@ -16,29 +18,52 @@
## 语法
```sql
-DAY(<dt>)
+DAY(<date_or_time_expr>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | 合法的日期表达式 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime 类型,具体 datetime 和 date
格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)|
## 返回值
-返回日期中的天信息
+返回日期中 “日” 的整数信息（1-31）。
+
+特殊情况：
+
+若 `dt` 为 NULL，返回 NULL；
## 举例
+
```sql
+
+--从 DATE 类型中提取日
select day('1987-01-31');
-```
-```text
+----------------------------+
| day('1987-01-31 00:00:00') |
+----------------------------+
| 31 |
+----------------------------+
+
+---从 DATETIME 类型中提取日（忽略时间部分）
+select day('2023-07-13 22:28:18');
+
++----------------------------+
+| day('2023-07-13 22:28:18') |
++----------------------------+
+| 13 |
++----------------------------+
+
+---输入为 NULL
+select day(NULL);
+
++-----------+
+| day(NULL) |
++-----------+
+| NULL |
++-----------+
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
index ee7dd26326a..b1dbc16a6ab 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayname.md
@@ -7,34 +7,58 @@
## 描述
-计算日期表达式对应的日期名字。
+DAYNAME 函数用于计算日期或时间表达式对应的星期名称（如“Tuesday” 等），返回值为字符串类型。
+
+该函数与 mysql 中的 [dayname
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_dayname)
行为一致
## 语法
```sql
-DAYNAME(<dt>)
+DAYNAME(<date_or_time_expr>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | 需要被计算的日期表达式 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime 类型和符合日期时间格式的字符串,具体
datetime 和 date 格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## 返回值
-返回日期表达式对应的日期名字。
+返回日期对应的星期名称（字符串类型）
+
+特殊情况：
+
+- 若 `date_or_time_expr` 为 NULL，返回 NULL；
## 举例
```sql
+
+---计算 DATETIME 类型对应的星期名称
select dayname('2007-02-03 00:00:00');
-```
-```text
+--------------------------------+
| dayname('2007-02-03 00:00:00') |
+--------------------------------+
| Saturday |
+--------------------------------+
+
+---计算 DATE 类型对应的星期名称
+
+select dayname('2023-10-01');
++-----------------------+
+| dayname('2023-10-01') |
++-----------------------+
+| Sunday |
++-----------------------+
+
+
+---参数为 NULL，返回 NULL
+select dayname(NULL);
++---------------+
+| dayname(NULL) |
++---------------+
+| NULL |
++---------------+
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
index 661651b1e6a..be03d024fca 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md
@@ -7,50 +7,67 @@
## 描述
-返回日期的工作日索引值，即星期日为 1，星期一为 2，星期六为 7。
+DAYOFWEEK 函数用于返回日期或时间表达式对应的星期索引值，遵循星期日为 1，星期一为 2，……，星期六为 7 的规则。
+
+该函数与 mysql 中的 [dayofweek
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_dayofweek)
行为一致
## 别名
-- DOW
+- DOW()
## 语法
```sql
-DAYOFWEEK(<dt>)
+DAYOFWEEK(<date_or_time_expr>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | 需要被计算的日期表达式 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime 类型,具体 datetime 和 date
格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## 返回值
-返回日期的工作日索引值。
+返回一个整数，表示日期对应的星期索引值（1-7，其中 1 代表星期日，7 代表星期六）。
+
+特殊情况：
+
+若 `<date_or_time_expr>` 为 NULL，返回 NULL；
## 举例
```sql
+---计算 date 类型的星期索引值
select dayofweek('2019-06-25');
-```
-```text
+----------------------------------+
| dayofweek('2019-06-25 00:00:00') |
+----------------------------------+
| 3 |
+----------------------------------+
-```text
-```sql
-select dayofweek(cast(20190625 as date));
-```
+---计算 datetime 类型的星期索引值
+select dayofweek('2019-06-25 15:30:45');
+
++----------------------------------+
+| dayofweek('2019-06-25 15:30:45') |
++----------------------------------+
+| 3 |
++----------------------------------+
+---星期日的索引
+select dayofweek('2024-02-18');
++-------------------------+
+| dayofweek('2024-02-18') |
++-------------------------+
+| 1 |
++-------------------------+
-```text
-+-----------------------------------+
-| dayofweek(CAST(20190625 AS DATE)) |
-+-----------------------------------+
-| 3 |
-+-----------------------------------+
+---输入日期时间为 NULL，返回 NULL
+select dayofweek(NULL);
++-----------------+
+| dayofweek(NULL) |
++-----------------+
+| NULL |
++-----------------+
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
index c849515e1ca..6cfe52054df 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md
@@ -7,7 +7,10 @@
## 描述
-获得日期中对应当年中的哪一天。
+DAYOFYEAR 函数用于计算日期或时间表达式对应的当年中天数，即该日期是当年的第几天。返回值为整数，范围从 1（1 月 1 日）到 366（闰年 12
月 31 日）。
+
+该函数与 mysql 中的 [dayofyear
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_dayofyear)
行为一致
+
## 别名
@@ -16,29 +19,58 @@
## 语法
```sql
-DAYOFYEAR(<dt>)
+DAYOFYEAR(<date_or_time_expr>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | 需要被计算的日期表达式 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime 类型,具体 datetime 和 date
格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## 返回值
-返回日期中对应当年中的哪一天。
+返回一个整数，表示日期在当年中的天数（1-366）,类型为 SMALLINT。
+
+特殊情况：
+
+- 若 <date_or_time_expr> 为 NULL，返回 NULL；
+- 对于闰年的 2 月 29 日，会正确计算为当年的第 60 天。
## 举例
```sql
+
+---提取 datetime 类型中的一年中的天数
select dayofyear('2007-02-03 00:00:00');
-```
-```text
+----------------------------------+
| dayofyear('2007-02-03 00:00:00') |
+----------------------------------+
| 34 |
+----------------------------------+
+
+---提取 date 类型中的天数
+select dayofyear('2023-12-31');
++-------------------------+
+| dayofyear('2023-12-31') |
++-------------------------+
+| 365 |
++-------------------------+
+
+---计算闰年中的天数
+select dayofyear('2024-12-31');
++-------------------------+
+| dayofyear('2024-12-31') |
++-------------------------+
+| 366 |
++-------------------------+
+
+---输入为 NULL ,返回 NULL
+select dayofyear(NULL);
++-----------------+
+| dayofyear(NULL) |
++-----------------+
+| NULL |
++-----------------+
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
index 4869212a05e..421392fc971 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md
@@ -7,43 +7,100 @@
## 描述
-`extract`
函数用于从日期或时间值中提取指定的部分，如年份、月份、日、小时、分钟、秒等。该函数常用于从日期时间字段中提取具体的时间组件进行计算、比较或展示。
+`EXTRACT` 函数用于从日期或时间值中提取指定的时间组件，如年份、月份,周、日、小时、分钟、秒等。该函数可精确获取日期时间中的特定部分.
+
+该函数与 mysql 中的 [extract
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_extract)
行为基本一致，不同的是，doris 目前暂不支持联合单位输入，如:
+
+```sql
+mysql> SELECT EXTRACT(YEAR_MONTH FROM '2019-07-02 01:02:03');
+ -> 201907
+```
+
## 语法
-`EXTRACT(<unit> FROM <datetime>)`
+`EXTRACT(<unit> FROM <date_or_time_expr>)`
## 参数
| 参数 | 说明 |
| -- | -- |
-| `unit` | 提取 DATETIME 某个指定单位的值。单位可以为 year, month, day, hour, minute, second,
microsecond, dayofyear(doy), dayofweek(dow) |
-| `datetime` | 参数是合法的日期表达式 |
+| `<unit>` | 提取 DATETIME 某个指定单位的值。单位可以为 year, month, week, day, hour, minute,
second 或者 microsecond |
+| `<datetime_or_time_expr>` | 参数是合法的日期表达式，支持输入 date/datetime
类型和符合日期时间格式的字符串,具体 datetime 和 date 格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
## 返回值
-返回的是提取出的日期或时间的某个部分（如整数），具体的部分取决于提取的单位。
+返回的是提取出的日期或时间的某个部分,类型为 INT，具体的部分取决于提取的单位。
+
+week 单位的取值范围为 0-53，计算规则如下：
+
+- 以 星期日为一周的第一天。
+- 当年的第一个星期日所在的周为第 1 周。
+- 在第一个星期日之前的日期属于第 0 周。
+单位为 year, month, day, hour, minute, second,microsecond 时，返回日期时间中对应的单位数值.
+
+单位为 quarter 时，1-3 月返回1，4-6 月返回2， 7-9 月返回3，10-12 返回4.
+
+特殊情况：
+
+若 <date_or_time_expr> 为 NULL，返回 NULL。
+若 <unit> 为不支持单位，报错
## 举例
```sql
+
+---提取日期时间中的 year, month, day, hour, minute, second,microsecond 时间组件
select extract(year from '2022-09-22 17:01:30') as year,
extract(month from '2022-09-22 17:01:30') as month,
extract(day from '2022-09-22 17:01:30') as day,
extract(hour from '2022-09-22 17:01:30') as hour,
extract(minute from '2022-09-22 17:01:30') as minute,
extract(second from '2022-09-22 17:01:30') as second,
-extract(microsecond from cast('2022-09-22 17:01:30.000123' as datetimev2(6)))
as microsecond,
-extract(dayofyear FROM '2022-09-22 17:01:30') as dayofyear,
-extract(doy FROM '2022-09-22 17:01:30') as dayofyear_alias,
-extract(dayofweek FROM '2022-09-22 17:01:30') as dayofweek,
-extract(dow FROM '2022-09-22 17:01:30') as dayofweek_alias;
-```
+extract(microsecond from cast('2022-09-22 17:01:30.000123' as datetime(6))) as
microsecond;
+
++------+-------+------+------+--------+--------+-------------+
+| year | month | day | hour | minute | second | microsecond |
++------+-------+------+------+--------+--------+-------------+
+| 2022 | 9 | 22 | 17 | 1 | 30 | 123 |
++------+-------+------+------+--------+--------+-------------+
+
+---提取日期时间中的 quarter
+
+mysql> select extract(quarter from '2023-05-15') as quarter;
+
++---------+
+| quarter |
++---------+
+| 2 |
++---------+
+
+---提取对应日期的周数，因为 2024 年的第一个周日在 1 月 7 日，所以 01-07 之前都返回0
+select extract(week from '2024-01-06') as week;
++------+
+| week |
++------+
+| 0 |
++------+
+
+--- 1 月 7 日为第一个周日，返回 1
+select extract(week from '2024-01-07') as week;
++------+
+| week |
++------+
+| 1 |
++------+
+
+---在这个规则下，2024 年的周数只有 0-52
+select extract(week from '2024-12-31') as week;
++------+
+| week |
++------+
+| 52 |
++------+
+
+---输入单位不存在，报错
+select extract(uint from '2024-01-07') as week;
-```text
-+------+-------+------+------+--------+--------+-------------+-----------+-----------------+-----------+-----------------+
-| year | month | day | hour | minute | second | microsecond | dayofyear |
dayofyear_alias | dayofweek | dayofweek_alias |
-+------+-------+------+------+--------+--------+-------------+-----------+-----------------+-----------+-----------------+
-| 2022 | 9 | 22 | 17 | 1 | 30 | 123 | 265 |
265 | 5 | 5 |
-+------+-------+------+------+--------+--------+-------------+-----------+-----------------+-----------+-----------------+
+ERROR 1105 (HY000): errCode = 2, detailMessage = Can not found function 'uint'
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
index 3d3decfe77a..87724c09330 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md
@@ -7,36 +7,57 @@
## 描述
-给定一个天数，返回一个 DATE。
+FROM_DAYS 函数用于将一个整数天数转换为对应的日期（DATE 类型）。该函数以 “公元 1 年 1 月 1 日” 为基准（即天数 0 对应
0000-01-01），计算从基准日期开始经过指定天数后的日期。
-- 注意，为了和 mysql 保持一致的行为，不存在 0000-02-29 这个日期。
+注意：为与 MySQL 保持行为一致，FROM_DAYS 函数不支持 “公元 1 年 2 月 29
日”（0000-02-29），即使理论上该年份符合闰年规则，也会自动跳过该日期。
+历史日期限制：该函数基于公历（格里高利历）扩展历法计算，不适用于 1582 年公历推行之前的日期（此时实际使用的是儒略历），可能导致结果与历史真实日期偏差。
+
+该函数与 mysql 中的 [from_days
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_from-days)
行为一致
## 语法
```sql
-FROM_DAYS(<dt>)
+FROM_DAYS(<days>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | 天数 |
+| `<days>` | 输入的天数，为 `INT` 类型 |
## 返回值
-返回对应天数的日期。
+返回值为 DATE 类型，格式为 YYYY-MM-DD，表示从基准日期（0000-01-01）开始经过 days 天后的日期。
+若 days 为负数，返回错误。
+若 days 超出有效日期范围（通常为 1 到 3652424，对应约公元 10000 年），返回错误
## 举例
```sql
+
+---从基准日期开始计算天数
select from_days(730669),from_days(5),from_days(59), from_days(60);
-```
-```text
+-------------------+--------------+---------------+---------------+
| from_days(730669) | from_days(5) | from_days(59) | from_days(60) |
+-------------------+--------------+---------------+---------------+
| 2000-07-03 | 0000-01-05 | 0000-02-28 | 0000-03-01 |
+-------------------+--------------+---------------+---------------+
+
+---输入参数为负数，返回错误
+select from_days(-60);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_days of -60 out of range
+
+---输入 NULL ,返回 NULL
+select from_days(NULL);
++-----------------+
+| from_days(NULL) |
++-----------------+
+| NULL |
++-----------------+
+
+---若 days 超出有效日期范围（通常为 1 到 3652424，对应约公元 10000 年），返回错误
+select from_days(99999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_days of 99999999 out of range
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
index 13525e4a8f1..b7d8c9b87e5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md
@@ -7,6 +7,13 @@
## 描述
将 ISO8601 格式的日期表达式转化为 date 类型的日期表达式。
+符合 ISO 8601 标准的日期字符串，支持的格式包括：
+- YYYY：仅年份（返回该年 1 月 1 日）
+- YYYY-MM：年月（返回该月 1 日）
+- YYYY-DDD：年 + 年中的天数（DDD 范围 1-366，如 0000-059 表示 0000 年第 59 天）
+- YYYY-WWW：年 + 周数（WWW 范围 1-53，返回该周的周一）
+- YYYY-WWW-D：年 + 周数 + 周内天数（D 范围 1-7，1 表示周一，7 表示周日）
+- 在该格式中，一年的第一周必须包含该周的星期四，不然算作上一年的周
## 语法
@@ -18,22 +25,76 @@ from_iso8601_date(<dt>)
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | ISO8601 格式的日期 |
+| `<date>` | ISO8601 格式的日期,为字符串类型 |
## 返回值
- date 类型的日期表达式。
+返回 DATE 类型，格式为 YYYY-MM-DD，表示解析后的具体日期。
+- 若输入格式无，返回错误
+- 输入 NULL，返回 NULL
## 举例
```sql
-SELECT
from_iso8601_date('0000-01'),from_iso8601_date('0000-W01'),from_iso8601_date('0000-059');
-```
+-- 解析不同ISO 8601格式的日期字符串
+select
+ from_iso8601_date('2023') as year_only,
+ from_iso8601_date('2023-10') as year_month,
+ from_iso8601_date('2023-10-05') as full_date;
+
++------------+------------+------------+
+| year_only | year_month | full_date |
++------------+------------+------------+
+| 2023-01-01 | 2023-10-01 | 2023-10-05 |
++------------+------------+------------+
+
+-- 解析“年-天数”格式
+select
+ from_iso8601_date('2021-001') as day_1,
+ from_iso8601_date('2021-059') as day_59,
+ from_iso8601_date('2021-060') as day_60,
+ from_iso8601_date('2024-366') as day_366;
+
++------------+------------+------------+------------+
+| day_1 | day_59 | day_60 | day_366 |
++------------+------------+------------+------------+
+| 0000-01-01 | 0000-02-28 | 0000-03-01 | 2024-12-31 |
++------------+------------+------------+------------+
+
+-- 解析“YYY-MMM-D”格式（每周以周一为第一天）,因为0522-01-01 才是周四，所以第一周之前的都会返回 0521 的年份
+select from_iso8601_date('0522-W01-1') as week_1;
++------------+
+| week_1 |
++------------+
+| 0521-12-29 |
++------------+
+1 row in set (0.02 sec)
-```text
-+------------------------------+-------------------------------+-------------------------------+
-| from_iso8601_date('0000-01') | from_iso8601_date('0000-W01') |
from_iso8601_date('0000-059') |
-+------------------------------+-------------------------------+-------------------------------+
-| 0000-01-01 | 0000-01-03 | 0000-02-28
|
-+------------------------------+-------------------------------+-------------------------------+
-```
\ No newline at end of file
+select from_iso8601_date('0522-W01-4') as week_4;
++------------+
+| week_4 |
++------------+
+| 0522-01-01 |
++------------+
+
+---YYY-MMM格式，第一周的周一在521年
+select from_iso8601_date('0522-W01') as week_1;
+
++------------+
+| week_1 |
++------------+
+| 0521-12-29 |
++------------+
+
+---格式错误，返回错误
+select from_iso8601_date('2023-10-01T12:34:10');
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INVALID_ARGUMENT]Operation from_iso8601_date of
2023-10-01T12:34:10 is invalid
+
+---输入 NULL
+select from_iso8601_date(NULL);
++-------------------------+
+| from_iso8601_date(NULL) |
++-------------------------+
+| NULL |
++-------------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
index 0cd1a2bde48..379e0609c29 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md
@@ -5,7 +5,8 @@
}
---
## 描述
-函数将输入的 Unix 时间戳（以微秒为单位）转换为 `DATETIME` 类型的日期时间值。
+
+FROM_MICROSECOND 函数用于将 Unix 时间戳（以微秒为单位） 转换为 `DATETIME` 类型的日期时间值。Unix 时间戳的基准时间为
1970-01-01 00:00:00 UTC，该函数会将输入的微秒数转换为该基准时间之后对应的具体日期和时间（包含秒的小数部分，精确到微秒）。
## 语法
@@ -17,23 +18,59 @@ FROM_MICROSECOND(<unix_timestamp>)
| 参数 | 说明 |
|--------------------|-----------------------------------------------------|
-| `<unix_timestamp>` | 必填，输入的 Unix 时间戳，表示从 1970-01-01 00:00:00 UTC 开始的微秒数。 |
+| `<unix_timestamp>` | 输入的 Unix 时间戳，类型为整数（BIGINT），表示从 1970-01-01
00:00:00 UTC 开始计算的微秒数 |
## 返回值
-- 返回一个 DATETIME 类型的值，表示输入的 Unix 时间戳对应的日期时间。
-- 如果 `<unix_timestamp>` 为 NULL，函数返回 NULL。
-- 如果 `<unix_timestamp>` 超出有效范围，函数返回错误。
+
+返回一个 DATETIME 类型的值，表示UTC时区下的unix时间戳，转换为当前时区的时间的结果
+- 如果 <unix_timestamp> 为 NULL，函数返回 NULL。
+- 若输入 <unix_timestamp> 能转换为整数秒，那么结果返回日期时间不带有 scale，如果不能，则结果返回带有 scale
+- 如果 <unix_timestamp> 小于 0 ，返回错误
+- 若 返回日期时间超过最大时间 9999-12-31 23:59:59 ，则返回错误
## 举例
```sql
+
+---当前机器所在时区是东八区，所以返回的时间相较于 UTC 加八个小时
+SELECT FROM_MICROSECOND(0);
++----------------------------+
+| FROM_MICROSECOND(0) |
++----------------------------+
+| 1970-01-01 08:00:00.000000 |
++----------------------------+
+
+---将 1700000000000000 微秒加在基准时间后转换为的日期时间
SELECT FROM_MICROSECOND(1700000000000000);
-```
-```text
+------------------------------------+
| from_microsecond(1700000000000000) |
+------------------------------------+
| 2023-11-15 06:13:20 |
+------------------------------------+
+
+-- 时间戳包含非整数秒（1700000000 秒 + 123456 微秒）
+select from_microsecond(1700000000123456) as dt_with_micro;
+
++----------------------------+
+| dt_with_micro |
++----------------------------+
+| 2023-11-15 06:13:20.123456 |
++----------------------------+
+
+---输入负数，返回错误
+ select from_microsecond(-1);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_microsecond of -1 out of range
+
+---输入 NULL，返回 NULL
+select from_microsecond(NULL);
++------------------------+
+| from_microsecond(NULL) |
++------------------------+
+| NULL |
++------------------------+
+
+---超过最大时间范围 9999-12-31 23:59:59 ，返回错误
+select from_microsecond(999999999999999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_microsecond of 999999999999999999 out of range
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
index a93e575038f..b7c4a1a2a13 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-millisecond.md
@@ -6,7 +6,7 @@
---
## 描述
-函数将输入的 Unix 时间戳（以毫秒为单位）转换为 `DATETIME` 类型的日期时间值。
+FROM_MILLISECOND 函数用于将 Unix 时间戳（以毫秒为单位） 转换为 DATETIME 类型的日期时间值。Unix 时间戳的基准时间为
1970-01-01 00:00:00 UTC，该函数会将输入的毫秒数转换为该基准时间之后对应的具体日期和时间（精确到毫秒）。
## 语法
@@ -18,25 +18,59 @@ FROM_MILLISECOND(<millisecond>)
| 参数 | 说明 |
|-----------------|-----------------------------------------------------|
-| `<millisecond>` | 必填，输入的 Unix 时间戳，表示从 1970-01-01 00:00:00 UTC 开始的毫秒数。 |
+| `<millisecond>` | 输入的 Unix 时间戳，类型为整数（BIGINT），表示从 1970-01-01 00:00:00 UTC
开始计算的毫秒数。 |
## 返回值
-- 返回一个 DATETIME 类型的值，表示输入的 Unix 时间戳对应的日期时间。
-- 如果 <millisecond> 为 NULL，函数返回 NULL。
-- 如果 <millisecond> 超出有效范围，函数返回错误。
+返回一个 DATETIME 类型的值，表示输入的 UTC时区下的unix时间戳，转换为当前时区的时间的结果
+- 如果 millisecond 为 NULL，函数返回 NULL。
+- 如果 millisecond 超出有效范围 ( 结果日期时间超过了 9999-12-31 23:59:59 ) ，函数返回错误。
+- 若输入 millisecond 能转换为整数秒，那么结果返回日期时间不带有 scale，如果不能，则结果返回带有 scale
+- 输入为负数，结果返回错误
## 举例
-
```sql
+
+----因为当前机器所在时区为东八区，所以返回的时间相较于 UTC 会加八个小时
+SELECT FROM_MILLISECOND(0);
++-------------------------+
+| FROM_MILLISECOND(0) |
++-------------------------+
+| 1970-01-01 08:00:00.000 |
++-------------------------+
+
+-- 将 1700000000000 毫秒转换为日期时间
SELECT FROM_MILLISECOND(1700000000000);
-```
-```text
+---------------------------------+
| from_millisecond(1700000000000) |
+---------------------------------+
| 2023-11-15 06:13:20 |
+---------------------------------+
+
+-- 时间戳包含非零毫秒（1700000000 秒 + 123 毫秒）
+select from_millisecond(1700000000123) as dt_with_milli;
+
++----------------------------+
+| dt_with_milli |
++----------------------------+
+| 2023-11-15 06:13:20.123000 |
++----------------------------+
+
+---输入为 NULL ，结果返回 NULL
+select from_millisecond(NULL);
++------------------------+
+| from_millisecond(NULL) |
++------------------------+
+| NULL |
++------------------------+
+
+---输入为负数，结果返回错误
+ select from_millisecond(-1);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_millisecond of -1 out of range
+
+--结果超过最大日期，返回错误
+select from_millisecond(999999999999999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_millisecond of 999999999999999999 out of range
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
index 36c19940250..a7a4e6a5415 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-second.md
@@ -6,7 +6,7 @@
---
## 描述
-函数将输入的 Unix 时间戳（以秒为单位）转换为 `DATETIME` 类型的日期时间值。
+FROM_SECOND 函数用于将 Unix 时间戳（以秒为单位） 转换为 DATETIME 类型的日期时间值。Unix 时间戳的基准时间为
1970-01-01 00:00:00 UTC，该函数会将输入的秒数转换为该基准时间之后对应的具体日期和时间（精确到秒）。
## 语法
@@ -18,24 +18,49 @@ FROM_SECOND(<unix_timestamp>)
| 参数 | 说明 |
|--------------------|----------------------------------------------------|
-| `<unix_timestamp>` | 必填，输入的 Unix 时间戳，表示从 1970-01-01 00:00:00 UTC 开始的秒数。 |
+| `<unix_timestamp>` | 输入的 Unix 时间戳，类型为整数（BIGINT），表示从 1970-01-01 00:00:00 UTC
开始计算的秒数。 |
## 返回值
-- 返回一个 DATETIME 类型的值，表示输入的 Unix 时间戳对应的日期时间。
-- 如果 `<unix_timestamp>` 为 NULL，函数返回 NULL。
-- 如果 `<unix_timestamp>` 超出有效范围，函数返回错误。
+- 返回一个 DATETIME 类型的值，表示输入的UTC时区下的unix时间戳，转换为当前时区的时间的结果
+- 如果 <unix_timestamp> 为 NULL，函数返回 NULL。
+- 如果 <unix_timestamp> 超出有效范围( 结果日期时间超过了 9999-12-31 23:59:59 ) ，函数返回错误。
+- 输入秒数为负数，函数返回错误
## 举例
```sql
+
+----因为当前机器所在时区为东八区，所以返回的时间相较于 UTC 会加八个小时
+ SELECT FROM_SECOND(0);
++---------------------+
+| FROM_SECOND(0) |
++---------------------+
+| 1970-01-01 08:00:00 |
++---------------------+
+
+---将 1700000000 秒转换为日期时间
SELECT FROM_SECOND(1700000000);
-```
-```text
+-------------------------+
| from_second(1700000000) |
+-------------------------+
| 2023-11-15 06:13:20 |
+-------------------------+
+
+---结果超过了最大日期范围，返回错误
+select from_second(999999999999999);
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INTERNAL_ERROR]The function from_second Argument value is out of
DateTime range
+
+---输入参数为 NULL, 返回 NULL
+select from_second(NULL);
++-------------------+
+| from_second(NULL) |
++-------------------+
+| NULL |
++-------------------+
+
+--输入参数为负数，结果返回错误
+ select from_second(-1);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation
from_second of -1 out of range
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
index 4bfdaf4b896..d33aac7f429 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md
@@ -7,10 +7,11 @@
## 描述
-将 unix 时间戳转化为对应的 time 格式。
+FROM_UNIXTIME 函数用于将 Unix 时间戳（以秒为单位） 转换为指定格式的日期时间字符串或 VARCHAR 类型值。Unix
时间戳的基准时间为 1970-01-01 00:00:00 UTC，函数会根据输入的时间戳和格式字符串，生成对应的日期时间表示。
+
+
+该函数与 mysql 中的 [from_unixtime
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_from-unixtime)
行为一致
-特殊情况：
-- 支持的 `unix_timestamp` 输入范围为 `[0, 253402271999.999999]`，超出范围的值将返回 `NULL`。
## 语法
@@ -22,16 +23,30 @@ FROM_UNIXTIME(<unix_timestamp> [, <string_format>])
| 参数 | 说明 |
| -- | -- |
-| `<unix_timestamp>` | unix 时间戳 |
-| `<string_format>` | format 格式，默认为 %Y-%m-%d %H:%i:%s|
+| `<unix_timestamp>` | 输入的 Unix 时间戳，类型为整数 BIGINT，表示从 1970-01-01 00:00:00 UTC
开始的秒数 |
+| `<string_format>` | format 格式,支持类型 varchar 和string，默认为 %Y-%m-%d %H:%i:%s,
具体格式请查看 [date-format](./date-format)|
## 返回值
-返回指定格式的日期。
+返回指定格式的日期,类型为 VARCHAR，返回的是UTC时区下的时间戳的时间戳转换为当前时区的时间。
+- 目前支持的 unix_timestamp 范围为 [0, 253402271999] 对应日期为 1970-01-01 00:00:00 至
9999-12-31 23:59:59，超出范围的 unix_timestamp 将返回 错误
+- 若 string_format 格式无效，返回不符合预期的字符串。
+- 若任意参数为 NULL ,则返回 NULL
+- 如果 string_format 超过 128 字符长度，返回错误
## 举例
-```
+```sql
+
+----因为当前时区为东八区，所以返回时间相较于 UTC 会加八个小时
+select from_unixtime(0);
++---------------------+
+| from_unixtime(0) |
++---------------------+
+| 1970-01-01 08:00:00 |
++---------------------+
+
+---默认格式 %Y-%m-%d %H:%i:%s 返回
mysql> select from_unixtime(1196440219);
+---------------------------+
| from_unixtime(1196440219) |
@@ -39,6 +54,7 @@ mysql> select from_unixtime(1196440219);
| 2007-12-01 00:30:19 |
+---------------------------+
+---指定 yyyy-MM-dd HH:mm:ss 格式返回
mysql> select from_unixtime(1196440219, 'yyyy-MM-dd HH:mm:ss');
+--------------------------------------------------+
| from_unixtime(1196440219, 'yyyy-MM-dd HH:mm:ss') |
@@ -46,14 +62,7 @@ mysql> select from_unixtime(1196440219, 'yyyy-MM-dd
HH:mm:ss');
| 2007-12-01 00:30:19 |
+--------------------------------------------------+
--- 最大支持时间
-mysql> select from_unixtime(253402271999.999999);
-+------------------------------------+
-| from_unixtime(253402271999.999999) |
-+------------------------------------+
-| 9999-12-31 23:59:59.999999 |
-+------------------------------------+
-
+---指定 %Y-%m-%d 只有日期格式返回
mysql> select from_unixtime(1196440219, '%Y-%m-%d');
+-----------------------------------------+
| from_unixtime(1196440219, '%Y-%m-%d') |
@@ -61,10 +70,36 @@ mysql> select from_unixtime(1196440219, '%Y-%m-%d');
| 2007-12-01 |
+-----------------------------------------+
+---指定 %Y-%m-%d %H:%i:%s 格式返回
mysql> select from_unixtime(1196440219, '%Y-%m-%d %H:%i:%s');
+--------------------------------------------------+
| from_unixtime(1196440219, '%Y-%m-%d %H:%i:%s') |
+--------------------------------------------------+
| 2007-12-01 00:30:19 |
+--------------------------------------------------+
+
+---超出最大范围， 返回错误
+select from_unixtime(253402281999);
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INVALID_ARGUMENT]Operation from_unixtime_new of 253402281999,
yyyy-MM-dd HH:mm:ss is invalid
+
+---输入字符串长度超出限制，报错
+select from_unixtime(32536799,repeat('a',129));
+ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.3)[INVALID_ARGUMENT]Operation from_unixtime_new of invalid or
oversized format is invalid
+
+---string-format 格式未引用任何时间值
+mysql> select from_unixtime(32536799,"gdaskpdp");
++------------------------------------+
+| from_unixtime(32536799,"gdaskpdp") |
++------------------------------------+
+| gdaskpdp |
++------------------------------------+
+
+---输入为 NULL，返回 NULL
+mysql> select from_unixtime(NULL);
++---------------------+
+| from_unixtime(NULL) |
++---------------------+
+| NULL |
++---------------------+
+
```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
