大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:YEARS_ADD

· 52CE 我爱测

YEARS_ADD 函数用于在指定的日期或时间值上增加(或减少)指定数量的年数,返回调整后的日期或时间。支持处理 DATE、DATETIME、TIMESTAMP_NS 类型,年数可为正数(增加)或负数(减少)。该函数支持 DATE、DATETIME、TIMESTAMP_NS 和 TIMESTAMPTZ 输入类型。

描述

YEARS_ADD 函数用于在指定的日期或时间值上增加(或减少)指定数量的年数,返回调整后的日期或时间。支持处理 DATE、DATETIME、TIMESTAMP_NS 类型,年数可为正数(增加)或负数(减少)。该函数支持 DATE、DATETIME、TIMESTAMP_NS 和 TIMESTAMPTZ 输入类型。

该函数与 date_add 函数 和 mysql 中的 date_add 函数 使用 YEAR 为单位的行为一致

语法

YEARS_ADD(<date_or_time_expr>, <years>)

参数

参数 说明
<date_or_time_expr> 输入的日期时间值,支持输入 DATE/DATETIME/TIMESTAMP_NS/TIMESTAMPTZ 类型,具体格式请查看 timestamptz的转换,datetime 的转换 和 date 的转换
<years> 要增加的年数,类型为 INT,负数表示减少,正数表示增加

返回值

输入为 TIMESTAMP_NS 时返回 TIMESTAMP_NS,并保持固定的 9 位小数秒精度。结果必须位于返回类型的取值范围内;TIMESTAMP_NS 的范围为 [1677-09-21 00:12:43.145224192, 2262-04-11 23:47:16.854775807]。

返回与输入类型一致的结果(DATE、DATETIME、TIMESTAMP_NS 或 TIMESTAMPTZ),表示调整后的日期或时间,返回值类型由第一个参数的类型决定:

  • 若输入为 DATE 类型,返回值为 DATE 类型(仅调整年月日)。
  • 若输入为 DATETIME 类型,返回值为 DATETIME 类型(年月日调整后,时分秒保持不变)。
  • 若输入为 TIMESTAMPTZ 类型,返回值为 TIMESTAMPTZ 类型(包含日期、时间和时区偏移)。
  • <years_value> 为负数时表示减少年数(等价于 YEARS_SUB(<datetime_or_date_value>, <years_value>))。
  • 任意输入参数为 NULL,返回 NULL。
  • 若计算结果超出日期类型的有效范围(0000-01-01 00:00:00 至 9999-12-31 23:59:59),返回错误。
  • 若调整后月份的天数不足(如 2 月 29 日加 1 年且次年非闰年),自动调整为当月最后一天(如 2020-02-29 加 1 年返回 2021-02-28)。 举例

举例

-- DATETIME类型增加1年(基础功能,时分秒保持不变)
SELECT YEARS_ADD('2020-01-31 02:02:02', 1) AS add_1_year_datetime;
+-----------------------+
| add_1_year_datetime   |
+-----------------------+
| 2021-01-31 02:02:02   |
+-----------------------+

-- DATETIME类型减少1年(负数years_value,跨年度)
SELECT YEARS_ADD('2023-05-10 15:40:20', -1) AS subtract_1_year_datetime;
+--------------------------+
| subtract_1_year_datetime |
+--------------------------+
| 2022-05-10 15:40:20      |
+--------------------------+

-- DATE类型增加3年(仅调整日期)
SELECT YEARS_ADD('2019-12-25', 3) AS add_3_year_date;
+------------------+
| add_3_year_date  |
+------------------+
| 2022-12-25       |
+------------------+

-- 闰日处理(2020-02-29加1年,次年为平年)
SELECT YEARS_ADD('2020-02-29', 1) AS leap_day_adjust;
+------------------+
| leap_day_adjust  |
+------------------+
| 2021-02-28       |
+------------------+

-- 跨月天数调整(1月31日加1年到2月)
SELECT YEARS_ADD('2023-01-31', 1) AS month_day_adjust;
+------------------+
| month_day_adjust |
+------------------+
| 2024-01-31       | 
+------------------+


-- 输入为NULL(返回NULL)
SELECT YEARS_ADD(NULL, 5) AS null_input;
+------------+
| null_input |
+------------+
| NULL       |
+------------+

-- TimestampTz 类型示例,SET time_zone = '+08:00'
SELECT YEARS_ADD('2025-10-10 11:22:33.123+07:00', 1);
+-----------------------------------------------+
| YEARS_ADD('2025-10-10 11:22:33.123+07:00', 1) |
+-----------------------------------------------+
| 2026-10-10 12:22:33.123+08:00                 |
+-----------------------------------------------+

-- 计算结果超出日期时间范围(上限)
SELECT YEARS_ADD('9999-12-31', 1);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation years_add of 9999-12-31, 1 out of range

-- 计算结果超出日期时间范围(下限)
SELECT YEARS_ADD('0000-01-01', -1);
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation years_add of 0000-01-01, -1 out of range

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。