YQL-14699: Improve dict documentation

ref:4442fd90e893a9dc549d6eeb34544ae9ad93e135

1 files changed, 140 insertions, 7 deletions

diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/dict.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/dict.md
index 19813b36772..70b09cb3050 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/dict.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/dict.md
@@ -1,8 +1,16 @@
 # Функции для работы со словарями
 
 ## DictCreate {#dictcreate}
+**Сигнатура**
+```
+DictCreate(K,V)->Dict<K,V>
+```
 
-Сконструировать пустой словарь. Передается два аргумента — для ключа и значения, в каждом из которых указывается строка с описанием типа данных, либо сам тип, полученный с помощью [предназначенных для этого функций](../types.md). Словарей с неизвестным типом ключа или значения в YQL не бывает. В качестве ключа может быть задан [примитивный тип данных](../../types/primitive.md) за исключением `Yson` и `Json` с необязательным признаком [опциональности](../../types/optional.md), или кортеж из них длины не менее два.
+Сконструировать пустой словарь. Передается два аргумента — для ключа и значения, в каждом из которых указывается строка с описанием типа данных, либо сам тип, полученный с помощью [предназначенных для этого функций](../types.md). Словарей с неизвестным типом ключа или значения в YQL не бывает.
+В качестве типа ключа могут быть заданы:
+* [примитивный тип данных](../../types/primitive.md) (кроме `Yson` и `Json`),
+* примитивный тип данных (кроме `Yson` и `Json`) с признаком опциональности,
+* кортеж длины не менее два из типов, перечисленных выше.
 
 [Документация по формату описания типа](../../types/type_string.md).
 
@@ -15,9 +23,17 @@ SELECT DictCreate(String, Tuple<String,Double?>);
 SELECT DictCreate(Tuple<Int32?,String>, OptionalType(DataType("String")));
 ```
 
+``` yql
+SELECT DictCreate(ParseType("Tuple<Int32?,String>"), ParseType("Tuple<String,Double?>"));
+```
+
 ## SetCreate {#setcreate}
+**Сигнатура**
+```
+SetCreate(T)->Set<T>
+```
 
-Сконструировать пустое множество. Передается аргумент - тип ключа, возможно, полученный с помощью [предназначенных для этого функций](../types.md). Множеств с неизвестным типом ключа в YQL не бывает. В качестве ключа может быть задан [примитивный тип данных](../../types/primitive.md) за исключением `Yson` и `Json` с необязательным признаком [опциональности](../../types/optional.md), или кортеж из них длины не менее два.
+Сконструировать пустое множество. Передается аргумент - тип ключа, возможно, полученный с помощью [предназначенных для этого функций](../types.md). Множеств с неизвестным типом ключа в YQL не бывает. Ограничения на тип ключа такие же как и на тип ключа для словаря. Следует иметь ввиду, что множество это словарь с типом значения `Void` и множество также можно создать и с помощью функции `DictCreate`. Отсюда также следует, что все функции, которые принимают на вход `Dict<K,V>` могут также принимать `Set<K>`.
 
 [Документация по формату описания типа](../../types/type_string.md).
 
@@ -31,6 +47,11 @@ SELECT SetCreate(Tuple<Int32?,String>);
 ```
 
 ## DictLength {#dictlength}
+**Сигнатура**
+```
+DictLength(Dict<K,V>)->Uint64
+DictLength(Dict<K,V>?)->Uint64?
+```
 
 Количество элементов в словаре.
 
@@ -44,6 +65,11 @@ SELECT DictLength(dict_column) FROM my_table;
 ```
 {% endif %}
 ## DictHasItems {#dicthasitems}
+**Сигнатура**
+```
+DictHasItems(Dict<K,V>)->Bool
+DictHasItems(Dict<K,V>?)->Bool?
+```
 
 Проверка того, что словарь содержит хотя бы один элемент.
 
@@ -59,6 +85,11 @@ SELECT DictHasItems(dict_column) FROM my_table;
 
 
 ## DictItems {#dictitems}
+**Сигнатура**
+```
+DictItems(Dict<K,V>)->List<Tuple<K,V>>
+DictItems(Dict<K,V>?)->List<Tuple<K,V>>?
+```
 
 Получение содержимого словаря в виде списка кортежей с парами ключ-значение (`List<Tuple<key_type,value_type>>`).
 
@@ -75,6 +106,11 @@ FROM my_table;
 ```
 {% endif %}
 ## DictKeys {#dictkeys}
+**Сигнатура**
+```
+DictKeys(Dict<K,V>)->List<K>
+DictKeys(Dict<K,V>?)->List<K>?
+```
 
 Получение списка ключей словаря.
 
@@ -91,6 +127,11 @@ FROM my_table;
 ```
 {% endif %}
 ## DictPayloads {#dictpayloads}
+**Сигнатура**
+```
+DictPayloads(Dict<K,V>)->List<V>
+DictPayloads(Dict<K,V>?)->List<V>?
+```
 
 Получение списка значений словаря.
 
@@ -108,6 +149,13 @@ FROM my_table;
 {% endif %}
 
 ## DictLookup {#dictlookup}
+**Сигнатура**
+```
+DictLookup(Dict<K,V>, K)->V?
+DictLookup(Dict<K,V>?, K)->V?
+DictLookup(Dict<K,V>, K?)->V?
+DictLookup(Dict<K,V>?, K?)->V?
+```
 
 Получение элемента словаря по ключу.
 
@@ -128,6 +176,13 @@ FROM my_table;
 {% endif %}
 
 ## DictContains {#dictcontains}
+**Сигнатура**
+```
+DictContains(Dict<K,V>, K)->Bool
+DictContains(Dict<K,V>?, K)->Bool
+DictContains(Dict<K,V>, K?)->Bool
+DictContains(Dict<K,V>?, K?)->Bool
+```
 
 Проверка наличия элемента в словаре по ключу. Возвращает true или false.
 
@@ -148,6 +203,11 @@ FROM my_table;
 {% endif %}
 
 ## DictAggregate {#dictaggregate}
+**Сигнатура**
+```
+DictAggregate(Dict<K,List<V>>, List<V>->T)->Dict<K,T>
+DictAggregate(Dict<K,List<V>>?, List<V>->T)->Dict<K,T>?
+```
 
 Применить [фабрику агрегационных функций](../basic.md#aggregationfactory) для переданного словаря, в котором каждое значение является списком. Фабрика применяется отдельно внутри каждого ключа.
 Если список является пустым, то результат агрегации будет такой же, как для пустой таблицы: 0 для функции `COUNT` и `NULL` для других функций.
@@ -165,13 +225,25 @@ FROM my_table;
 ```sql
 SELECT DictAggregate(AsDict(
     AsTuple(1, AsList("foo", "bar")),
-    AsTuple(2, AsList("baz", "qwe"))), 
+    AsTuple(2, AsList("baz", "qwe"))),
     AggregationFactory("Max"));
 -- {1 : "foo", 2 : "qwe" }
 
 ```
 
 ## SetIsDisjoint {#setisjoint}
+**Сигнатура**
+```
+SetIsDisjoint(Dict<K,V1>, Dict<K,V2>)->Bool
+SetIsDisjoint(Dict<K,V1>?, Dict<K,V2>)->Bool?
+SetIsDisjoint(Dict<K,V1>, Dict<K,V2>?)->Bool?
+SetIsDisjoint(Dict<K,V1>?, Dict<K,V2>?)->Bool?
+
+SetIsDisjoint(Dict<K,V1>, List<K>)->Bool
+SetIsDisjoint(Dict<K,V1>?, List<K>)->Bool?
+SetIsDisjoint(Dict<K,V1>, List<K>?)->Bool?
+SetIsDisjoint(Dict<K,V1>?, List<K>?)->Bool?
+```
 
 Проверка того, что словарь и список или другой словарь не пересекаются по ключам.
 
@@ -188,8 +260,20 @@ SELECT SetIsDisjoint(ToSet(AsList(1, 2, 3)), ToSet(AsList(3, 4))); -- false
 ```
 
 ## SetIntersection {#setintersection}
+**Сигнатура**
+```
+SetIntersection(Dict<K,V1>, Dict<K,V2>)->Set<K>
+SetIntersection(Dict<K,V1>?, Dict<K,V2>)->Set<K>?
+SetIntersection(Dict<K,V1>, Dict<K,V2>?)->Set<K>?
+SetIntersection(Dict<K,V1>?, Dict<K,V2>?)->Set<K>?
+
+SetIntersection(Dict<K,V1>, Dict<K,V2>, (K,V1,V2)->U)->Dict<K,U>
+SetIntersection(Dict<K,V1>?, Dict<K,V2>, (K,V1,V2)->U)->Dict<K,U>?
+SetIntersection(Dict<K,V1>, Dict<K,V2>?, (K,V1,V2)->U)->Dict<K,U>?
+SetIntersection(Dict<K,V1>?, Dict<K,V2>?, (K,V1,V2)->U)->Dict<K,U>?
+```
 
-Строит пересечение двух словарей по ключам. 
+Строит пересечение двух словарей по ключам.
 
 Аргументы:
 
@@ -206,7 +290,25 @@ SELECT SetIntersection(
 -- { 1 : ("foo", "baz") }
 ```
 
+{% note info %}
+
+В примере использовалась [лямбда функция](../../syntax/expressions.md#lambda).
+
+{% endnote %}
+
 ## SetIncludes {#setincludes}
+**Сигнатура**
+```
+SetIncludes(Dict<K,V1>, List<K>)->Bool
+SetIncludes(Dict<K,V1>?, List<K>)->Bool?
+SetIncludes(Dict<K,V1>, List<K>?)->Bool?
+SetIncludes(Dict<K,V1>?, List<K>?)->Bool?
+
+SetIncludes(Dict<K,V1>, Dict<K,V2>)->Bool
+SetIncludes(Dict<K,V1>?, Dict<K,V2>)->Bool?
+SetIncludes(Dict<K,V1>, Dict<K,V2>?)->Bool?
+SetIncludes(Dict<K,V1>?, Dict<K,V2>?)->Bool?
+```
 
 Проверка того, что в ключи заданного словаря входят все элементы списка или ключи второго словаря.
 
@@ -222,8 +324,20 @@ SELECT SetIncludes(ToSet(AsList(1, 2, 3)), ToSet(AsList(2, 3))); -- true
 ```
 
 ## SetUnion {#setunion}
+**Сигнатура**
+```
+SetUnion(Dict<K,V1>, Dict<K,V2>)->Set<K>
+SetUnion(Dict<K,V1>?, Dict<K,V2>)->Set<K>?
+SetUnion(Dict<K,V1>, Dict<K,V2>?)->Set<K>?
+SetUnion(Dict<K,V1>?, Dict<K,V2>?)->Set<K>?
+
+SetUnion(Dict<K,V1>, Dict<K,V2>,(K,V1?,V2?)->U)->Dict<K,U>
+SetUnion(Dict<K,V1>?, Dict<K,V2>,(K,V1?,V2?)->U)->Dict<K,U>?
+SetUnion(Dict<K,V1>, Dict<K,V2>?,(K,V1?,V2?)->U)->Dict<K,U>?
+SetUnion(Dict<K,V1>?, Dict<K,V2>?,(K,V1?,V2?)->U)->Dict<K,U>?
+```
 
-Строит объединение двух словарей по ключам. 
+Строит объединение двух словарей по ключам.
 
 Аргументы:
 
@@ -241,6 +355,13 @@ SELECT SetUnion(
 ```
 
 ## SetDifference {#setdifference}
+**Сигнатура**
+```
+SetDifference(Dict<K,V1>, Dict<K,V2>)->Dict<K,V1>
+SetDifference(Dict<K,V1>?, Dict<K,V2>)->Dict<K,V1>?
+SetDifference(Dict<K,V1>, Dict<K,V2>?)->Dict<K,V1>?
+SetDifference(Dict<K,V1>?, Dict<K,V2>?)->Dict<K,V1>?
+```
 
 Строит словарь, в котором есть все ключи с соответствующими значениями первого словаря, для которых нет ключа во втором словаре.
 
@@ -248,14 +369,26 @@ SELECT SetUnion(
 ``` yql
 SELECT SetDifference(ToSet(AsList(1, 2, 3)), ToSet(AsList(3, 4))); -- { 1, 2 }
 SELECT SetDifference(
-    AsDict(AsTuple(1, "foo"), AsTuple(2, "bar")), 
+    AsDict(AsTuple(1, "foo"), AsTuple(2, "bar")),
     ToSet(AsList(2, 3)));
 -- { 1 : "foo" }
 ```
 
 ## SetSymmetricDifference {#setsymmetricdifference}
+**Сигнатура**
+```
+SetSymmetricDifference(Dict<K,V1>, Dict<K,V2>)->Set<K>
+SetSymmetricDifference(Dict<K,V1>?, Dict<K,V2>)->Set<K>?
+SetSymmetricDifference(Dict<K,V1>, Dict<K,V2>?)->Set<K>?
+SetSymmetricDifference(Dict<K,V1>?, Dict<K,V2>?)->Set<K>?
+
+SetSymmetricDifference(Dict<K,V1>, Dict<K,V2>,(K,V1?,V2?)->U)->Dict<K,U>
+SetSymmetricDifference(Dict<K,V1>?, Dict<K,V2>,(K,V1?,V2?)->U)->Dict<K,U>?
+SetSymmetricDifference(Dict<K,V1>, Dict<K,V2>?,(K,V1?,V2?)->U)->Dict<K,U>?
+SetSymmetricDifference(Dict<K,V1>?, Dict<K,V2>?,(K,V1?,V2?)->U)->Dict<K,U>?
+```
 
-Строит симметрическую разность двух словарей по ключам. 
+Строит симметрическую разность двух словарей по ключам.
 
 Аргументы: