struct doc more examples

ref:fcb8e3a747c903714770de0d5e47b93f7c7c114b

1 files changed, 114 insertions, 30 deletions

diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/struct.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/struct.md
index 8b8f5de691..0636c88a58 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/struct.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/struct.md
@@ -2,14 +2,22 @@
 
 ## TryMember {#trymember}
 
-Попытка получить поле из структуры, а в случае его отсутствия среди полей или null в значении структуры использовать значение по умолчанию.
+Попытка получить значение поля из структуры, а в случае его отсутствия среди полей или null в значении структуры использовать значение по умолчанию.
+Тип `default_value` должен совпадать с типом поля `key` из структуры.
+
+**Сигнатура**
+```
+TryMember(struct:Struct<...>, key:String, default_value:T) -> T
+TryMember(struct:Struct<...>?, key:String, default_value:T) -> T?
+```
 
 Аргументы:
 
-1. Структура;
-2. Имя поля;
-3. Значение по умолчанию.
+1. struct - исходная структура;
+2. key - имя поля;
+3. default_value - значение по умолчанию если поле отсутствует
 
+**Примеры**
 ``` yql
 $struct = <|a:1|>;
 SELECT
@@ -27,9 +35,12 @@ SELECT
 
 ## ExpandStruct {#expandstruct}
 
-Добавление одного или нескольких новых полей в структуру.
+Добавление одного или нескольких новых полей в структуру. Возвращается новая раширенная структура.  В случае возникновения дублей в наборе полей будет возвращена ошибка.
 
-В случае возникновения дублей в наборе полей будет возвращена ошибка.
+**Сигнатура**
+```
+ExpandStruct(struct:Struct<...>, value_1:T1 AS key_1:K, value_2:T2 AS key_2:K, ....) -> Struct<...>
+```
 
 Аргументы:
 
@@ -44,7 +55,7 @@ SELECT
     $struct,
     2 AS b,
     "3" AS c
-  ) AS abc;
+  ) AS abc;  -- ("a": 1, "b": 2, "c": "3")
 ```
 
 ## AddMember {#addmember}
@@ -53,11 +64,16 @@ SELECT
 
 В случае возникновения дублей в наборе полей будет возвращена ошибка.
 
+**Сигнатура**
+```
+AddMember(struct:Struct<...>, new_key:String, new_value:T) -> Struct<...>
+```
+
 Аргументы:
 
-1. Исходная структура;
-2. Имя нового поля;
-3. Значение нового поля.
+1. struct - исходная структура;
+2. new_key - имя нового поля;
+3. new_value - значение нового поля.
 
 **Примеры**
 ``` yql
@@ -67,19 +83,22 @@ SELECT
     $struct,
     "b",
     2
-  ) AS ab;
+  ) AS ab; -- ("a": 1, "b": 2)
 ```
 
 ## RemoveMember {#removemember}
 
-Удаление поля из структуры.
+Удаление поля из структуры. Если указанного поля не существовало, будет возвращена ошибка.
 
-Если указанного поля не существовало, будет возвращена ошибка. 
+**Сигнатура**
+```
+RemoveMember(struct:Struct<...>, key_to_delete:String) -> Struct<...>
+```
 
 Аргументы:
 
 1. Исходная структура;
-2. Имя поля.
+2. Имя поля для удаления
 
 **Примеры**
 ``` yql
@@ -88,7 +107,7 @@ SELECT
   RemoveMember(
     $struct,
     "b"
-  ) AS a;
+  ) AS a; -- ("a": 1)
 ```
 
 ## ForceRemoveMember {#forceremovemember}
@@ -97,10 +116,15 @@ SELECT
 
 Если указанного поля не существовало, в отличии от [RemoveMember](#removemember) ошибка возвращена не будет.
 
+**Сигнатура**
+```
+ForceRemoveMember(struct:Struct<...>, key_to_delete:String) -> Struct<...>
+```
+
 Аргументы:
 
 1. Исходная структура;
-2. Имя поля.
+2. Имя поля для удаления.
 
 **Примеры**
 ``` yql
@@ -109,14 +133,19 @@ SELECT
   ForceRemoveMember(
     $struct,
     "c"
-  ) AS ab;
+  ) AS ab; -- ("a": 1, "b": 2) 
 ```
 
 ## ChooseMembers {#choosemembers}
 
-Выделение из структуры полей с заданными именами.
+Выделение из структуры полей с заданными именами. Возвращается новая структура только из заданных полей.
 
-Если какого-либо из полей не существовало, будет возвращена ошибка. 
+Если какого-либо из полей не существовало, будет возвращена ошибка.
+
+**Сигнатура**
+```
+ChooseMembers(struct:Struct<...>, list_of_keys:List<String>) -> Struct<...>
+```
 
 Аргументы:
 
@@ -130,7 +159,7 @@ SELECT
   ChooseMembers(
     $struct,
     ["a", "b"]
-  ) AS ab;
+  ) AS ab; -- ("a": 1, "b": 2)
 ```
 
 ## RemoveMembers {#removemembers}
@@ -139,6 +168,11 @@ SELECT
 
 Если какого-либо из полей не существовало, будет возвращена ошибка. 
 
+**Сигнатура**
+```
+RemoveMembers(struct:Struct<...>, list_of_delete_keys:List<String>) -> Struct<...>
+```
+
 Аргументы:
 
 1. Исходная структура;
@@ -151,7 +185,7 @@ SELECT
   RemoveMembers(
     $struct,
     ["a", "b"]
-  ) AS c;
+  ) AS c; -- ("c": 3)
 ```
 
 ## ForceRemoveMembers {#forceremovemembers}
@@ -160,6 +194,11 @@ SELECT
 
 Если какого-либо из полей не существовало, то оно игнорируется.
 
+**Сигнатура**
+```
+ForceRemoveMembers(struct:Struct<...>, list_of_delete_keys:List<String>) -> Struct<...>
+```
+
 Аргументы:
 
 1. Исходная структура;
@@ -172,7 +211,7 @@ SELECT
   ForceRemoveMembers(
     $struct,
     ["a", "b", "z"]
-  ) AS c;
+  ) AS c; -- ("c": 3)
 ```
 
 ## CombineMembers {#combinemembers}
@@ -181,6 +220,12 @@ SELECT
 
 В случае возникновения дублей в результирующем наборе полей будет возвращена ошибка.
 
+**Сигнатура**
+```
+CombineMembers(struct1:Struct<...>, struct2:Struct<...>, .....) -> Struct<...>
+CombineMembers(struct1:Struct<...>?, struct2:Struct<...>?, .....) -> Struct<...>
+```
+
 Аргументы: две и более структуры.
 
 **Примеры**
@@ -191,7 +236,7 @@ SELECT
   CombineMembers(
     $struct1,
     $struct2
-  ) AS abc;
+  ) AS abc; -- ("a": 1, "b": 2, "c": 3)
 ```
 
 ## FlattenMembers {#flattenmembers}
@@ -200,6 +245,11 @@ SELECT
 
 В случае возникновения дублей в результирующем наборе полей будет возвращена ошибка.
 
+**Сигнатура**
+```
+FlattenMembers(prefix_struct1:Tuple<String, Struct<...>>, prefix_struct2:Tuple<String, Struct<...>>, ...) -> Struct<...>
+```
+
 Аргументы: два и более кортежа из двух элементов: префикс и структура.
 
 **Примеры**
@@ -210,26 +260,39 @@ SELECT
   FlattenMembers(
     AsTuple("foo", $struct1), -- fooa, foob
     AsTuple("bar", $struct2)  -- barc
-  ) AS abc;
+  ) AS abc; -- ("barc": 3, "fooa": 1, "foob": 2)
 ```
 
 ## StructMembers {#structmembers}
 
 Возвращает неупорядоченный список имен полей (возможно, сняв один уровень опциональности) для единственного аргумента - структуры. Для `NULL` аргумента возвращается пустой список строк.
 
+**Сигнатура**
+```
+StructMembers(struct:Struct<...>) -> List<String>
+StructMembers(struct:Struct<...>?) -> List<String>
+StructMembers(NULL) -> []
+```
+
 Аргумент: структура
 
 **Примеры**
 ``` yql
 $struct = <|a:1, b:2|>;
 SELECT
-  StructMembers($struct); -- ['a', 'b']
+  StructMembers($struct) AS a, -- ['a', 'b']
+  StructMembers(NULL) AS b; -- []
 ```
 
 ## RenameMembers {#renamemembers}
 
 Переименовывает поля в переданной структуре. При этом исходное поле можно переименовать в несколько новых. Все поля, не упомянутые в переименовании как исходные, переносятся в результирующую структуру. Если нет какого-то исходного поля в списке для переименования, выдается ошибка. Для опциональной структуры либо `NULL` таким же является и результат.
 
+**Сигнатура**
+```
+RenameMembers(struct:Struct<...>, rename_rules:List<Tuple<String, String>>) -> Struct<...>
+```
+
 Аргументы:
 
 1. Исходная структура;
@@ -246,6 +309,11 @@ SELECT
 
 Переименовывает поля в переданной структуре. При этом исходное поле можно переименовать в несколько новых. Все поля, не упомянутые в переименовании как исходные, переносятся в результирующую структуру. Если нет какого-то исходного поля в списке для переименования, оно игнорируется. Для опциональной структуры либо `NULL` таким же является и результат.
 
+**Сигнатура**
+```
+ForceRenameMembers(struct:Struct<...>, rename_rules:List<Tuple<String, String>>) -> Struct<...>
+```
+
 Аргументы:
 
 1. Исходная структура;
@@ -262,18 +330,31 @@ SELECT
 
 Возвращает неупорядоченный список таплов из имени поля и значения. Для `NULL` аргумента возвращается `EmptyList`. Можно использовать только в тех случаях, когда типы элементов в структуре одинаковы или совместимы. Для опциональной структуры возвращает опциональный список.
 
+**Сигнатура**
+```
+GatherMembers(struct:Struct<...>) -> List<Tuple<String,V>>
+GatherMembers(struct:Struct<...>?) -> List<Tuple<String,V>>?
+GatherMembers(NULL) -> []
+```
+
 Аргумент: структура
 
 **Примеры**
 ``` yql
 $struct = <|a:1, b:2|>;
 SELECT
-  GatherMembers($struct); -- [('a', 1), ('b', 2)]
+  GatherMembers($struct), -- [('a', 1), ('b', 2)]
+  GatherMembers(null); -- []
 ```
 
 ## SpreadMembers {#spreadmembers}
 
-Создает структуру с заданным списком полей и применяет к ней заданный список исправлений в формате (имя поля, значение). Все типы полей результирующей структуры совпадают, и равны типу значений в списке исправлений с добавленной опциональностью (если еще не были таковыми). Если поле не было упомянуто среди списка редактируемых полей, оно возвращается как `NULL`. Среди всех исправлений по одному полю сохраняется последнее. Если список исправлений опционален либо равен `NULL`, то таковым является и результат. Если в списке исправлений встречается поле, которого нет в списке ожидаемых полей, выдается ошибка.
+Создает структуру с заданным списком полей и применяет к ней заданный список исправлений в формате (имя поля, значение). Все типы полей результирующей структуры совпадают, и равны типу значений в списке исправлений с добавленной опциональностью (если еще не были таковыми). Если поле не было упомянуто среди списка редактируемых полей, оно возвращается как `NULL`. Среди всех исправлений по одному полю сохраняется последнее. Если в списке исправлений встречается поле, которого нет в списке ожидаемых полей, выдается ошибка.
+
+**Сигнатура**
+```
+SpreadMembers(list_of_tuples:List<Tuple<String, T>>, result_keys:List<String>) -> Struct<...>
+```
 
 Аргументы:
 
@@ -282,14 +363,18 @@ SELECT
 
 **Примеры**
 ``` yql
-
 SELECT
   SpreadMembers([('a',1),('a',2)],['a','b']); -- (a: 2, b: null)
 ```
 
 ## ForceSpreadMembers {#forcespreadmembers}
 
-Создает структуру с заданным списком полей и применяет к ней заданный список исправлений в формате (имя поля, значение). Все типы полей результирующей структуры совпадают, и равны типу значений в списке исправлений с добавленной опциональностью (если еще не были таковыми). Если поле не было упомянуто среди списка редактируемых полей, оно возвращается как `NULL`. Среди всех исправлений по одному полю сохраняется последнее. Если список исправлений опционален либо равен `NULL`, то таковым является и результат. Если в списке исправлений встречается поле, которого нет в списке ожидаемых полей, то это исправление игнорируется.
+Создает структуру с заданным списком полей и применяет к ней заданный список исправлений в формате (имя поля, значение). Все типы полей результирующей структуры совпадают, и равны типу значений в списке исправлений с добавленной опциональностью (если еще не были таковыми). Если поле не было упомянуто среди списка редактируемых полей, оно возвращается как `NULL`. Среди всех исправлений по одному полю сохраняется последнее. Если в списке исправлений встречается поле, которого нет в списке ожидаемых полей, то это исправление игнорируется.
+
+**Сигнатура**
+```
+ForceSpreadMembers(list_of_tuples:List<Tuple<String, T>>, result_keys:List<String>) -> Struct<...>
+```
 
 Аргументы:
 
@@ -298,7 +383,6 @@ SELECT
 
 **Примеры**
 ``` yql
-
 SELECT
   ForceSpreadMembers([('a',1),('a',2),('c',100)],['a','b']); -- (a: 2, b: null)
 ```