Skip to content

[doc](function) Support Add_time/sub_time function documention #2901

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+396 −0
Open

[doc](function) Support Add_time/sub_time function documention #2901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
98 changes: 98 additions & 0 deletions docs/sql-manual/sql-functions/scalar-functions/date-time-functions/add-time.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
{
"title": "ADD_TIME",
"language": "en"
}
---

## Description

Adds the specified time interval to a date/time or time expression. If the second parameter is negative, it is equivalent to subtracting the interval from the first parameter.

## Syntax

```sql
ADD_TIME(`<date_or_time_expr>`, `<time>`)
```

## Parameters

| Parameter | Description |
| ---------------------| ----------- |
| `<date_or_time_expr>`| A valid date expression. Supports input of datetime/date/time types. If the type is date, it will be converted to the start time of the day (00:00:00). For specific datetime/time formats, see [datetime conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) and [time conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/time-conversion). |
| `<time>` | A valid time expression, representing the time value to be added to `<date_or_time_expr>`. If negative, it means subtraction. Supports input of time type. |

## Return Value

Returns the result of adding `<time>` to `<date_or_time_expr>`. The return type depends on the type of the first parameter:
- If the first parameter is of datetime type, returns datetime type.
- If the first parameter is of time type, returns time type.

Special cases:
- If any input parameter is null, returns null.
- If the first parameter is of time type and the result exceeds the time type range, returns the maximum (or minimum) time value.
- If the first parameter is of datetime type and the result exceeds the datetime type range, an error is thrown.

## Examples

```sql
-- Add time when the first parameter is datetime type
SELECT ADD_TIME('2025-09-19 12:00:00', '01:30:00');
+---------------------------------------------+
| ADD_TIME('2025-09-19 12:00:00', '01:30:00') |
+---------------------------------------------+
| 2025-09-19 13:30:00 |
+---------------------------------------------+

-- Add time when the first parameter is time type
SELECT ADD_TIME(cast('12:15:20' as time), '00:10:40');
+------------------------------------------------+
| ADD_TIME(cast('12:15:20' as time), '00:10:40') |
+------------------------------------------------+
| 12:26:00 |
+------------------------------------------------+

-- NULL parameter test
SELECT ADD_TIME(NULL, '01:00:00');
+----------------------------+
| ADD_TIME(NULL, '01:00:00') |
+----------------------------+
| NULL |
+----------------------------+

SELECT ADD_TIME('2025-09-19 12:00:00', NULL);
+---------------------------------------+
| ADD_TIME('2025-09-19 12:00:00', NULL) |
+---------------------------------------+
| NULL |
+---------------------------------------+

SELECT ADD_TIME(NULL, NULL);
+----------------------+
| ADD_TIME(NULL, NULL) |
+----------------------+
| NULL |
+----------------------+

-- Time type out-of-range test (returns max/min value)
SELECT ADD_TIME(cast('835:30:00' as time), '21:00:00');
+-------------------------------------------------+
| ADD_TIME(cast('835:30:00' as time), '21:00:00') |
+-------------------------------------------------+
| 838:59:59 |
+-------------------------------------------------+

SELECT ADD_TIME(cast('-832:30:00' as time), '-31:00:00');
+---------------------------------------------------+
| ADD_TIME(cast('-832:30:00' as time), '-31:00:00') |
+---------------------------------------------------+
| -838:59:59 |
+---------------------------------------------------+

-- Datetime type out-of-range test (throws error)
SELECT ADD_TIME('9999-12-31 23:59:59', '00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function add_time

SELECT ADD_TIME('0000-01-01 00:00:00', '-00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function add_time
```
98 changes: 98 additions & 0 deletions docs/sql-manual/sql-functions/scalar-functions/date-time-functions/sub-time.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
{
"title": "SUB_TIME",
"language": "en"
}
---

## Description

Subtracts the specified time interval from a date/time or time expression. If the second parameter is negative, it is equivalent to adding the interval to the first parameter.

## Syntax

```sql
SUB_TIME(`<date_or_time_expr>`, `<time>`)
```

## Parameters

| Parameter | Description |
| ---------------------| ----------- |
| `<date_or_time_expr>`| A valid date expression. Supports input of datetime/date/time types. If the type is date, it will be converted to the start time of the day (00:00:00). For specific datetime/time formats, see [datetime conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) and [time conversion](../../../../../docs/sql-manual/basic-element/sql-data-types/conversion/time-conversion). |
| `<time>` | A valid time expression, representing the time value to be subtracted from `<date_or_time_expr>`. If negative, it means addition. Supports input of time type. |

## Return Value

Returns the result of subtracting `<time>` from `<date_or_time_expr>`. The return type depends on the type of the first parameter:
- If the first parameter is of datetime type, returns datetime type.
- If the first parameter is of time type, returns time type.

Special cases:
- If any input parameter is null, returns null.
- If the first parameter is of time type and the result exceeds the time type range, returns the maximum (or minimum) time value.
- If the first parameter is of datetime type and the result exceeds the datetime type range, an error is thrown.

## Examples

```sql
-- Subtract time when the first parameter is datetime type
SELECT SUB_TIME('2025-09-19 12:00:00', '01:30:00');
+---------------------------------------------+
| SUB_TIME('2025-09-19 12:00:00', '01:30:00') |
+---------------------------------------------+
| 2025-09-19 10:30:00 |
+---------------------------------------------+

-- Subtract time when the first parameter is time type
SELECT SUB_TIME(cast('12:15:20' as time), '00:10:40');
+------------------------------------------------+
| SUB_TIME(cast('12:15:20' as time), '00:10:40') |
+------------------------------------------------+
| 12:04:40 |
+------------------------------------------------+

-- NULL parameter test
SELECT SUB_TIME(NULL, '01:00:00');
+----------------------------+
| SUB_TIME(NULL, '01:00:00') |
+----------------------------+
| NULL |
+----------------------------+

SELECT SUB_TIME('2025-09-19 12:00:00', NULL);
+---------------------------------------+
| SUB_TIME('2025-09-19 12:00:00', NULL) |
+---------------------------------------+
| NULL |
+---------------------------------------+

SELECT SUB_TIME(NULL, NULL);
+----------------------+
| SUB_TIME(NULL, NULL) |
+----------------------+
| NULL |
+----------------------+

-- Time type out-of-range test (returns max/min value)
SELECT SUB_TIME(cast('835:30:00' as time), '-21:00:00');
+--------------------------------------------------+
| SUB_TIME(cast('835:30:00' as time), '-21:00:00') |
+--------------------------------------------------+
| 838:59:59 |
+--------------------------------------------------+

SELECT SUB_TIME(cast('-832:30:00' as time), '31:00:00');
+---------------------------------------------------+
| SUB_TIME(cast('-832:30:00' as time), '31:00:00') |
+---------------------------------------------------+
| -838:59:59 |
+---------------------------------------------------+

-- Datetime type out-of-range test (throws error)
SELECT SUB_TIME('0000-01-01 00:00:00', '00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function sub_time

SELECT SUB_TIME('9999-12-31 23:59:59', '-00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function sub_time
```
101 changes: 101 additions & 0 deletions ...rrent/sql-manual/sql-functions/scalar-functions/date-time-functions/add-time.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
{
"title": "ADD_TIME",
"language": "zh-CN"
}
---

## 描述

将给定的时间间隔添加到日期时间/时间表达式上。若第二个参数为负数，则等价于从第一个参数中减去该时间间隔。


## 语法

```sql
ADD_TIME(`<date_or_time_expr>`, `<time>`)
```

## 参数

| 参数 | 说明 |
| -- | -- |
| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 datetime/date/time 类型,date 类型会转换为对应日期的一天起始时间 00:00:00 ,具体 datetime//time 格式请查看 [datetime 的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) 和 [time的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/time-conversion) |
| `<time>` | 参数为合法的时间表达式，表示增加到`<date_or_time_expr>` 上面的时间值，若为负数，则表示减少，支持输入 time 类型 |

## 返回值

返回 `<date_or_time_expr>` 添加 `<time>` 时间值之后的结果，根据第一个参数类型返回不同的类型
- 若第一个参数为 datetime 类型，则返回 datetime 类型
- 若第一个参数为 time 类型，则返回 time 类型

特殊情况:
- 若输入参数包含 null ,返回 null
- 若第一个参数类型为 time 类型，且计算结果超出 time 类型范围，则返回 time 类型最大（最小值）
- 若第一个参数类型为 datetime 类型，且计算结果超出 datetime 类型，则跑出错误


## 举例

```sql
-- 增加时间当第一个参数为 datetime 类型
SELECT ADD_TIME('2025-09-19 12:00:00', '01:30:00');
+---------------------------------------------+
| ADD_TIME('2025-09-19 12:00:00', '01:30:00') |
+---------------------------------------------+
| 2025-09-19 13:30:00 |
+---------------------------------------------+

-- 增加时间当第一个参数为 time 类型
SELECT ADD_TIME(cast('12:15:20' as time), '00:10:40');
+------------------------------------------------+
| ADD_TIME(cast('12:15:20' as time), '00:10:40') |
+------------------------------------------------+
| 12:26:00 |
+------------------------------------------------+

-- NULL 参数测试
SELECT ADD_TIME(NULL, '01:00:00');
+----------------------------+
| ADD_TIME(NULL, '01:00:00') |
+----------------------------+
| NULL |
+----------------------------+

SELECT ADD_TIME('2025-09-19 12:00:00', NULL);
+---------------------------------------+
| ADD_TIME('2025-09-19 12:00:00', NULL) |
+---------------------------------------+
| NULL |
+---------------------------------------+

SELECT ADD_TIME(NULL, NULL);
+----------------------+
| ADD_TIME(NULL, NULL) |
+----------------------+
| NULL |
+----------------------+

-- time 类型超出范围测试（返回最大/最小值）
SELECT ADD_TIME(cast('835:30:00' as time), '21:00:00');
+-------------------------------------------------+
| ADD_TIME(cast('835:30:00' as time), '21:00:00') |
+-------------------------------------------------+
| 838:59:59 |
+-------------------------------------------------+


SELECT ADD_TIME(cast('-832:30:00' as time), '-31:00:00');
+---------------------------------------------------+
| ADD_TIME(cast('-832:30:00' as time), '-31:00:00') |
+---------------------------------------------------+
| -838:59:59 |
+---------------------------------------------------+

-- datetime 类型超出范围测试（抛出错误）
SELECT ADD_TIME('9999-12-31 23:59:59', '00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function add_time

SELECT ADD_TIME('0000-01-01 00:00:00', '-00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function add_time
```
99 changes: 99 additions & 0 deletions ...rrent/sql-manual/sql-functions/scalar-functions/date-time-functions/sub-time.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
{
"title": "SUB_TIME",
"language": "zh-CN"
}
---

## 描述

从给定的日期时间/时间表达式中减去指定的时间间隔。若第二个参数为负数，则等价于向第一个参数中添加该时间间隔。

## 语法

```sql
SUB_TIME(`<date_or_time_expr>`, `<time>`)
```

## 参数

| 参数 | 说明 |
| -- | -- |
| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 datetime/date/time 类型,date 类型会转换为对应日期的一天起始时间 00:00:00 ,具体 datetime//time 格式请查看 [datetime 的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion) 和 [time的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/time-conversion) |
| `<time>` | 参数为合法的时间表达式，表示从`<date_or_time_expr>` 中减去的时间值，若为负数，则表示增加，支持输入 time 类型 |

## 返回值

返回 `<date_or_time_expr>` 减去 `<time>` 时间值之后的结果，根据第一个参数类型返回不同的类型
- 若第一个参数为 datetime 类型，则返回 datetime 类型
- 若第一个参数为 time 类型，则返回 time 类型

特殊情况:
- 若输入参数包含 null ,返回 null
- 若第一个参数类型为 time 类型，且计算结果超出 time 类型范围，则返回 time 类型最大（最小值）
- 若第一个参数类型为 datetime 类型，且计算结果超出 datetime 类型，则跑出错误

## 举例

```sql
-- 减少时间当第一个参数为 datetime 类型
SELECT SUB_TIME('2025-09-19 12:00:00', '01:30:00');
+---------------------------------------------+
| SUB_TIME('2025-09-19 12:00:00', '01:30:00') |
+---------------------------------------------+
| 2025-09-19 10:30:00 |
+---------------------------------------------+

-- 减少时间当第一个参数为 time 类型
SELECT SUB_TIME(cast('12:15:20' as time), '00:10:40');
+------------------------------------------------+
| SUB_TIME(cast('12:15:20' as time), '00:10:40') |
+------------------------------------------------+
| 12:04:40 |
+------------------------------------------------+

-- NULL 参数测试
SELECT SUB_TIME(NULL, '01:00:00');
+----------------------------+
| SUB_TIME(NULL, '01:00:00') |
+----------------------------+
| NULL |
+----------------------------+

SELECT SUB_TIME('2025-09-19 12:00:00', NULL);
+---------------------------------------+
| SUB_TIME('2025-09-19 12:00:00', NULL) |
+---------------------------------------+
| NULL |
+---------------------------------------+

SELECT SUB_TIME(NULL, NULL);
+----------------------+
| SUB_TIME(NULL, NULL) |
+----------------------+
| NULL |
+----------------------+

-- time 类型超出范围测试（返回最大/最小值）
SELECT SUB_TIME(cast('835:30:00' as time), '-21:00:00');
+--------------------------------------------------+
| SUB_TIME(cast('835:30:00' as time), '-21:00:00') |
+--------------------------------------------------+
| 838:59:59 |
+--------------------------------------------------+


SELECT SUB_TIME(cast('-832:30:00' as time), '31:00:00');
+---------------------------------------------------+
| SUB_TIME(cast('-832:30:00' as time), '31:00:00') |
+---------------------------------------------------+
| -838:59:59 |
+---------------------------------------------------+

-- datetime 类型超出范围测试（抛出错误）
SELECT SUB_TIME('0000-01-01 00:00:00', '00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function sub_time

SELECT SUB_TIME('9999-12-31 23:59:59', '-00:00:01');
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]datetime value is out of range in function sub_time
```