apache · linrrzqqq · Oct 14, 2025
diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
@@ -0,0 +1,74 @@
+---
+{
+    "title": "PERIOD_ADD",
+    "language": "en"
+}
+---
+
+## Description
+Adds `<month>` months to the `<period>` (formatted as YYYYMM or YYMM) and returns the result in YYYYMM format.
+
+This function behaves consistently with MySQL's [PERIOD_ADD function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-add).
+
+## Syntax
+
+```sql
+PERIOD_ADD(`<period>`, `month`)
+```
+
+## Parameters
+
+| Parameter  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<period>` | Represents a period consisting of a year and a month. <ul><li>**Format**: The last two digits represent the month, interpreted as YYYYMM or YYMM. If the YYMM format is used, YY values less than 70 are interpreted as 20YY, and YY values greater than or equal to 70 are interpreted as 19YY.</li><li>**Value Range**: Accepts integer values in the range `[0, 2^63-1]`, and the last two digits (month) must be within `[1, 12]`.</li><li>**Year Digits**: The function does not restrict the number of digits in the year, meaning the year can exceed four digits.</li></ul> |
+| `<month>`  | The number of months to add to `<period>`. Accepts integer values in the range `[-2^63, 2^63-1]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+
+## Return Value
+
+Returns an integer representing the calculated period in YYYYMM format. As noted in the parameter description, the year part is not limited to four digits.
+
+If any parameter is NULL, or if the `period` parameter cannot be converted to BIGINT, the function returns NULL.
+
+If the `period` parameter is negative or its month part is invalid, the function will throw an error.
+
+## Examples
+
+```sql
+SELECT `period`, `month`, PERIOD_ADD(`period`, `month`) AS ans FROM test_period_add;
+```
+```text
++----------+--------+----------+
+| period   | month  | ans      |
++----------+--------+----------+
+|   200803 |      2 |   200805 |
+|   200809 |      5 |   200902 |
+|      803 |      2 |   200805 |
+|     6910 |      3 |   207001 |
+|     7001 |      1 |   197002 |
+| 12345611 | 123456 | 13374411 |
+|     NULL |     10 |     NULL |
+|   202510 |   NULL |     NULL |
++----------+--------+----------+
+```
+
+```sql
+-- Month part exceeds the range [1, 12]
+SELECT PERIOD_ADD(202513, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: 202513
+
+-- Period exceeds BIGINT range
+SELECT PERIOD_ADD(-1, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```
+
+```sql
+SELECT PERIOD_ADD(9223372036854775807, 1);
+```
+```text
++------------------------------------+
+| PERIOD_ADD(9223372036854775807, 1) |
++------------------------------------+
+|               -9223372036854775808 |
++------------------------------------+
+```
+Explanation: Doris uses int64_t for internal calculations, so overflow may occur. This behavior is consistent with MySQL.
diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
@@ -0,0 +1,57 @@
+---
+{
+    "title": "PERIOD_DIFF",
+    "language": "en"
+}
+---
+
+## Description
+Calculates the difference in months between two periods.
+
+This function behaves consistently with MySQL's [PERIOD_DIFF function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-diff).
+
+## Syntax
+
+```sql
+PERIOD_DIFF(`<period_1>`, `<period_2>`)
+```
+
+## Parameters
+
+| Parameter      | Description                                                                                     |
+|----------------|-------------------------------------------------------------------------------------------------|
+| `<period_1>`   | Represents a period consisting of a year and a month. <ul><li>**Format**: The last two digits represent the month, interpreted as YYYYMM or YYMM. If the YYMM format is used, YY values less than 70 are interpreted as 20YY, and YY values greater than or equal to 70 are interpreted as 19YY.</li><li>**Value Range**: Accepts integer values in the range `[0, 2^63-1]`, and the last two digits (month) must be within `[1, 12]`.</li><li>**Year Digits**: The function does not restrict the number of digits in the year, meaning the year can exceed four digits.</li></ul> |
+| `<period_2>`   | Represents another period. The format requirements are the same as `<period_1>`. |
+
+## Return Value
+
+Returns an integer representing the total number of months in `<period_1>` minus the total number of months in `<period_2>`.
+
+If any parameter is NULL, or if the values cannot be converted to BIGINT, the function returns NULL.
+
+If the parameters are negative or their month parts are invalid, the function will throw an error.
+
+## Examples
+
+```sql
+SELECT `period_1`, `period_2`, PERIOD_DIFF(`period_1`, `period_2`) AS DIFF FROM `test_period_diff`;
+```
+```text
++---------------------+----------+---------------------+
+| period_1            | period_2 | DIFF                |
++---------------------+----------+---------------------+
+| 200802              |   200703 |                  11 |
+| 200703              |   200802 |                 -11 |
+| 7001                |     6912 |               -1199 |
+| NULL                |     2510 |                NULL |
+| 2510                |     NULL |                NULL |
+| 9223372036854775807 |      101 | 1106804644422549090 |
+| 9223372036854775808 |      101 |                NULL |
++---------------------+----------+---------------------+
+```
+In the last row, `period_1` exceeds the BIGINT upper limit (2^63-1), so the output is NULL.
+
+```sql
+SELECT PERIOD_DIFF(1, -1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```
diff --git a/...ent/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md b/...ent/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
@@ -0,0 +1,74 @@
+---
+{
+    "title": "PERIOD_ADD",
+    "language": "zh-CN"
+}
+---
+
+## 描述
+为周期 `<period>` (格式为 YYYYMM 或 YYMM) 增加 `<month>` 个月，并以 YYYYMM 格式返回结果。
+
+该函数与 MySQL 的 [PERIOD_ADD 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-add) 行为一致。
+
+## 语法
+
+```sql
+PERIOD_ADD(`<period>`, `month`)
+```
+
+## 参数
+
+| 参数            | 说明       |
+|---------------|-------------------------------------------------------|
+| `<period>` | 代表一个由年和月组成的周期。<ul><li>**格式**：月份固定占末尾两位，格式解读为 YYYYMM 或 YYMM。若使用 YYMM 格式，当 YY 小于 70 时会被解读为 20YY，当 YY 大于等于 70 时会被解读为 19YY。</li><li>**值范围**：接受 `[0, 2^63-1]` 范围内的整型参数，且最后两位（月份）必须在 `[1, 12]` 范围内。</li><li>**年份位数**：函数不限制年份部分的位数，这意味着年份可以超过四位。</li></ul> |
+| `<month>` | 在 `<period>` 基础上需要增加的月份数。接受 `[-2^63, 2^63-1]` 范围内的整型。 |
+
+## 返回值
+
+返回一个整型，代表计算之后得到的周期。格式为YYYYMM。 同参数说明，年份部分不一定为四位数字。
+
+当任一参数为 NULL，或 period 参数因数值无法转换为 BIGINT 时，返回 NULL。
+
+当 `period` 参数为负数或其月份部分无效时，函数将报错。
+
+## 举例
+
+```sql
+SELECT `period`, `month`, PERIOD_ADD(`period`, `month`) AS ans FROM test_period_add;
+```
+```text
++----------+--------+----------+
+| period   | month  | ans      |
++----------+--------+----------+
+|   200803 |      2 |   200805 |
+|   200809 |      5 |   200902 |
+|      803 |      2 |   200805 |
+|     6910 |      3 |   207001 |
+|     7001 |      1 |   197002 |
+| 12345611 | 123456 | 13374411 |
+|     NULL |     10 |     NULL |
+|   202510 |   NULL |     NULL |
++----------+--------+----------+
+```
+
+```sql
+-- 月份部分超出范围[1, 12]
+SELECT PERIOD_ADD(202513, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: 202513
+
+-- period 超出BIGINT范围
+SELECT PERIOD_ADD(-1, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```
+
+```sql
+SELECT PERIOD_ADD(9223372036854775807, 1);
+```
+```text
++------------------------------------+
+| PERIOD_ADD(9223372036854775807, 1) |
++------------------------------------+
+|               -9223372036854775808 |
++------------------------------------+
+```
+解释: 在 Doris 内部使用int64_t进行计算，所以会存在数值溢出的情况，此行为与 MySQL 一致。
diff --git a/...nt/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md b/...nt/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
@@ -0,0 +1,57 @@
+---
+{
+    "title": "PERIOD_DIFF",
+    "language": "zh-CN"
+}
+---
+
+## 描述
+计算两个周期之间的月份差值。
+
+该函数与 MySQL 的 [PERIOD_DIFF 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-diff) 行为一致。
+
+## 语法
+
+```sql
+PERIOD_DIFF(`<period_1>`, `<period_2>`)
+```
+
+## 参数
+
+| 参数            | 说明       |
+|---------------|-------------------------------------------------------|
+| `<period_1>` | 代表一个由年和月组成的周期。<ul><li>**格式**：月份固定占末尾两位，格式解读为 YYYYMM 或 YYMM。若使用 YYMM 格式，当 YY 小于 70 时会被解读为 20YY，当 YY 大于等于 70 时会被解读为 19YY。</li><li>**值范围**：接受 `[0, 2^63-1]` 范围内的整型参数，且最后两位（月份）必须在 `[1, 12]` 范围内。</li><li>**年份位数**：函数不限制年份部分的位数，这意味着年份可以超过四位。</li></ul> |
+| `<period_2>` | 代表另一个周期，格式要求与 `<period_1>` 相同。 |
+
+## 返回值
+
+返回一个整型，表示`<period_1>` 的总月份数减去 `<period_2>` 的总月份数的值。
+
+当任一参数为 NULL，因数值无法转换为 BIGINT 时，返回 NULL。
+
+当参数为负数或其月份部分无效时，函数将报错。
+
+## 举例
+
+```sql
+SELECT `period_1`, `period_2`, PERIOD_DIFF(`period_1`, `period_2`) AS DIFF FROM `test_period_diff`;
+```
+```text
++---------------------+----------+---------------------+
+| period_1            | period_2 | DIFF                |
++---------------------+----------+---------------------+
+| 200802              |   200703 |                  11 |
+| 200703              |   200802 |                 -11 |
+| 7001                |     6912 |               -1199 |
+| NULL                |     2510 |                NULL |
+| 2510                |     NULL |                NULL |
+| 9223372036854775807 |      101 | 1106804644422549090 |
+| 9223372036854775808 |      101 |                NULL |
++---------------------+----------+---------------------+
+```
+最后一行中period_1超出了BIGINT的上限(2^63-1), 故输出 NULL
+
+```sql
+SELECT PERIOD_DIFF(1, -1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```
diff --git a/sidebars.json b/sidebars.json
@@ -1385,6 +1385,8 @@
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/months-sub",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/now",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/next-day",
+                                        "sql-manual/sql-functions/scalar-functions/date-time-functions/period-add",
+                                        "sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/quarter",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-add",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-sub",