[doc](sql-functions) Document nonnegative bitmap_union_int inputs

docs/sql-manual/sql-functions/aggregate-functions/bitmap-union-int.md

@@ -1,30 +1,36 @@
 ---
 {
     "title": "BITMAP-UNION-INT",
     "language": "en",
-    "description": "Counts the number of distinct values in the input expression. The return value is the same as COUNT(DISTINCT expr)."
+    "description": "Counts distinct nonnegative integers in the input expression, ignoring negative values and NULLs."
 }
 ---
 
 ## Description
 
-Counts the number of distinct values in the input expression. The return value is the same as COUNT(DISTINCT expr).
+Counts distinct nonnegative integers in the input expression, ignoring negative values and NULLs.
+
+For supported integer inputs, this is equivalent to `COUNT(DISTINCT CASE WHEN expr >= 0 THEN expr END)` and to `BITMAP_COUNT(BITMAP_AGG(expr))`. It is equivalent to `COUNT(DISTINCT expr)` only when the input contains no negative values.
+
+## Usage Notes
+
+Ignoring negative values is the behavior of the development version. Earlier releases may count negative values; queries containing negative inputs can therefore return different results after upgrading.
 
 ## Syntax
 
 ```sql
 BITMAP_UNION_INT(<expr>)
 ```
 
-## Arguments
+## Parameters
 
-| Argument | Description |
-| -- | -- |
+| Parameter | Description |
+| --- | --- |
 | `<expr>` | The input expression. Supported types: TinyInt, SmallInt, Integer. |
 
 ## Return Value
 
-Returns the number of distinct values in the column. If there is no valid data in the group, returns 0.
+Returns a BIGINT containing the number of distinct nonnegative integers. NULLs and negative values are ignored. Returns 0 for empty input or a group containing only NULLs and negative values; the result is never NULL.
 
 ## Example
 
@@ -44,6 +50,11 @@
     (2, 200, to_bitmap(300));
 ```
 
+```text
+Query OK, 0 rows affected
+Query OK, 5 rows affected
+```
+
 ```sql
 select bitmap_union_int(dt) from pv_bitmap;
 ```
@@ -66,4 +77,37 @@
 +----------------------+
 |                    0 |
 +----------------------+
-```
+```
+
+Negative integers are excluded while zero is included:
+
+```sql
+SELECT bitmap_union_int(x) AS nonnegative_count
+FROM (
+    SELECT -1 AS x UNION ALL SELECT 0 UNION ALL SELECT 1
+    UNION ALL SELECT 1 UNION ALL SELECT NULL
+) AS input;
+```
+
+```text
++-------------------+
+| nonnegative_count |
++-------------------+
+|                 2 |
++-------------------+
+```
+
+A group with only negative values and NULLs returns zero:
+
+```sql
+SELECT bitmap_union_int(x) AS nonnegative_count
+FROM (SELECT -1 AS x UNION ALL SELECT -2 UNION ALL SELECT NULL) AS input;
+```
+
+```text
++-------------------+
+| nonnegative_count |
++-------------------+
+|                 0 |
++-------------------+
+```

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/bitmap-union-int.md

@@ -1,14 +1,20 @@
 ---
 {
     "title": "BITMAP-UNION-INT",
     "language": "zh-CN",
-    "description": "计算输入的表达式中不同值的个数，返回值和 COUNT(DISTINCT expr) 相同。"
+    "description": "计算输入表达式中不同非负整数的个数，忽略负数和 NULL。"
 }
 ---
 
 ## 描述
 
-计算输入的表达式中不同值的个数，返回值和 COUNT(DISTINCT expr) 相同。
+计算输入表达式中不同非负整数的个数，忽略负数和 NULL。
+
+对于支持的整数类型，结果等价于 `COUNT(DISTINCT CASE WHEN expr >= 0 THEN expr END)` 和 `BITMAP_COUNT(BITMAP_AGG(expr))`。只有输入不包含负数时，结果才与 `COUNT(DISTINCT expr)` 相同。
+
+## 使用说明
+
+忽略负数是开发版本的行为。早期版本可能将负数计入结果，因此升级后，包含负数的查询可能返回不同的结果。
 
 ## 语法
 
@@ -18,16 +24,15 @@
 
 ## 参数
 
-| 参数 | 说明 |
-| -- | -- |
+| 参数 | 描述 |
+| --- | --- |
 | `<expr>` | 输入的表达式，支持类型为 TinyInt，SmallInt，Integer。 |
 
 ## 返回值
 
-返回列中不同值的个数。
-组内没有合法数据时，返回 0 。
+返回 BIGINT 类型，表示不同非负整数的个数。忽略 NULL 和负数。输入为空或组内只有 NULL 和负数时，返回 0；结果不会为 NULL。
 
-## 举例
+## 示例
 
 ```sql
 -- setup
@@ -45,6 +50,11 @@
     (2, 200, to_bitmap(300));
 ```
 
+```text
+Query OK, 0 rows affected
+Query OK, 5 rows affected
+```
+
 ```sql
 select bitmap_union_int(dt) from pv_bitmap;
 ```
@@ -68,3 +78,36 @@
 |                    0 |
 +----------------------+
 ```
+
+负数不计入结果，零计入结果：
+
+```sql
+SELECT bitmap_union_int(x) AS nonnegative_count
+FROM (
+    SELECT -1 AS x UNION ALL SELECT 0 UNION ALL SELECT 1
+    UNION ALL SELECT 1 UNION ALL SELECT NULL
+) AS input;
+```
+
+```text
++-------------------+
+| nonnegative_count |
++-------------------+
+|                 2 |
++-------------------+
+```
+
+组内只有负数和 NULL 时返回零：
+
+```sql
+SELECT bitmap_union_int(x) AS nonnegative_count
+FROM (SELECT -1 AS x UNION ALL SELECT -2 UNION ALL SELECT NULL) AS input;
+```
+
+```text
++-------------------+
+| nonnegative_count |
++-------------------+
+|                 0 |
++-------------------+
+```