Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Improve some datetime function desc #2091

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

[doc] Improve some datetime function desc #2091

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
610d09b
[doc] Merge json_parse_* docs into json_parse zh_doc
mklzl Jan 17, 2025
d02e03e
[doc] Fix syntax format for json_parse zh_doc
mklzl Jan 18, 2025
28164d7
Merge remote-tracking branch 'origin/master'
mklzl Feb 6, 2025
0fbab4e
Merge remote-tracking branch 'origin/master'
mklzl Feb 20, 2025
ca8cf75
[doc] Improve some datetime function desc
mklzl Feb 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions docs/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampadd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
{
"title": "TIMESTAMPADD",
"language": "en"
"title": "TIMESTAMPADD",
"language": "en"
}
---

Expand All @@ -26,24 +26,26 @@ under the License.

## Description

The `timestampadd` function is used to add a specified time unit (such as year, month, day, hour, minute, second, etc.) to a timestamp or date. This function is commonly used for date and time calculations.
The `timestampadd` function is used to add a specified time unit (such as year, month, day, hour, minute, second, etc.) to a date. This function is commonly used for date and time calculations.

## Syntax

`TIMESTAMPADD(<unit>, <interval>, <datetime_expr>)`

## Parameters

| Parameter | Description |
| -- | -- |
| `unit` | Time unit, specifies the time unit to add, common values include SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR |
| Parameter | Description |
| -- |----------------------------------------------------------------------------------------------------------------------|
| `unit` | Time unit, specifies the time unit to add, common values include SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR |
| `interval` | The time interval to add, typically an integer, which can be positive or negative to add or subtract the time length |
| `datetime_expr` | A valid target timestamp or date |
| `datetime_expr` | A valid datetime data type |

## Return Value

The return value is the new date and time, representing the result of adding or subtracting the specified time interval to the given timestamp.

If the input parameters are invalid, `NULL` is returned.

## Examples

```sql
Expand All @@ -69,3 +71,15 @@ SELECT TIMESTAMPADD(WEEK,1,'2019-01-02');
| 2019-01-09 00:00:00 |
+----------------------------------------------+
```

```sql
SELECT TIMESTAMPADD(WEEK,1,'1196440219');
```

```sql
+------------------------------------------------------------+
| timestampadd(WEEK, 1, CAST('1196440219' AS datetimev2(6))) |
+------------------------------------------------------------+
| NULL |
+------------------------------------------------------------+
```
28 changes: 21 additions & 7 deletions .../sql-manual/sql-functions/scalar-functions/date-time-functions/timestampdiff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
{
"title": "TIMESTAMPDIFF",
"language": "en"
"title": "TIMESTAMPDIFF",
"language": "en"
}
---

Expand All @@ -26,24 +26,26 @@ under the License.

## Description

The `timestampdiff` function is used to calculate the difference between two timestamps or dates and returns the time interval between them. The difference can be returned in the specified time unit (such as seconds, minutes, hours, days, months, years, etc.).
The `timestampdiff` function is used to calculate the difference between two dates and returns the time interval between them. The difference can be returned in the specified time unit (such as seconds, minutes, hours, days, months, years, etc.).

## Syntax

`TIMESTAMPDIFF(<unit>, <datetime_expr1>, <datetime_expr2>)`

## Parameters

| Parameter | Description |
| -- | -- |
| Parameter | Description |
| -- |------------------------------------------------------------------------------------------------------------------------------|
| `unit` | Time unit, specifies the unit in which to return the difference, common values include SECOND, MINUTE, HOUR, DAY, MONTH, YEAR |
| `datetime_expr1` | The first datetime, a valid target timestamp or date |
| `datetime_expr2` | The second datetime, a valid target timestamp or date |
| `datetime_expr1` | The first datetime, a valid target date |
| `datetime_expr2` | The second datetime, a valid target date |

## Return Value

The return value is the difference between the two date-times, with the unit determined by the unit parameter.

If the input parameters are invalid, `NULL` is returned.

## Examples

```sql
Expand Down Expand Up @@ -80,4 +82,16 @@ SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','2003-05-01 12:05:55');
+---------------------------------------------------------------------+
| 128885 |
+---------------------------------------------------------------------+
```

```sql
SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','1196440219');
```

```text
+-----------------------------------------------------------------------------------+
| timestampdiff(MINUTE, '2003-02-01 00:00:00', CAST('1196440219' AS datetimev2(6))) |
+-----------------------------------------------------------------------------------+
| NULL |
+-----------------------------------------------------------------------------------+
```
26 changes: 20 additions & 6 deletions ...t/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampadd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,24 +26,26 @@ under the License.

## 描述

`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个时间戳或日期上。这个函数通常用于日期和时间的计算。
`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个日期上。这个函数通常用于日期和时间的计算。

## 语法

`TIMESTAMPADD(<unit>, <interval>, <datetime_expr>)`

## 参数

| 参数 | 说明 |
| -- | -- |
| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR|
|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 |
| `datetime_expr` | 合法的目标时间戳或日期 |
| 参数 | 说明 |
| -- |-------------------------------------------------------------------|
| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR |
|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 |
| `datetime_expr` | 合法的目标日期，为 `DATETIME` 类型 |

## 返回值

返回新的日期时间，表示在指定时间点上添加或减去指定时间间隔后的结果。

如果输入的目标日期不合法，则返回 `NULL`。

## 举例

```sql
Expand All @@ -69,3 +71,15 @@ SELECT TIMESTAMPADD(WEEK,1,'2019-01-02');
| 2019-01-09 00:00:00 |
+----------------------------------------------+
```

```sql
SELECT TIMESTAMPADD(WEEK,1,'1196440219');
```

```sql
+------------------------------------------------------------+
| timestampadd(WEEK, 1, CAST('1196440219' AS datetimev2(6))) |
+------------------------------------------------------------+
| NULL |
+------------------------------------------------------------+
```
23 changes: 18 additions & 5 deletions .../sql-manual/sql-functions/scalar-functions/date-time-functions/timestampdiff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,24 +26,26 @@ under the License.

## 描述

`timestampdiff` 函数用于计算两个时间戳或日期之间的差值，返回两个时间戳之间的时间间隔。可以计算两者之间的差异，以指定的时间单位（如秒、分钟、小时、天、月、年等）返回结果。
`timestampdiff` 函数用于计算两个日期之间的差值，返回两个日期之间的时间间隔。可以计算两者之间的差异，以指定的时间单位（如秒、分钟、小时、天、月、年等）返回结果。

## 语法

`TIMESTAMPDIFF(<unit>, <datetime_expr1>, <datetime_expr2>)`

## 参数

| 参数 | 说明 |
| -- | -- |
| 参数 | 说明 |
| -- |-----------------------------------------------------------|
| `unit` | 时间单位，指定要返回差异的单位，常见的值有 SECOND、MINUTE、HOUR、DAY、MONTH、YEAR 等 |
|`datetime_expr1`| 第一个日期时间，合法的目标时间戳或日期 |
|`datetime_expr2`| 第二个日期时间，合法的目标时间戳或日期 |
|`datetime_expr1`| 第一个日期时间，合法的日期格式 |
|`datetime_expr2`| 第二个日期时间，合法的日期格式 |

## 返回值

返回两个日期时间之间的差异，单位根据 unit 参数确定。

如果输入的参数不合法，则返回 `NULL`

## 举例

```sql
Expand Down Expand Up @@ -81,3 +83,14 @@ SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','2003-05-01 12:05:55');
| 128885 |
+---------------------------------------------------------------------+
```
```sql
SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','1196440219');
```

```text
+-----------------------------------------------------------------------------------+
| timestampdiff(MINUTE, '2003-02-01 00:00:00', CAST('1196440219' AS datetimev2(6))) |
+-----------------------------------------------------------------------------------+
| NULL |
+-----------------------------------------------------------------------------------+
```
30 changes: 22 additions & 8 deletions ...1/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampadd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
{
"title": "TIMESTAMPADD",
"language": "zh-CN"
"title": "TIMESTAMPADD",
"language": "zh-CN"
}
---

Expand All @@ -26,24 +26,26 @@ under the License.

## 描述

`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个时间戳或日期上。这个函数通常用于日期和时间的计算。
`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个日期上。这个函数通常用于日期和时间的计算。

## 语法

`TIMESTAMPADD(<unit>, <interval>, <datetime_expr>)`

## 参数

| 参数 | 说明 |
| -- | -- |
| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR|
|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 |
| `datetime_expr` | 合法的目标时间戳或日期 |
| 参数 | 说明 |
| -- |-------------------------------------------------------------------|
| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR |
|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 |
| `datetime_expr` | 合法的目标日期，为 `DATETIME` 类型 |

## 返回值

返回新的日期时间，表示在指定时间点上添加或减去指定时间间隔后的结果。

如果输入的目标日期不合法，则返回 `NULL`。

## 举例

```sql
Expand All @@ -69,3 +71,15 @@ SELECT TIMESTAMPADD(WEEK,1,'2019-01-02');
| 2019-01-09 00:00:00 |
+----------------------------------------------+
```

```sql
SELECT TIMESTAMPADD(WEEK,1,'1196440219');
```

```sql
+------------------------------------------------------------+
| timestampadd(WEEK, 1, CAST('1196440219' AS datetimev2(6))) |
+------------------------------------------------------------+
| NULL |
+------------------------------------------------------------+
```
29 changes: 21 additions & 8 deletions .../sql-manual/sql-functions/scalar-functions/date-time-functions/timestampdiff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
{
"title": "TIMESTAMPDIFF",
"language": "zh-CN"
"title": "TIMESTAMPDIFF",
"language": "zh-CN"
}
---

Expand All @@ -26,23 +26,25 @@ under the License.

## 描述

`timestampdiff` 函数用于计算两个时间戳或日期之间的差值，返回两个时间戳之间的时间间隔。可以计算两者之间的差异，以指定的时间单位（如秒、分钟、小时、天、月、年等）返回结果。
`timestampdiff` 函数用于计算两个日期之间的差值，返回两个日期之间的时间间隔。可以计算两者之间的差异，以指定的时间单位（如秒、分钟、小时、天、月、年等）返回结果。

## 语法

`TIMESTAMPDIFF(<unit>, <datetime_expr1>, <datetime_expr2>)`

## 参数

| 参数 | 说明 |
| -- | -- |
| 参数 | 说明 |
| -- |-----------------------------------------------------------|
| `unit` | 时间单位，指定要返回差异的单位，常见的值有 SECOND、MINUTE、HOUR、DAY、MONTH、YEAR 等 |
|`datetime_expr1`| 第一个日期时间，合法的目标时间戳或日期 |
|`datetime_expr2`| 第二个日期时间，合法的目标时间戳或日期 |
|`datetime_expr1`| 第一个日期时间，合法的日期格式 |
|`datetime_expr2`| 第二个日期时间，合法的日期格式 |

## 返回值

返回两个日期时间之间的差异，单位根据 unit 参数确定。
返回两个日期时间之间的差异，单位根据 unit 参数确定。

如果输入的参数不合法，则返回 `NULL`

## 举例

Expand Down Expand Up @@ -81,3 +83,14 @@ SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','2003-05-01 12:05:55');
| 128885 |
+---------------------------------------------------------------------+
```
```sql
SELECT TIMESTAMPDIFF(MINUTE,'2003-02-01','1196440219');
```

```text
+-----------------------------------------------------------------------------------+
| timestampdiff(MINUTE, '2003-02-01 00:00:00', CAST('1196440219' AS datetimev2(6))) |
+-----------------------------------------------------------------------------------+
| NULL |
+-----------------------------------------------------------------------------------+
```
30 changes: 22 additions & 8 deletions ...0/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampadd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
{
"title": "TIMESTAMPADD",
"language": "zh-CN"
"title": "TIMESTAMPADD",
"language": "zh-CN"
}
---

Expand All @@ -26,24 +26,26 @@ under the License.

## 描述

`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个时间戳或日期上。这个函数通常用于日期和时间的计算。
`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个日期上。这个函数通常用于日期和时间的计算。

## 语法

`TIMESTAMPADD(<unit>, <interval>, <datetime_expr>)`

## 参数

| 参数 | 说明 |
| -- | -- |
| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR|
|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 |
| `datetime_expr` | 合法的目标时间戳或日期 |
| 参数 | 说明 |
| -- |-------------------------------------------------------------------|
| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR |
|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 |
| `datetime_expr` | 合法的目标日期，为 `DATETIME` 类型 |

## 返回值

返回新的日期时间，表示在指定时间点上添加或减去指定时间间隔后的结果。

如果输入的目标日期不合法，则返回 `NULL`。

## 举例

```sql
Expand All @@ -69,3 +71,15 @@ SELECT TIMESTAMPADD(WEEK,1,'2019-01-02');
| 2019-01-09 00:00:00 |
+----------------------------------------------+
```

```sql
SELECT TIMESTAMPADD(WEEK,1,'1196440219');
```

```sql
+------------------------------------------------------------+
| timestampadd(WEEK, 1, CAST('1196440219' AS datetimev2(6))) |
+------------------------------------------------------------+
| NULL |
+------------------------------------------------------------+
```
Loading