Update docs for Variant builtins (#11296)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

Author: Vadim Averin

ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/basic/variant.md

@@ -34,3 +34,64 @@ SELECT
    AsVariant(6, "foo") as VariantValue
 ```
 
+## Visit, VisitOrDefault {#visit}
+
+Processes the possible values of a variant over a structure or tuple using the provided handler functions for each field/element of the variant.
+
+### Signature
+
+```yql
+Visit(Variant<key1: K1, key2: K2, ...>, K1->R AS key1, K2->R AS key2, ...)->R
+Visit(Variant<K1, K2, ...>, K1->R, K2->R, ...)->R
+
+VisitOrDefault(Variant<K1, K2, ...>{Flags:AutoMap}, [K1->R, [K2->R, ...]], R)->R
+VisitOrDefault(Variant<key1: K1, key2: K2, ...>{Flags:AutoMap}, [K1->R AS key1, [K2->R AS key2, ...]], R)->R
+```
+
+### Arguments
+
+* For a variant over structure: accepts the variant as the positional argument and named arguments (handlers) corresponding to each field of the variant.
+* For a variant over tuple: accepts the variant and handlers for each element of the variant as positional arguments.
+* `VisitOrDefault` includes an additional positional argument for the default value, enabling the omission of certain handlers.
+
+### Example
+
+```yql
+$vartype = Variant<num: Int32, flag: Bool, str: String>;
+$handle_num = ($x) -> { return 2 * $x; };
+$handle_flag = ($x) -> { return If($x, 200, 10); };
+$handle_str = ($x) -> { return Unwrap(CAST(LENGTH($x) AS Int32)); };
+
+$visitor = ($var) -> { return Visit($var, $handle_num AS num, $handle_flag AS flag, $handle_str AS str); };
+SELECT
+    $visitor(Variant(5, "num", $vartype)),                -- 10
+    $visitor(Just(Variant(True, "flag", $vartype))),      -- Just(200)
+    $visitor(Just(Variant("somestr", "str", $vartype))),  -- Just(7)
+    $visitor(Nothing(OptionalType($vartype))),            -- Nothing(Optional<Int32>)
+    $visitor(NULL)                                        -- NULL
+;
+```
+
+## VariantItem {#variantitem}
+
+Returns the value of a homogeneous variant (i.e., a variant containing fields/elements of the same type).
+
+### Signature
+
+```yql
+VariantItem(Variant<key1: K, key2: K, ...>{Flags:AutoMap})->K
+VariantItem(Variant<K, K, ...>{Flags:AutoMap})->K
+```
+
+### Example
+
+```yql
+$vartype1 = Variant<num1: Int32, num2: Int32, num3: Int32>;
+SELECT
+    VariantItem(Variant(7, "num2", $vartype1)),          -- 7
+    VariantItem(Just(Variant(5, "num1", $vartype1))),    -- Just(5)
+    VariantItem(Nothing(OptionalType($vartype1))),       -- Nothing(Optional<Int32>)
+    VariantItem(NULL)                                    -- NULL
+;
+```
+

ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/variant.md

@@ -46,3 +46,64 @@ SELECT
    AsVariant(6, "foo") as VariantValue
 ```
 
+## Visit, VisitOrDefault {#visit}
+
+Обрабатывает возможные значения варианта, представленного структурой или кортежем, с использованием предоставленных функций-обработчиков для каждого из его полей/элементов.
+
+### Сигнатура
+
+```yql
+Visit(Variant<key1: K1, key2: K2, ...>, K1->R AS key1, K2->R AS key2, ...)->R
+Visit(Variant<K1, K2, ...>, K1->R, K2->R, ...)->R
+
+VisitOrDefault(Variant<K1, K2, ...>{Flags:AutoMap}, [K1->R, [K2->R, ...]], R)->R
+VisitOrDefault(Variant<key1: K1, key2: K2, ...>{Flags:AutoMap}, [K1->R AS key1, [K2->R AS key2, ...]], R)->R
+```
+
+### Аргументы
+
+* Для варианта над структурой функция принимает сам вариант в качестве позиционного аргумента и по одному именованному аргументу-обработчику для каждого поля этой структуры.
+* Для варианта над кортежем функция принимает сам вариант и по одному обработчику на каждый элемент кортежа в качестве позиционных аргументов.
+* Модификация `VisitOrDefault` принимает дополнительный последний позиционный аргумент, представляющий значение по умолчанию, и позволяет не указывать некоторые обработчики.
+
+### Пример
+
+```yql
+$vartype = Variant<num: Int32, flag: Bool, str: String>;
+$handle_num = ($x) -> { return 2 * $x; };
+$handle_flag = ($x) -> { return If($x, 200, 10); };
+$handle_str = ($x) -> { return Unwrap(CAST(LENGTH($x) AS Int32)); };
+
+$visitor = ($var) -> { return Visit($var, $handle_num AS num, $handle_flag AS flag, $handle_str AS str); };
+SELECT
+    $visitor(Variant(5, "num", $vartype)),                -- 10
+    $visitor(Just(Variant(True, "flag", $vartype))),      -- Just(200)
+    $visitor(Just(Variant("somestr", "str", $vartype))),  -- Just(7)
+    $visitor(Nothing(OptionalType($vartype))),            -- Nothing(Optional<Int32>)
+    $visitor(NULL)                                        -- NULL
+;
+```
+
+## VariantItem {#variantitem}
+
+Возвращает значение гомогенного варианта (т.е. содержащего поля/элементы одного типа).
+
+### Сигнатура
+
+```yql
+VariantItem(Variant<key1: K, key2: K, ...>{Flags:AutoMap})->K
+VariantItem(Variant<K, K, ...>{Flags:AutoMap})->K
+```
+
+### Пример
+
+```yql
+$vartype1 = Variant<num1: Int32, num2: Int32, num3: Int32>;
+SELECT
+    VariantItem(Variant(7, "num2", $vartype1)),          -- 7
+    VariantItem(Just(Variant(5, "num1", $vartype1))),    -- Just(5)
+    VariantItem(Nothing(OptionalType($vartype1))),       -- Nothing(Optional<Int32>)
+    VariantItem(NULL)                                    -- NULL
+;
+```
+