Add more examples for BOOL aggregations to docs (#12566)

2 files changed, 88 insertions, 10 deletions

diff --git a/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md b/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md
index c935c54e56..cb622154b0 100644
--- a/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md
+++ b/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md
@@ -1,17 +1,61 @@
 ## BOOL_AND, BOOL_OR and BOOL_XOR {#bool-and-or-xor}
 
+### Signature
+
+```yql
+BOOL_AND(Bool?)->Bool?
+BOOL_OR(Bool?)->Bool?
+BOOL_XOR(Bool?)->Bool?
+```
+
 Apply the relevant logical operation  (`AND`/`OR`/`XOR`) to all values in a Boolean column or expression.
 
-These functions **don't skip** `NULL` during aggregation, with even one `NULL` turning the result into `NULL`. To skip `NULLs` during aggregation, you can use the functions `MIN`/`MAX` or `BIT_AND`/`BIT_OR`/`BIT_XOR`.
+Unlike most other aggregate functions, these functions **don't skip** `NULL` during aggregation and use the following rules:
+
+- `true AND null == null`
+- `false OR null == null`
+
+For `BOOL_AND`:
+
+- If at least one `NULL` value is present, the result is `NULL` regardless of `true` values in the expression.
+- If at least one `false` value is present, the result changes to `false` regardless of `NULL` values in the expression.
+
+For `BOOL_OR`:
+
+- If at least one `NULL` value is present, the result changes to `NULL` regardless of `false` values in the expression.
+- If at least one `true` value is present, the result changes to `true` regardless of `NULL` values in the expression.
+
+For `BOOL_XOR`:
+
+- The result is `NULL` if any `NULL` is found.
+
+Examples of such behavior can be found below.
+
+To skip `NULL` values during aggregation, use the `MIN`/`MAX` or `BIT_AND`/`BIT_OR`/`BIT_XOR` functions.
 
 ### Examples
 
 ```yql
+$data = [
+    <|nonNull: true, nonFalse: true, nonTrue: NULL, anyVal: true|>,
+    <|nonNull: false, nonFalse: NULL, nonTrue: NULL, anyVal: NULL|>,
+    <|nonNull: false, nonFalse: NULL, nonTrue: false, anyVal: false|>,
+];
+
 SELECT
-  BOOL_AND(bool_column),
-  BOOL_OR(bool_column),
-  BOOL_XOR(bool_column)
-FROM my_table;
+    BOOL_AND(nonNull) as nonNullAnd,      -- false
+    BOOL_AND(nonFalse) as nonFalseAnd,    -- NULL
+    BOOL_AND(nonTrue) as nonTrueAnd,      -- false
+    BOOL_AND(anyVal) as anyAnd,           -- false
+    BOOL_OR(nonNull) as nonNullOr,        -- true
+    BOOL_OR(nonFalse) as nonFalseOr,      -- true
+    BOOL_OR(nonTrue) as nonTrueOr,        -- NULL
+    BOOL_OR(anyVal) as anyOr,             -- true
+    BOOL_XOR(nonNull) as nonNullXor,      -- true
+    BOOL_XOR(nonFalse) as nonFalseXor,    -- NULL
+    BOOL_XOR(nonTrue) as nonTrueXor,      -- NULL
+    BOOL_XOR(anyVal) as anyXor,           -- NULL
+FROM AS_TABLE($data);
 ```
 
 ## BIT_AND, BIT_OR and BIT_XOR {#bit-and-or-xor}
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md
index 9cbc336370..e5b22e7754 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/aggregation/bool_bit.md
@@ -10,18 +10,52 @@ BOOL_XOR(Bool?)->Bool?
 
 Применение соответствующей логической операции (`AND`/`OR`/`XOR`) ко всем значениям булевой колонки или выражения.
 
-Эти функции **не пропускают** `NULL` значение при агрегации и действуют по правилу `true and null == null`, `false or null == null`. Для `BOOL_AND` по всем `true` и любым `NULL` значениям превратит результат в `NULL`, а любое `false` значение превратит результат в `false` независимо от наличия `NULL`. Для `BOOL_OR` по всем `false` и любым `NULL` значениям превратит результат в `NULL`, а любое `true` значение превратит результат в `true` независимо от наличия `NULL`. Для `BOOL_XOR` любое `NULL` значение превратит результат в `NULL`.
+В отличие от большинства агрегатных функций, эти функции **не пропускают** `NULL` значение при агрегации и действуют по правилу:
+
+- `true AND null == null`
+- `false OR null == null`
+
+Для `BOOL_AND`:
+
+- Для любого количества значений `true` и хотя бы одного `NULL` значения, результатом будет `NULL`.
+- В случае хотя бы одного `false` значения, результатом будет `false`, независимо от наличия `NULL`.
+
+Для `BOOL_OR`:
+
+- Для любого количества значений `false` и хотя бы одного `NULL` значения, результатом будет `NULL`.
+- В случае хотя бы одного `true` значения, результатом будет `true`, независимо от наличия `NULL`.
+
+Для `BOOL_XOR`:
+
+- В случае хотя бы одного `NULL` значения, результатом будет `NULL`.
+
+Примеры описанного поведения приведены ниже.
 
 Для агрегации с пропуском `NULL`-ов можно использовать функции `MIN`/`MAX` или `BIT_AND`/`BIT_OR`/`BIT_XOR`.
 
 ### Примеры
 
 ```yql
+$data = [
+    <|nonNull: true, nonFalse: true, nonTrue: NULL, anyVal: true|>,
+    <|nonNull: false, nonFalse: NULL, nonTrue: NULL, anyVal: NULL|>,
+    <|nonNull: false, nonFalse: NULL, nonTrue: false, anyVal: false|>,
+];
+
 SELECT
-  BOOL_AND(bool_column),
-  BOOL_OR(bool_column),
-  BOOL_XOR(bool_column)
-FROM my_table;
+    BOOL_AND(nonNull) as nonNullAnd,      -- false
+    BOOL_AND(nonFalse) as nonFalseAnd,    -- NULL
+    BOOL_AND(nonTrue) as nonTrueAnd,      -- false
+    BOOL_AND(anyVal) as anyAnd,           -- false
+    BOOL_OR(nonNull) as nonNullOr,        -- true
+    BOOL_OR(nonFalse) as nonFalseOr,      -- true
+    BOOL_OR(nonTrue) as nonTrueOr,        -- NULL
+    BOOL_OR(anyVal) as anyOr,             -- true
+    BOOL_XOR(nonNull) as nonNullXor,      -- true
+    BOOL_XOR(nonFalse) as nonFalseXor,    -- NULL
+    BOOL_XOR(nonTrue) as nonTrueXor,      -- NULL
+    BOOL_XOR(anyVal) as anyXor,           -- NULL
+FROM AS_TABLE($data);
 ```
 
 ## BIT_AND, BIT_OR и BIT_XOR {#bit-and-or-xor}