This is an automated email from the ASF dual-hosted git repository.
Mryange 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 693e821bd80 [Feature](func) Support AggFn percentile_approx_array
(#4016)
693e821bd80 is described below
commit 693e821bd80f3dd034fb58d6935893918afcb0fc
Author: linrrarity <[email protected]>
AuthorDate: Wed Aug 5 11:05:24 2026 +0800
[Feature](func) Support AggFn percentile_approx_array (#4016)
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
- [ ] Updated required version and language counterparts, or explained
why not
- [ ] If only one language changed, confirmed whether source/translation
counterparts need sync
---
.../aggregate-functions/percentile-approx-array.md | 108 +++++++++++++++++++++
.../aggregate-functions/percentile-approx-array.md | 108 +++++++++++++++++++++
.../aggregate-functions/percentile-approx-array.md | 108 +++++++++++++++++++++
sidebars.ts | 2 +
.../aggregate-functions/percentile-approx-array.md | 108 +++++++++++++++++++++
versioned_sidebars/version-4.x-sidebars.json | 2 +
6 files changed, 436 insertions(+)
diff --git
a/docs/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
b/docs/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
new file mode 100644
index 00000000000..dc179c137b1
--- /dev/null
+++
b/docs/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
@@ -0,0 +1,108 @@
+---
+{
+ "title": "PERCENTILE_APPROX_ARRAY",
+ "language": "en",
+ "description": "PERCENTILE_APPROX_ARRAY calculates multiple approximate
percentiles in one aggregation using a shared T-Digest state."
+}
+---
+
+## Description
+
+`PERCENTILE_APPROX_ARRAY` calculates multiple approximate percentiles in one
aggregation. It builds one T-Digest for the input values and evaluates every
requested percentile from that shared state, which is more efficient than
calling `PERCENTILE_APPROX` separately for each percentile.
+
+:::note
+This function is supported since 4.2.0.
+:::
+
+## Syntax
+
+```sql
+PERCENTILE_APPROX_ARRAY(<col>, <quantiles> [, <compression>])
+```
+
+## Parameters
+
+| Parameter | Description |
+| -- | -- |
+| `<col>` | The numeric expression whose percentiles are calculated. Values
are converted to `DOUBLE`. `NULL` values are ignored. |
+| `<quantiles>` | A constant `ARRAY<DOUBLE>`. Each element must be finite,
non-NULL, and in `[0.0, 1.0]`. Results follow the same order as the array, and
duplicate levels are preserved. An empty array is allowed. |
+| `<compression>` | Optional constant `DOUBLE` in `[2048, 10000]`. A larger
value generally improves accuracy but uses more memory. The default is `10000`;
non-finite values and values outside the valid range also use `10000`. |
+
+## Return Value
+
+Returns an `ARRAY<DOUBLE>` containing one approximate percentile for each
element of `<quantiles>`. The function returns an empty array when
`<quantiles>` is empty or when the group contains no non-NULL input values.
Invalid percentile levels and NULL elements in `<quantiles>` produce an error.
+
+## Example
+
+```sql
+CREATE TABLE percentile_approx_array_example (
+ id INT,
+ value DOUBLE NULL
+) DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO percentile_approx_array_example VALUES
+ (1, 1.0), (2, 2.0), (3, 3.0), (4, NULL),
+ (5, 10.0), (6, 20.0), (7, 30.0), (8, 100.0);
+```
+
+Calculate several approximate percentiles with the default compression:
+
+```sql
+SELECT percentile_approx_array(value, [0.0, 0.25, 0.5, 0.75, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++--------------------------+
+| percentiles |
++--------------------------+
+| [1, 2.25, 10, 27.5, 100] |
++--------------------------+
+```
+
+Specify the compression explicitly:
+
+```sql
+SELECT percentile_approx_array(value, [0.25, 0.5, 0.75], 2048) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++------------------+
+| percentiles |
++------------------+
+| [2.25, 10, 27.5] |
++------------------+
+```
+
+All-NULL input returns an empty array:
+
+```sql
+SELECT percentile_approx_array(CAST(NULL AS DOUBLE), [0.0, 0.5, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
+
+An empty percentile array also returns an empty array:
+
+```sql
+SELECT percentile_approx_array(value, []) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
new file mode 100644
index 00000000000..defdb847a25
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
@@ -0,0 +1,108 @@
+---
+{
+ "title": "PERCENTILE_APPROX_ARRAY",
+ "language": "zh-CN",
+ "description": "PERCENTILE_APPROX_ARRAY 使用共享的 T-Digest 状态在一次聚合中计算多个近似百分位数。"
+}
+---
+
+## 描述
+
+`PERCENTILE_APPROX_ARRAY` 在一次聚合中计算多个近似百分位数。函数为输入值构建一个
T-Digest，并基于这个共享状态计算所有指定的百分位数，因此比针对每个百分位数分别调用 `PERCENTILE_APPROX` 更高效。
+
+:::note
+自 4.2.0 版本开始支持该函数。
+:::
+
+## 语法
+
+```sql
+PERCENTILE_APPROX_ARRAY(<col>, <quantiles> [, <compression>])
+```
+
+## 参数
+
+| 参数 | 说明 |
+| -- | -- |
+| `<col>` | 需要计算百分位数的数值表达式，输入值会转换为 `DOUBLE`。函数忽略 `NULL` 值。 |
+| `<quantiles>` | 常量 `ARRAY<DOUBLE>`。每个元素都必须是有限值、非 NULL 且位于 `[0.0, 1.0]`
范围内。结果顺序与数组一致，并保留重复的百分位点。允许传入空数组。 |
+| `<compression>` | 可选的常量 `DOUBLE`，取值范围为 `[2048,
10000]`。值越大通常精度越高，但内存占用也越大。默认值为 `10000`；非有限值或超出有效范围时也使用 `10000`。 |
+
+## 返回值
+
+返回 `ARRAY<DOUBLE>`，其中每个元素对应 `<quantiles>` 中相同位置的近似百分位数。当 `<quantiles>`
为空，或组内没有非 NULL 输入值时，返回空数组。百分位点超出范围或 `<quantiles>` 包含 NULL 元素时返回错误。
+
+## 举例
+
+```sql
+CREATE TABLE percentile_approx_array_example (
+ id INT,
+ value DOUBLE NULL
+) DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO percentile_approx_array_example VALUES
+ (1, 1.0), (2, 2.0), (3, 3.0), (4, NULL),
+ (5, 10.0), (6, 20.0), (7, 30.0), (8, 100.0);
+```
+
+使用默认 compression 计算多个近似百分位数：
+
+```sql
+SELECT percentile_approx_array(value, [0.0, 0.25, 0.5, 0.75, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++--------------------------+
+| percentiles |
++--------------------------+
+| [1, 2.25, 10, 27.5, 100] |
++--------------------------+
+```
+
+显式指定 compression：
+
+```sql
+SELECT percentile_approx_array(value, [0.25, 0.5, 0.75], 2048) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++------------------+
+| percentiles |
++------------------+
+| [2.25, 10, 27.5] |
++------------------+
+```
+
+输入值全部为 NULL 时返回空数组：
+
+```sql
+SELECT percentile_approx_array(CAST(NULL AS DOUBLE), [0.0, 0.5, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
+
+百分位数组为空时也返回空数组：
+
+```sql
+SELECT percentile_approx_array(value, []) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
new file mode 100644
index 00000000000..defdb847a25
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
@@ -0,0 +1,108 @@
+---
+{
+ "title": "PERCENTILE_APPROX_ARRAY",
+ "language": "zh-CN",
+ "description": "PERCENTILE_APPROX_ARRAY 使用共享的 T-Digest 状态在一次聚合中计算多个近似百分位数。"
+}
+---
+
+## 描述
+
+`PERCENTILE_APPROX_ARRAY` 在一次聚合中计算多个近似百分位数。函数为输入值构建一个
T-Digest，并基于这个共享状态计算所有指定的百分位数，因此比针对每个百分位数分别调用 `PERCENTILE_APPROX` 更高效。
+
+:::note
+自 4.2.0 版本开始支持该函数。
+:::
+
+## 语法
+
+```sql
+PERCENTILE_APPROX_ARRAY(<col>, <quantiles> [, <compression>])
+```
+
+## 参数
+
+| 参数 | 说明 |
+| -- | -- |
+| `<col>` | 需要计算百分位数的数值表达式，输入值会转换为 `DOUBLE`。函数忽略 `NULL` 值。 |
+| `<quantiles>` | 常量 `ARRAY<DOUBLE>`。每个元素都必须是有限值、非 NULL 且位于 `[0.0, 1.0]`
范围内。结果顺序与数组一致，并保留重复的百分位点。允许传入空数组。 |
+| `<compression>` | 可选的常量 `DOUBLE`，取值范围为 `[2048,
10000]`。值越大通常精度越高，但内存占用也越大。默认值为 `10000`；非有限值或超出有效范围时也使用 `10000`。 |
+
+## 返回值
+
+返回 `ARRAY<DOUBLE>`，其中每个元素对应 `<quantiles>` 中相同位置的近似百分位数。当 `<quantiles>`
为空，或组内没有非 NULL 输入值时，返回空数组。百分位点超出范围或 `<quantiles>` 包含 NULL 元素时返回错误。
+
+## 举例
+
+```sql
+CREATE TABLE percentile_approx_array_example (
+ id INT,
+ value DOUBLE NULL
+) DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO percentile_approx_array_example VALUES
+ (1, 1.0), (2, 2.0), (3, 3.0), (4, NULL),
+ (5, 10.0), (6, 20.0), (7, 30.0), (8, 100.0);
+```
+
+使用默认 compression 计算多个近似百分位数：
+
+```sql
+SELECT percentile_approx_array(value, [0.0, 0.25, 0.5, 0.75, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++--------------------------+
+| percentiles |
++--------------------------+
+| [1, 2.25, 10, 27.5, 100] |
++--------------------------+
+```
+
+显式指定 compression：
+
+```sql
+SELECT percentile_approx_array(value, [0.25, 0.5, 0.75], 2048) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++------------------+
+| percentiles |
++------------------+
+| [2.25, 10, 27.5] |
++------------------+
+```
+
+输入值全部为 NULL 时返回空数组：
+
+```sql
+SELECT percentile_approx_array(CAST(NULL AS DOUBLE), [0.0, 0.5, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
+
+百分位数组为空时也返回空数组：
+
+```sql
+SELECT percentile_approx_array(value, []) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
diff --git a/sidebars.ts b/sidebars.ts
index e8c3f35b55a..99fbebcfea7 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -2060,6 +2060,7 @@ const sidebars: SidebarsConfig = {
'sql-manual/sql-functions/aggregate-functions/min-map',
'sql-manual/sql-functions/aggregate-functions/percentile',
'sql-manual/sql-functions/aggregate-functions/percentile-approx',
+
'sql-manual/sql-functions/aggregate-functions/percentile-approx-array',
'sql-manual/sql-functions/aggregate-functions/percentile-array',
'sql-manual/sql-functions/aggregate-functions/percentile-approx-weighted',
'sql-manual/sql-functions/aggregate-functions/percentile_reservoir',
@@ -2159,6 +2160,7 @@ const sidebars: SidebarsConfig = {
'sql-manual/sql-functions/aggregate-functions/min-by',
'sql-manual/sql-functions/aggregate-functions/percentile',
'sql-manual/sql-functions/aggregate-functions/percentile-approx',
+
'sql-manual/sql-functions/aggregate-functions/percentile-approx-array',
'sql-manual/sql-functions/aggregate-functions/percentile-array',
'sql-manual/sql-functions/aggregate-functions/percentile-approx-weighted',
'sql-manual/sql-functions/aggregate-functions/quantile-union',
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
new file mode 100644
index 00000000000..dc179c137b1
--- /dev/null
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/aggregate-functions/percentile-approx-array.md
@@ -0,0 +1,108 @@
+---
+{
+ "title": "PERCENTILE_APPROX_ARRAY",
+ "language": "en",
+ "description": "PERCENTILE_APPROX_ARRAY calculates multiple approximate
percentiles in one aggregation using a shared T-Digest state."
+}
+---
+
+## Description
+
+`PERCENTILE_APPROX_ARRAY` calculates multiple approximate percentiles in one
aggregation. It builds one T-Digest for the input values and evaluates every
requested percentile from that shared state, which is more efficient than
calling `PERCENTILE_APPROX` separately for each percentile.
+
+:::note
+This function is supported since 4.2.0.
+:::
+
+## Syntax
+
+```sql
+PERCENTILE_APPROX_ARRAY(<col>, <quantiles> [, <compression>])
+```
+
+## Parameters
+
+| Parameter | Description |
+| -- | -- |
+| `<col>` | The numeric expression whose percentiles are calculated. Values
are converted to `DOUBLE`. `NULL` values are ignored. |
+| `<quantiles>` | A constant `ARRAY<DOUBLE>`. Each element must be finite,
non-NULL, and in `[0.0, 1.0]`. Results follow the same order as the array, and
duplicate levels are preserved. An empty array is allowed. |
+| `<compression>` | Optional constant `DOUBLE` in `[2048, 10000]`. A larger
value generally improves accuracy but uses more memory. The default is `10000`;
non-finite values and values outside the valid range also use `10000`. |
+
+## Return Value
+
+Returns an `ARRAY<DOUBLE>` containing one approximate percentile for each
element of `<quantiles>`. The function returns an empty array when
`<quantiles>` is empty or when the group contains no non-NULL input values.
Invalid percentile levels and NULL elements in `<quantiles>` produce an error.
+
+## Example
+
+```sql
+CREATE TABLE percentile_approx_array_example (
+ id INT,
+ value DOUBLE NULL
+) DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO percentile_approx_array_example VALUES
+ (1, 1.0), (2, 2.0), (3, 3.0), (4, NULL),
+ (5, 10.0), (6, 20.0), (7, 30.0), (8, 100.0);
+```
+
+Calculate several approximate percentiles with the default compression:
+
+```sql
+SELECT percentile_approx_array(value, [0.0, 0.25, 0.5, 0.75, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++--------------------------+
+| percentiles |
++--------------------------+
+| [1, 2.25, 10, 27.5, 100] |
++--------------------------+
+```
+
+Specify the compression explicitly:
+
+```sql
+SELECT percentile_approx_array(value, [0.25, 0.5, 0.75], 2048) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++------------------+
+| percentiles |
++------------------+
+| [2.25, 10, 27.5] |
++------------------+
+```
+
+All-NULL input returns an empty array:
+
+```sql
+SELECT percentile_approx_array(CAST(NULL AS DOUBLE), [0.0, 0.5, 1.0]) AS
percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
+
+An empty percentile array also returns an empty array:
+
+```sql
+SELECT percentile_approx_array(value, []) AS percentiles
+FROM percentile_approx_array_example;
+```
+
+```text
++-------------+
+| percentiles |
++-------------+
+| [] |
++-------------+
+```
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index 42b1373b5e3..f4b70f2fa73 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -2233,6 +2233,7 @@
"sql-manual/sql-functions/aggregate-functions/min-map",
"sql-manual/sql-functions/aggregate-functions/percentile",
"sql-manual/sql-functions/aggregate-functions/percentile-approx",
+
"sql-manual/sql-functions/aggregate-functions/percentile-approx-array",
"sql-manual/sql-functions/aggregate-functions/percentile-array",
"sql-manual/sql-functions/aggregate-functions/percentile-approx-weighted",
"sql-manual/sql-functions/aggregate-functions/percentile_reservoir",
@@ -2334,6 +2335,7 @@
"sql-manual/sql-functions/aggregate-functions/min-map",
"sql-manual/sql-functions/aggregate-functions/percentile",
"sql-manual/sql-functions/aggregate-functions/percentile-approx",
+
"sql-manual/sql-functions/aggregate-functions/percentile-approx-array",
"sql-manual/sql-functions/aggregate-functions/percentile-array",
"sql-manual/sql-functions/aggregate-functions/percentile-approx-weighted",
"sql-manual/sql-functions/aggregate-functions/quantile-union",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
