This is an automated email from the ASF dual-hosted git repository.
kassiez 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 f593f3628bc [Fix](docs)Sql function months_diff,seconds_diff,timediff
(#1822)
f593f3628bc is described below
commit f593f3628bcf4888f516ab6f9a09fa960c85cddb
Author: bingquanzhao <bingquan_z...@icloud.com>
AuthorDate: Fri Feb 7 16:38:25 2025 +0800
[Fix](docs)Sql function months_diff,seconds_diff,timediff (#1822)
## Versions
- [x] dev
- [x] 3.0
- [x] 2.1
- [x] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../date-time-functions/months-diff.md | 45 +++++++++++------
.../date-time-functions/seconds-diff.md | 2 +
.../date-time-functions/timediff.md | 56 ++++++++++----------
.../date-time-functions/months-diff.md | 39 +++++++++-----
.../date-time-functions/seconds-diff.md | 1 +
.../date-time-functions/timediff.md | 52 +++++++++----------
.../date-time-functions/months-diff.md | 39 +++++++++-----
.../date-time-functions/seconds-diff.md | 1 +
.../sql-functions/date-time-functions/timediff.md | 52 +++++++++----------
.../date-time-functions/months-diff.md | 39 +++++++++-----
.../date-time-functions/seconds-diff.md | 2 +-
.../date-time-functions/timediff.md | 52 +++++++++----------
.../date-time-functions/months-diff.md | 39 +++++++++-----
.../date-time-functions/seconds-diff.md | 1 +
.../date-time-functions/timediff.md | 54 ++++++++++----------
.../date-time-functions/months-diff.md | 45 +++++++++++------
.../date-time-functions/seconds-diff.md | 2 +
.../sql-functions/date-time-functions/timediff.md | 58 ++++++++++-----------
.../date-time-functions/months-diff.md | 45 +++++++++++------
.../date-time-functions/seconds-diff.md | 2 +
.../date-time-functions/timediff.md | 59 +++++++++++-----------
.../date-time-functions/months-diff.md | 45 +++++++++++------
.../date-time-functions/seconds-diff.md | 2 +
.../date-time-functions/timediff.md | 58 ++++++++++-----------
24 files changed, 445 insertions(+), 345 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
index d39a24d0995..24dea4b7450 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
-### description
-#### Syntax
+## Description
+The `MONTHS_DIFF` function calculates the number of complete months between
two dates. It accepts two date arguments and returns the difference in months
as an integer.
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+## Syntax
-The difference between the start time and the end time is months
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
-### example
+## Parameters
-```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
+| 参数 | 说明
|
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<enddate>` | The ending date, representing the later date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+| `<startdate>` | The starting date, representing the earlier date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+
+## Return Value
-### keywords
+returns the number of months resulting from `<enddate>` minus `<startdate>`
+- When either `<enddate>` or `<startdate>` is NULL, or both are NULL, it
returns NULL
+
+
+## Example
+
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
+```
- months_diff
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
index 798bbd90293..8338eaa1d9f 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## Description
+
The function calculates the time difference between two datetime values and
returns the difference in seconds.
## Syntax
@@ -32,6 +33,7 @@ The function calculates the time difference between two
datetime values and retu
```sql
SECONDS_DIFF(<end_datetime>, <start_datetime>)
```
+
## Parameters
| Parameter | Description
|
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
index 156fb49de73..e21dcde2767 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
-### Description
-#### Syntax
+## Description
+The `TIMEDIFF` function calculates the difference between two datetime values.
This function accepts two arguments and returns the difference as a `TIME` type.
-`TIME TIMEDIFF (DATETIME expr1, DATETIME expr2)`
+## Syntax
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
-TIMEDIFF returns the difference between two DATETIMEs
+## Parameters
-The TIMEDIFF function returns the result of expr1 - expr2 expressed as a time
value, with a return value of TIME type
+| Parameter | Description |
+|--------------------|------------------------------|
+| `<end_datetime>` | The ending datetime value. |
+| `<start_datetime>` | The starting datetime value. |
-The results are limited to TIME values ranging from - 838:59:59 to 838:59:59.
+## Return Value
+Returns a `TIME` type value representing the difference between the two inputs:
+- If `<end_datetime>` is later than `<start_datetime>`, it returns a positive
time difference.
+- If `<end_datetime>` is earlier than `<start_datetime>`, it returns a
negative time difference.
+- If `<end_datetime>` and `<start_datetime>` are equal, it returns `00:00:00`.
+- If `<end_datetime>` or `<start_datetime>` is `NULL`, the function returns
`NULL`.
+- If `<end_datetime>` or `<start_datetime>` is an invalid datetime value
(e.g., `0000-00-00 00:00:00`), the function returns `NULL`.
-#### example
+## Example
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
```
-### keywords
- TIMEDIFF
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
index 13f76ec0d86..4bf81c43a6d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
## 描述
+`MONTHS_DIFF` 函数用于计算两个日期之间相差的月份数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差月份数。
+
## 语法
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|---------------|---------------------------------------------------------|
+| `<enddate>` | 结束日期，表示计算差值时的较晚日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+| `<startdate>` | 开始日期，表示计算差值时的较早日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+
+## 返回值
+
+返回 `<enddate>` 减去 `<startdate>` 所得月份数
+- 当`<enddate>`与`<startdate>`任意为NULL，或者两者都为NULL时，返回NULL
-开始时间到结束时间相差几个月
## 举例
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
-
-### keywords
- months_diff
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
\ 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/seconds-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
index 0bffe6a3946..4d5deea53ec 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## 描述
+
函数用于计算两个日期时间值之间的时间差，以秒为单位返回差值。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
index 4f54960da56..6bc88a2e7b8 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
## 描述
+`TIMEDIFF` 函数用于计算两个日期时间值之间的差值。该函数接受两个参数，并返回其差值，结果为 `TIME` 类型。
+
## 语法
-`TIME TIMEDIFF(DATETIME expr1, DATETIME expr2)`
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
+## 参数
-TIMEDIFF返回两个DATETIME之间的差值
+| 参数 | 说明 |
+|-------------------|-------------------------------|
+| `<end_datetime>` | 结束的时间或日期时间值 |
+| `<start_datetime>` | 开始的时间或日期时间值 |
-TIMEDIFF函数返回表示为时间值的expr1 - expr2的结果，返回值为TIME类型
+## 返回值
+返回一个 `TIME` 类型的值，表示两个输入之间的时间差：
+- 当 `<end_datetime>` 晚于 `<start_datetime>` 时，返回正的时间差。
+- 当 `<end_datetime>` 早于 `<start_datetime>` 时，返回负的时间差。
+- 当 `<end_datetime>` 和 `<start_datetime>` 相等时，返回 `00:00:00`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为 `NULL`，函数返回 `NULL`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为非法时间或日期时间值（如 `0000-00-00
00:00:00`），函数返回 `NULL`。
## 举例
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
```
-
-### keywords
-
- TIMEDIFF
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
index 13f76ec0d86..4bf81c43a6d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
## 描述
+`MONTHS_DIFF` 函数用于计算两个日期之间相差的月份数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差月份数。
+
## 语法
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|---------------|---------------------------------------------------------|
+| `<enddate>` | 结束日期，表示计算差值时的较晚日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+| `<startdate>` | 开始日期，表示计算差值时的较早日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+
+## 返回值
+
+返回 `<enddate>` 减去 `<startdate>` 所得月份数
+- 当`<enddate>`与`<startdate>`任意为NULL，或者两者都为NULL时，返回NULL
-开始时间到结束时间相差几个月
## 举例
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
-
-### keywords
- months_diff
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
index 0bffe6a3946..4d5deea53ec 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## 描述
+
函数用于计算两个日期时间值之间的时间差，以秒为单位返回差值。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
index 4f54960da56..6bc88a2e7b8 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
## 描述
+`TIMEDIFF` 函数用于计算两个日期时间值之间的差值。该函数接受两个参数，并返回其差值，结果为 `TIME` 类型。
+
## 语法
-`TIME TIMEDIFF(DATETIME expr1, DATETIME expr2)`
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
+## 参数
-TIMEDIFF返回两个DATETIME之间的差值
+| 参数 | 说明 |
+|-------------------|-------------------------------|
+| `<end_datetime>` | 结束的时间或日期时间值 |
+| `<start_datetime>` | 开始的时间或日期时间值 |
-TIMEDIFF函数返回表示为时间值的expr1 - expr2的结果，返回值为TIME类型
+## 返回值
+返回一个 `TIME` 类型的值，表示两个输入之间的时间差：
+- 当 `<end_datetime>` 晚于 `<start_datetime>` 时，返回正的时间差。
+- 当 `<end_datetime>` 早于 `<start_datetime>` 时，返回负的时间差。
+- 当 `<end_datetime>` 和 `<start_datetime>` 相等时，返回 `00:00:00`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为 `NULL`，函数返回 `NULL`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为非法时间或日期时间值（如 `0000-00-00
00:00:00`），函数返回 `NULL`。
## 举例
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
```
-
-### keywords
-
- TIMEDIFF
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
index 13f76ec0d86..4bf81c43a6d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
## 描述
+`MONTHS_DIFF` 函数用于计算两个日期之间相差的月份数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差月份数。
+
## 语法
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|---------------|---------------------------------------------------------|
+| `<enddate>` | 结束日期，表示计算差值时的较晚日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+| `<startdate>` | 开始日期，表示计算差值时的较早日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+
+## 返回值
+
+返回 `<enddate>` 减去 `<startdate>` 所得月份数
+- 当`<enddate>`与`<startdate>`任意为NULL，或者两者都为NULL时，返回NULL
-开始时间到结束时间相差几个月
## 举例
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
-
-### keywords
- months_diff
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
index 0bffe6a3946..e0aa6d0ea4d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## 描述
+
函数用于计算两个日期时间值之间的时间差，以秒为单位返回差值。
@@ -58,5 +59,4 @@ SELECT SECONDS_DIFF('2025-01-23 12:35:56', '2025-01-23
12:34:56');
| seconds_diff(cast('2025-01-23 12:35:56' as DATETIMEV2(0)), cast('2025-01-23
12:34:56' as DATETIMEV2(0))) |
+----------------------------------------------------------------------------------------------------------+
|
60 |
-+----------------------------------------------------------------------------------------------------------+
```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
index 4f54960da56..6bc88a2e7b8 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
## 描述
+`TIMEDIFF` 函数用于计算两个日期时间值之间的差值。该函数接受两个参数，并返回其差值，结果为 `TIME` 类型。
+
## 语法
-`TIME TIMEDIFF(DATETIME expr1, DATETIME expr2)`
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
+## 参数
-TIMEDIFF返回两个DATETIME之间的差值
+| 参数 | 说明 |
+|-------------------|-------------------------------|
+| `<end_datetime>` | 结束的时间或日期时间值 |
+| `<start_datetime>` | 开始的时间或日期时间值 |
-TIMEDIFF函数返回表示为时间值的expr1 - expr2的结果，返回值为TIME类型
+## 返回值
+返回一个 `TIME` 类型的值，表示两个输入之间的时间差：
+- 当 `<end_datetime>` 晚于 `<start_datetime>` 时，返回正的时间差。
+- 当 `<end_datetime>` 早于 `<start_datetime>` 时，返回负的时间差。
+- 当 `<end_datetime>` 和 `<start_datetime>` 相等时，返回 `00:00:00`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为 `NULL`，函数返回 `NULL`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为非法时间或日期时间值（如 `0000-00-00
00:00:00`），函数返回 `NULL`。
## 举例
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
```
-
-### keywords
-
- TIMEDIFF
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
index 13f76ec0d86..4bf81c43a6d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
## 描述
+`MONTHS_DIFF` 函数用于计算两个日期之间相差的月份数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差月份数。
+
## 语法
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+|---------------|---------------------------------------------------------|
+| `<enddate>` | 结束日期，表示计算差值时的较晚日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+| `<startdate>` | 开始日期，表示计算差值时的较早日期。支持日期类型（如 `DATE`）或日期时间类型（如 `DATETIME`） |
+
+## 返回值
+
+返回 `<enddate>` 减去 `<startdate>` 所得月份数
+- 当`<enddate>`与`<startdate>`任意为NULL，或者两者都为NULL时，返回NULL
-开始时间到结束时间相差几个月
## 举例
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
-
-### keywords
- months_diff
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
index 0bffe6a3946..4d5deea53ec 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## 描述
+
函数用于计算两个日期时间值之间的时间差，以秒为单位返回差值。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
index 4f54960da56..9839a33ec97 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
## 描述
+`TIMEDIFF` 函数用于计算两个日期时间值之间的差值。该函数接受两个参数，并返回其差值，结果为 `TIME` 类型。
+
## 语法
-`TIME TIMEDIFF(DATETIME expr1, DATETIME expr2)`
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
+## 参数
-TIMEDIFF返回两个DATETIME之间的差值
+| 参数 | 说明 |
+|-------------------|-------------------------------|
+| `<end_datetime>` | 结束的时间或日期时间值 |
+| `<start_datetime>` | 开始的时间或日期时间值 |
-TIMEDIFF函数返回表示为时间值的expr1 - expr2的结果，返回值为TIME类型
+## 返回值
+返回一个 `TIME` 类型的值，表示两个输入之间的时间差：
+- 当 `<end_datetime>` 晚于 `<start_datetime>` 时，返回正的时间差。
+- 当 `<end_datetime>` 早于 `<start_datetime>` 时，返回负的时间差。
+- 当 `<end_datetime>` 和 `<start_datetime>` 相等时，返回 `00:00:00`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为 `NULL`，函数返回 `NULL`。
+- 如果 `<end_datetime>` 或 `<start_datetime>` 为非法时间或日期时间值（如 `0000-00-00
00:00:00`），函数返回 `NULL`。
## 举例
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
-```
-
-### keywords
- TIMEDIFF
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
b/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
index d39a24d0995..24dea4b7450 100644
---
a/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
+++
b/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
-### description
-#### Syntax
+## Description
+The `MONTHS_DIFF` function calculates the number of complete months between
two dates. It accepts two date arguments and returns the difference in months
as an integer.
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+## Syntax
-The difference between the start time and the end time is months
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
-### example
+## Parameters
-```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
+| 参数 | 说明
|
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<enddate>` | The ending date, representing the later date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+| `<startdate>` | The starting date, representing the earlier date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+
+## Return Value
-### keywords
+returns the number of months resulting from `<enddate>` minus `<startdate>`
+- When either `<enddate>` or `<startdate>` is NULL, or both are NULL, it
returns NULL
+
+
+## Example
+
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
+```
- months_diff
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
b/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
index ee2784f0c33..3a9658ac359 100644
---
a/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
+++
b/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## Description
+
The function calculates the time difference between two datetime values and
returns the difference in seconds.
## Syntax
@@ -32,6 +33,7 @@ The function calculates the time difference between two
datetime values and retu
```sql
SECONDS_DIFF(<end_datetime>, <start_datetime>)
```
+
## Parameters
| Parameter | Description
|
diff --git
a/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
b/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
index 156fb49de73..fd409fdfd93 100644
---
a/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
+++
b/versioned_docs/version-2.0/sql-manual/sql-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
-### Description
-#### Syntax
+## Description
+The `TIMEDIFF` function calculates the difference between two datetime values.
This function accepts two arguments and returns the difference as a `TIME` type.
-`TIME TIMEDIFF (DATETIME expr1, DATETIME expr2)`
+## Syntax
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
-TIMEDIFF returns the difference between two DATETIMEs
+## Parameters
-The TIMEDIFF function returns the result of expr1 - expr2 expressed as a time
value, with a return value of TIME type
+| Parameter | Description |
+|--------------------|------------------------------|
+| `<end_datetime>` | The ending datetime value. |
+| `<start_datetime>` | The starting datetime value. |
-The results are limited to TIME values ranging from - 838:59:59 to 838:59:59.
+## Return Value
+Returns a `TIME` type value representing the difference between the two inputs:
+- If `<end_datetime>` is later than `<start_datetime>`, it returns a positive
time difference.
+- If `<end_datetime>` is earlier than `<start_datetime>`, it returns a
negative time difference.
+- If `<end_datetime>` and `<start_datetime>` are equal, it returns `00:00:00`.
+- If `<end_datetime>` or `<start_datetime>` is `NULL`, the function returns
`NULL`.
+- If `<end_datetime>` or `<start_datetime>` is an invalid datetime value
(e.g., `0000-00-00 00:00:00`), the function returns `NULL`.
-#### example
+## Example
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
-```
-### keywords
- TIMEDIFF
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
index d39a24d0995..04674cff35a 100644
---
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
+++
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
-### description
-#### Syntax
+## Description
+The `MONTHS_DIFF` function calculates the number of complete months between
two dates. It accepts two date arguments and returns the difference in months
as an integer.
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+## Syntax
-The difference between the start time and the end time is months
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
-### example
+## Parameters
-```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
+| 参数 | 说明
|
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<enddate>` | The ending date, representing the later date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+| `<startdate>` | The starting date, representing the earlier date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+
+## Return Value
+
+returns the number of months resulting from `<enddate>` minus `<startdate>`
+- When either `<enddate>` or `<startdate>` is NULL, or both are NULL, it
returns NULL
-### keywords
- months_diff
+## Example
+
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
+```
+
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
diff --git
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
index ee2784f0c33..3a9658ac359 100644
---
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
+++
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## Description
+
The function calculates the time difference between two datetime values and
returns the difference in seconds.
## Syntax
@@ -32,6 +33,7 @@ The function calculates the time difference between two
datetime values and retu
```sql
SECONDS_DIFF(<end_datetime>, <start_datetime>)
```
+
## Parameters
| Parameter | Description
|
diff --git
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
index 156fb49de73..179e25c4bc0 100644
---
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
+++
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
@@ -24,42 +24,41 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
-### Description
-#### Syntax
+## Description
+The `TIMEDIFF` function calculates the difference between two datetime values.
This function accepts two arguments and returns the difference as a `TIME` type.
-`TIME TIMEDIFF (DATETIME expr1, DATETIME expr2)`
+## Syntax
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
-TIMEDIFF returns the difference between two DATETIMEs
-
-The TIMEDIFF function returns the result of expr1 - expr2 expressed as a time
value, with a return value of TIME type
-The results are limited to TIME values ranging from - 838:59:59 to 838:59:59.
+## Parameters
-#### example
+| Parameter | Description |
+|--------------------|------------------------------|
+| `<end_datetime>` | The ending datetime value. |
+| `<start_datetime>` | The starting datetime value. |
-```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
+## Return Value
+Returns a `TIME` type value representing the difference between the two inputs:
+- If `<end_datetime>` is later than `<start_datetime>`, it returns a positive
time difference.
+- If `<end_datetime>` is earlier than `<start_datetime>`, it returns a
negative time difference.
+- If `<end_datetime>` and `<start_datetime>` are equal, it returns `00:00:00`.
+- If `<end_datetime>` or `<start_datetime>` is `NULL`, the function returns
`NULL`.
+- If `<end_datetime>` or `<start_datetime>` is an invalid datetime value
(e.g., `0000-00-00 00:00:00`), the function returns `NULL`.
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
+## Example
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-### keywords
- TIMEDIFF
+
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
diff --git
a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
index d39a24d0995..04674cff35a 100644
---
a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
+++
b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/months-diff.md
@@ -24,25 +24,38 @@ specific language governing permissions and limitations
under the License.
-->
-## months_diff
-### description
-#### Syntax
+## Description
+The `MONTHS_DIFF` function calculates the number of complete months between
two dates. It accepts two date arguments and returns the difference in months
as an integer.
-`INT months_diff(DATETIME enddate, DATETIME startdate)`
+## Syntax
-The difference between the start time and the end time is months
+```sql
+MONTHS_DIFF(<enddate>, <startdate>)
+```
-### example
+## Parameters
-```
-mysql> select months_diff('2020-12-25','2020-10-25');
-+-----------------------------------------------------------+
-| months_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') |
-+-----------------------------------------------------------+
-| 2 |
-+-----------------------------------------------------------+
-```
+| 参数 | 说明
|
+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `<enddate>` | The ending date, representing the later date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+| `<startdate>` | The starting date, representing the earlier date in the
difference calculation. Supports `DATE` (e.g., `YYYY-MM-DD`) or `DATETIME`
(e.g., `YYYY-MM-DD HH:MM:SS`) types. |
+
+## Return Value
+
+returns the number of months resulting from `<enddate>` minus `<startdate>`
+- When either `<enddate>` or `<startdate>` is NULL, or both are NULL, it
returns NULL
-### keywords
- months_diff
+## Example
+
+```sql
+select months_diff('2020-12-25','2020-10-25'),months_diff('2020-10-25
10:00:00','2020-12-25 11:00:00');
+```
+
+```text
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+| months_diff(cast('2020-12-25' as DATETIMEV2(0)), cast('2020-10-25' as
DATETIMEV2(0))) | months_diff(cast('2020-10-25 10:00:00' as DATETIMEV2(0)),
cast('2020-12-25 11:00:00' as DATETIMEV2(0))) |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+|
2 |
-2 |
++---------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+
+```
diff --git
a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
index ee2784f0c33..3a9658ac359 100644
---
a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
+++
b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/seconds-diff.md
@@ -25,6 +25,7 @@ under the License.
-->
## Description
+
The function calculates the time difference between two datetime values and
returns the difference in seconds.
## Syntax
@@ -32,6 +33,7 @@ The function calculates the time difference between two
datetime values and retu
```sql
SECONDS_DIFF(<end_datetime>, <start_datetime>)
```
+
## Parameters
| Parameter | Description
|
diff --git
a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
index 156fb49de73..fd409fdfd93 100644
---
a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
+++
b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md
@@ -24,42 +24,40 @@ specific language governing permissions and limitations
under the License.
-->
-## timediff
-### Description
-#### Syntax
+## Description
+The `TIMEDIFF` function calculates the difference between two datetime values.
This function accepts two arguments and returns the difference as a `TIME` type.
-`TIME TIMEDIFF (DATETIME expr1, DATETIME expr2)`
+## Syntax
+```sql
+TIMEDIFF(<end_datetime>, <start_datetime>)
+```
-TIMEDIFF returns the difference between two DATETIMEs
+## Parameters
-The TIMEDIFF function returns the result of expr1 - expr2 expressed as a time
value, with a return value of TIME type
+| Parameter | Description |
+|--------------------|------------------------------|
+| `<end_datetime>` | The ending datetime value. |
+| `<start_datetime>` | The starting datetime value. |
-The results are limited to TIME values ranging from - 838:59:59 to 838:59:59.
+## Return Value
+Returns a `TIME` type value representing the difference between the two inputs:
+- If `<end_datetime>` is later than `<start_datetime>`, it returns a positive
time difference.
+- If `<end_datetime>` is earlier than `<start_datetime>`, it returns a
negative time difference.
+- If `<end_datetime>` and `<start_datetime>` are equal, it returns `00:00:00`.
+- If `<end_datetime>` or `<start_datetime>` is `NULL`, the function returns
`NULL`.
+- If `<end_datetime>` or `<start_datetime>` is an invalid datetime value
(e.g., `0000-00-00 00:00:00`), the function returns `NULL`.
-#### example
+## Example
+```sql
+SELECT TIMEDIFF('2024-07-20 16:59:30','2024-07-11 16:35:21');
```
-mysql> SELECT TIMEDIFF(now(),utc_timestamp());
-+----------------------------------+
-| timediff(now(), utc_timestamp()) |
-+----------------------------------+
-| 08:00:00 |
-+----------------------------------+
-
-mysql> SELECT TIMEDIFF('2019-07-11 16:59:30','2019-07-11 16:59:21');
-+--------------------------------------------------------+
-| timediff('2019-07-11 16:59:30', '2019-07-11 16:59:21') |
-+--------------------------------------------------------+
-| 00:00:09 |
-+--------------------------------------------------------+
-mysql> SELECT TIMEDIFF('2019-01-01 00:00:00', NULL);
-+---------------------------------------+
-| timediff('2019-01-01 00:00:00', NULL) |
-+---------------------------------------+
-| NULL |
-+---------------------------------------+
-```
-### keywords
- TIMEDIFF
+```text
++------------------------------------------------------------------------------------------------------+
+| timediff(cast('2024-07-20 16:59:30' as DATETIMEV2(0)), cast('2024-07-11
16:35:21' as DATETIMEV2(0))) |
++------------------------------------------------------------------------------------------------------+
+| 216:24:09
|
++------------------------------------------------------------------------------------------------------+
+```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org
For additional commands, e-mail: commits-h...@doris.apache.org
