[] Document AssumeStrict and Likely

3 files changed, 44 insertions, 0 deletions

diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/assume_strict.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/assume_strict.md
new file mode 100644
index 0000000000..98bd84e39f
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/assume_strict.md
@@ -0,0 +1,22 @@
+## AssumeStrict {#assumestrict}
+
+**Сигнатура**
+```
+AssumeStrict(T)->T
+```
+
+Функция `AssumeStrict` возвращает свой аргумент. Использование этой функции – способ сказать оптимизатору YQL, что выражение в аргументе является _строгим_, т.е. свободным от ошибок времени выполнения.
+Большинство встроенных функций и операторов YQL являются строгими, но есть исключения – например [Unwrap](#optional-ops) и [Ensure](#ensure).
+Кроме того, нестрогим выражением считается вызов UDF.
+
+Если есть уверенность, что при вычислении выражения ошибок времени выполнения на самом деле не возникает, то имеет смысл использовать `AssumeStrict`.
+
+**Пример**
+``` yql
+SELECT * FROM T1 AS a JOIN T2 AS b USING(key)
+WHERE AssumeStrict(Unwrap(CAST(a.key AS Int32))) == 1;
+```
+
+В данном примере мы считаем что все значения текстовой колонки `a.key` в таблице `T1` являются валидными числами, поэтому Unwrap не приводит к ошибке.
+При налиичии `AssumeStrict` оптимизатор сможет выполнить сначала фильтрацию, а потом JOIN.
+Без `AssumeStrict` такая оптимизация не выполняется – оптимизатор обязан учитывать ситуацию, при которой в колонке `a.key` есть нечисловые значения, которые отфильтровываются `JOIN`ом.
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/likely.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/likely.md
new file mode 100644
index 0000000000..f34f3b03c6
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/basic/likely.md
@@ -0,0 +1,18 @@
+## Likely {#likely}
+
+**Сигнатура**
+```
+Likely(Bool)->Bool
+Likely(Bool?)->Bool?
+```
+
+Функция `Likely` возвращает свой аргумент. Функция является подсказкой оптимизатору и говорит о том, что в большинстве случаев ее аргумент будет иметь значение `True`.
+Например, наличие такой функции в `WHERE` означает что фильтр является слабоселективным.
+
+**Пример**
+``` yql
+SELECT * FROM T1 AS a JOIN T2 AS b USING(key)
+WHERE Likely(a.amount > 0)  -- почти всегда верно
+```
+
+При наличии `Likely` оптимизатор не будет стараться выполнить фильтрацию перед `JOIN`.
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/basic.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/basic.md
index b4262430aa..b3c267dbb5 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/builtins/basic.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/basic.md
@@ -51,6 +51,10 @@
 
 {% include [x](_includes/basic/ensure.md) %}
 
+{% include [x](_includes/basic/assume_strict.md) %}
+
+{% include [x](_includes/basic/likely.md) %}
+
 {% if feature_codegen %}
 
   {% include [x](_includes/basic/evaluate_expr_atom.md) %}