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

Apache Doris 中文参考:QUARTERS_SUB

· 52CE 我爱测

QUARTERS_SUB 函数用于在指定的日期时间值基础上减去或增加指定的季度数(1 个季度 = 3 个月),并返回计算后的日期时间值。该函数支持处理 DATE、DATETIME、TIMESTAMP_NS 类型,若输入负数则等效于增加对应季度数。

描述

QUARTERS_SUB 函数用于在指定的日期时间值基础上减去或增加指定的季度数(1 个季度 = 3 个月),并返回计算后的日期时间值。该函数支持处理 DATE、DATETIME、TIMESTAMP_NS 类型,若输入负数则等效于增加对应季度数。

该函数与 date_sub 函数 使用 QUARTER 为单位行为一致。

语法

QUARTERS_SUB(`<date_or_time_expr>`, `<quarters>`)

参数

参数 说明
<date_or_time_expr 输入的日期或日期时间值,支持输入 DATE/DATETIME/TIMESTAMP_NS 类型,具体 datetime 和 date 格式请查看 datetime 的转换 和 date 的转换。
<quarters> 要增加或减少的季度数,正整数表示增加,负整数表示减少。

返回值

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

  • 若 <quarters> 为负数,函数效果等同于向基准时间中增加对应季度数(即 QUARTERS_SUB (date, -n) 等价于 QUARTERS_ADD (date, n))。
  • 若输入为 DATE 类型(仅包含年月日),返回结果仍为 DATE 类型;若输入为 DATETIME 类型,返回结果保留原时间部分(如 '2023-04-01 12:34:56' 减 1 个季度后为 '2023-01-01 12:34:56')。
  • 若输入日期为当月最后一天,且目标月份天数少于该日期,则自动调整为目标月份的最后一天(如 4 月 30 日减 1 个季度(3 个月)为 1 月 31 日)。
  • 若计算结果超出日期类型的有效范围(DATE 类型:0000-01-01 至 9999-12-31;DATETIME 类型:0000-01-01 00:00:00 至 9999-12-31 23:59:59),抛出异常。
  • 若任一参数为 NULL,返回 NULL。

举例

--- 从 DATE 类型减去季度
SELECT QUARTERS_SUB('2020-01-31', 1) AS result;
+------------+
| result     |
+------------+
| 2019-10-31 |
+------------+

--- 从 DATETIME 类型减去季度(保留时间部分)
SELECT QUARTERS_SUB('2020-01-31 02:02:02', 1) AS result;
+---------------------+
| result              |
+---------------------+
| 2019-10-31 02:02:02 |
+---------------------+

--- 负数季度(等价于加法)
SELECT QUARTERS_SUB('2019-10-31', -1) AS result;
+------------+
| result     |
+------------+
| 2020-01-31 |
+------------+

--- 非月底日期减去季度(直接递减)
SELECT QUARTERS_SUB('2023-07-13 22:28:18', 2) AS result;
+---------------------+
| result              |
+---------------------+
| 2023-01-13 22:28:18 |
+---------------------+

--- 包含微秒的 DATETIME(保留精度)
SELECT QUARTERS_SUB('2023-10-13 22:28:18.456789', 1) AS result;
+----------------------------+
| result                     |
+----------------------------+
| 2023-07-13 22:28:18.456789 |
+----------------------------+

--- 跨年度减去季度
SELECT QUARTERS_SUB('2024-04-01', 2) AS result;
+------------+
| result     |
+------------+
| 2023-10-01 |
+------------+

--- 输入为 NULL 时返回 NULL
SELECT QUARTERS_SUB(NULL, 1), QUARTERS_SUB('2023-07-13', NULL) AS result;
+-------------------------+--------+
| quarters_sub(NULL, 1)   | result |
+-------------------------+--------+
| NULL                    | NULL   |
+-------------------------+--------+

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

--- 计算结果超出日期范围
SELECT QUARTERS_SUB('0000-04-30', 1) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation quarters_sub of 0000-04-30, 1 out of range

SELECT QUARTERS_SUB('9999-12-31', -1) AS result;
ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[E-218]Operation quarters_sub of 9999-12-31, -1 out of range

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

资料来源与适用范围

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

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

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