This is an automated email from the ASF dual-hosted git repository.
zclll pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 45cd49150b5 [Feature](func) Support function PERIOD_ADD and
PERIOD_DIFF (#2972)
45cd49150b5 is described below
commit 45cd49150b53b5206eafd4166079ed24124cb456
Author: linrrarity <[email protected]>
AuthorDate: Sat Nov 29 02:19:34 2025 +0800
[Feature](func) Support function PERIOD_ADD and PERIOD_DIFF (#2972)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../date-time-functions/period-add.md | 80 ++++++++++++++++++++++
.../date-time-functions/period-diff.md | 62 +++++++++++++++++
.../date-time-functions/period-add.md | 80 ++++++++++++++++++++++
.../date-time-functions/period-diff.md | 62 +++++++++++++++++
.../date-time-functions/period-add.md | 80 ++++++++++++++++++++++
.../date-time-functions/period-diff.md | 62 +++++++++++++++++
sidebars.ts | 2 +
.../date-time-functions/period-add.md | 80 ++++++++++++++++++++++
.../date-time-functions/period-diff.md | 62 +++++++++++++++++
versioned_sidebars/version-4.x-sidebars.json | 2 +
10 files changed, 572 insertions(+)
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
new file mode 100644
index 00000000000..9b560650c83
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
@@ -0,0 +1,80 @@
+---
+{
+ "title": "PERIOD_ADD",
+ "language": "en"
+}
+---
+
+## Description
+Calculate the result of increasing the `<period>` by `<month>` months.
+
+The `<period>` is an integer, the last two digits represent the month (01-12),
and the preceding digits represent the year.
+The function returns the calculated period in the format of an integer (year +
month).
+
+If the year part is less than 100, it will be processed into a four-digit year
format according to [certain rules](#parameters).
+For example: PERIOD_ADD(2501, 0) will return 202501, not 2501.
+
+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 composed of year and month.
<ul><li>**Format**: The month occupies the last two digits, which must be
within the range `[1, 12]`. The preceding digits represent the year, and the
number of digits for the year is unlimited; it can exceed four
digits.</li><li>**Year Inference**: The year value is directly taken from all
digits except the last two. If the year is a two-digit number (range: [00,
99]), if the year is less than 70, it is interpreted as 20YY; [...]
+| `<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.
\ No newline at end of file
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
new file mode 100644
index 00000000000..8d344cffd1e
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
@@ -0,0 +1,62 @@
+---
+{
+ "title": "PERIOD_DIFF",
+ "language": "en"
+}
+---
+
+## Description
+Calculates the difference in months between two periods.
+
+where `<period>` is an integer, the last two digits represent the month
(01-12), and the preceding digits represent the year.
+The function returns the absolute result of period_1 - period_2.
+
+If the year part is less than 100, it will be converted to a four-digit year
format according to [certain rules](#parameters).
+
+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 composed of year and month.
<ul><li>**Format**: The month occupies the last two digits, which must be
within the range `[1, 12]`. The preceding digits represent the year, and the
number of digits for the year is unlimited; it can exceed four
digits.</li><li>**Year Inference**: The year value is directly taken from all
digits except the last two. If the year is a two-digit number (range: [00,
99]), if the year is less than 70, it is interpreted as 20 [...]
+| `<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
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
new file mode 100644
index 00000000000..5e263accbb6
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
@@ -0,0 +1,80 @@
+---
+{
+ "title": "PERIOD_ADD",
+ "language": "zh-CN"
+}
+---
+
+## 描述
+计算周期 `<period>`增加 `<month>` 个月的结果。
+
+其中 `<period>` 是一个整数，最后两位表示月份（01-12），前面的数字表示年份。
+函数返回计算后的周期，格式为整数（年份+月份）。
+
+若年份部分小于 100 会按[一定规则](#参数)补为四位数年份格式处理。
+如: PERIOD_ADD(2501, 0) 会返回 202501, 而不是2501。
+
+该函数与 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>**格式**：月份固定占末尾两位，必须在 `[1, 12]`
范围内。前面的数字表示年份，年份位数不限，可以超过四位。</li><li>**年份推断**：年份取值直接使用除最后两位外的所有数字。当年份为两位数(范围:[00,
99]), 此时若年份小于 70 则解读为 20YY，若大于等于 70 则解读为 19YY。</li><li>**值范围**：接受 `[0,
2^63-1]` 范围内的整型参数。</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/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
new file mode 100644
index 00000000000..40fcb044e3b
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
@@ -0,0 +1,62 @@
+---
+{
+ "title": "PERIOD_DIFF",
+ "language": "zh-CN"
+}
+---
+
+## 描述
+计算两个周期之间的月份差值。
+
+其中 `<period>` 是一个整数，最后两位表示月份（01-12），前面的数字表示年份。
+函数返回period_1 - period_2的绝对结果。
+
+若年份部分小于 100 会按[一定规则](#参数)补为四位数年份格式处理。
+
+该函数与 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>**格式**：月份固定占末尾两位，必须在 `[1, 12]`
范围内。前面的数字表示年份，年份位数不限，可以超过四位。</li><li>**年份推断**：年份取值直接使用除最后两位外的所有数字。当年份为两位数(范围:[00,
99]), 此时若年份小于 70 则解读为 20YY，若大于等于 70 则解读为 19YY。</li><li>**值范围**：接受 `[0,
2^63-1]` 范围内的整型参数。</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
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
new file mode 100644
index 00000000000..5e263accbb6
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
@@ -0,0 +1,80 @@
+---
+{
+ "title": "PERIOD_ADD",
+ "language": "zh-CN"
+}
+---
+
+## 描述
+计算周期 `<period>`增加 `<month>` 个月的结果。
+
+其中 `<period>` 是一个整数，最后两位表示月份（01-12），前面的数字表示年份。
+函数返回计算后的周期，格式为整数（年份+月份）。
+
+若年份部分小于 100 会按[一定规则](#参数)补为四位数年份格式处理。
+如: PERIOD_ADD(2501, 0) 会返回 202501, 而不是2501。
+
+该函数与 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>**格式**：月份固定占末尾两位，必须在 `[1, 12]`
范围内。前面的数字表示年份，年份位数不限，可以超过四位。</li><li>**年份推断**：年份取值直接使用除最后两位外的所有数字。当年份为两位数(范围:[00,
99]), 此时若年份小于 70 则解读为 20YY，若大于等于 70 则解读为 19YY。</li><li>**值范围**：接受 `[0,
2^63-1]` 范围内的整型参数。</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/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
new file mode 100644
index 00000000000..40fcb044e3b
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
@@ -0,0 +1,62 @@
+---
+{
+ "title": "PERIOD_DIFF",
+ "language": "zh-CN"
+}
+---
+
+## 描述
+计算两个周期之间的月份差值。
+
+其中 `<period>` 是一个整数，最后两位表示月份（01-12），前面的数字表示年份。
+函数返回period_1 - period_2的绝对结果。
+
+若年份部分小于 100 会按[一定规则](#参数)补为四位数年份格式处理。
+
+该函数与 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>**格式**：月份固定占末尾两位，必须在 `[1, 12]`
范围内。前面的数字表示年份，年份位数不限，可以超过四位。</li><li>**年份推断**：年份取值直接使用除最后两位外的所有数字。当年份为两位数(范围:[00,
99]), 此时若年份小于 70 则解读为 20YY，若大于等于 70 则解读为 19YY。</li><li>**值范围**：接受 `[0,
2^63-1]` 范围内的整型参数。</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
+```
\ No newline at end of file
diff --git a/sidebars.ts b/sidebars.ts
index b24499acc15..325eab630c6 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1418,6 +1418,8 @@ const sidebars: SidebarsConfig = {
'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',
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
new file mode 100644
index 00000000000..9b560650c83
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md
@@ -0,0 +1,80 @@
+---
+{
+ "title": "PERIOD_ADD",
+ "language": "en"
+}
+---
+
+## Description
+Calculate the result of increasing the `<period>` by `<month>` months.
+
+The `<period>` is an integer, the last two digits represent the month (01-12),
and the preceding digits represent the year.
+The function returns the calculated period in the format of an integer (year +
month).
+
+If the year part is less than 100, it will be processed into a four-digit year
format according to [certain rules](#parameters).
+For example: PERIOD_ADD(2501, 0) will return 202501, not 2501.
+
+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 composed of year and month.
<ul><li>**Format**: The month occupies the last two digits, which must be
within the range `[1, 12]`. The preceding digits represent the year, and the
number of digits for the year is unlimited; it can exceed four
digits.</li><li>**Year Inference**: The year value is directly taken from all
digits except the last two. If the year is a two-digit number (range: [00,
99]), if the year is less than 70, it is interpreted as 20YY; [...]
+| `<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.
\ No newline at end of file
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
new file mode 100644
index 00000000000..8d344cffd1e
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md
@@ -0,0 +1,62 @@
+---
+{
+ "title": "PERIOD_DIFF",
+ "language": "en"
+}
+---
+
+## Description
+Calculates the difference in months between two periods.
+
+where `<period>` is an integer, the last two digits represent the month
(01-12), and the preceding digits represent the year.
+The function returns the absolute result of period_1 - period_2.
+
+If the year part is less than 100, it will be converted to a four-digit year
format according to [certain rules](#parameters).
+
+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 composed of year and month.
<ul><li>**Format**: The month occupies the last two digits, which must be
within the range `[1, 12]`. The preceding digits represent the year, and the
number of digits for the year is unlimited; it can exceed four
digits.</li><li>**Year Inference**: The year value is directly taken from all
digits except the last two. If the year is a two-digit number (range: [00,
99]), if the year is less than 70, it is interpreted as 20 [...]
+| `<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
+```
\ No newline at end of file
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index c6591780960..4ce802f228f 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -1440,6 +1440,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",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
