From 8b8059da840933af6e13ab6ba96fec30dd4dbd56 Mon Sep 17 00:00:00 2001
From: Mark Ziganshin <ziganshinmr@yandex-team.ru>
Date: Thu, 28 Nov 2024 18:13:50 +0300
Subject: [PATCH] Documentation for ListSample/ListSampleN/ListShuffle (#11802)

Co-authored-by: anton-bobkov <anton-bobkov@yandex-team.ru>
---
 .../yql-core/builtins/_includes/list.md       | 46 +++++++++++++++++
 .../yql-core/builtins/_includes/list.md       | 50 +++++++++++++++++++
 2 files changed, 96 insertions(+)

diff --git a/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/list.md b/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/list.md
index 4ad4d4b176b5..d47ed877e9ef 100644
--- a/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/list.md
+++ b/ydb/docs/en/core/yql/reference/yql-core/builtins/_includes/list.md
@@ -228,6 +228,52 @@ SELECT ListTake(list_column, 3) FROM my_table;
 
 {% endif %}
 
+## ListSample and ListSampleN {#listsample}
+
+Returns a sample without replacement from the list.
+
+- `ListSample` chooses elements independently with the specified probability.
+
+- `ListSampleN` chooses a sample of the specified size (if the length of the list is less than the sample size, returns the original list).
+
+If the probability/sample size is NULL, returns the original list.
+
+An optional argument is used to control randomness, see [documentation for `Random`](./basic/random.md).
+
+### Examples
+
+```yql
+ListSample(List<T>, Double?[, U])->List<T>
+ListSample(List<T>?, Double?[, U])->List<T>?
+
+ListSampleN(List<T>, Uint64?[, U])->List<T>
+ListSampleN(List<T>?, Uint64?[, U])->List<T>?
+```
+
+```yql
+$list = AsList(1, 2, 3, 4, 5);
+
+SELECT ListSample($list, 0.5);  -- [1, 2, 5]
+SELECT ListSampleN($list, 2);  -- [4, 2]
+```
+
+## ListShuffle {#listshuffle}
+
+Returns a shuffled copy of the list. An optional argument is used to control randomness, see [documentation for `Random`](./basic/random.md).
+
+### Examples
+
+```yql
+ListShuffle(List<T>[, U])->List<T>
+ListShuffle(List<T>?[, U])->List<T>?
+```
+
+```yql
+$list = AsList(1, 2, 3, 4, 5);
+
+SELECT ListShuffle($list);  -- [1, 3, 5, 2, 4]
+```
+
 ## ListIndexOf {#listindexof}
 
 Searches the list for an element with the specified value and returns its index at the first occurrence. Indexes count from 0. If such element is missing, it returns `NULL`.
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/list.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/list.md
index 494d6b809589..d2586eb89da2 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/list.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/list.md
@@ -363,6 +363,56 @@ ListTake(List<T>, Uint64)->List<T>
 ListTake(List<T>?, Uint64)->List<T>?
 ```
 
+## ListSample и ListSampleN {#listsample}
+
+Возвращает выборку без повторений из элементов списка.
+
+- `ListSample` выбирает каждый элемент независимо с заданной вероятностью.
+
+- `ListSampleN` выбирает фиксированное количество элементов (если длина списка меньше размера выборки, то вернется исходный список).
+
+Если вероятность/размер выборки является NULL, то вернется исходный список.
+
+Дополнительный аргумент используется для управления случайностью, подробнее см. [документацию к `Random`](./basic/random.md).
+
+### Примеры
+
+```yql
+$list = AsList(1, 2, 3, 4, 5);
+
+SELECT ListSample($list, 0.5);  -- [1, 2, 5]
+SELECT ListSampleN($list, 2);  -- [4, 2]
+```
+
+### Сигнатура
+
+```yql
+ListSample(List<T>, Double?[, U])->List<T>
+ListSample(List<T>?, Double?[, U])->List<T>?
+
+ListSampleN(List<T>, Uint64?[, U])->List<T>
+ListSampleN(List<T>?, Uint64?[, U])->List<T>?
+```
+
+## ListShuffle {#listshuffle}
+
+Возвращает копию списка с элементами, перестановленными в случайном порядке. Дополнительный аргумент используется для управления случайностью, подробнее см. [документацию к `Random`](./basic/random.md).
+
+### Примеры
+
+```yql
+$list = AsList(1, 2, 3, 4, 5);
+
+SELECT ListShuffle($list);  -- [1, 3, 5, 2, 4]
+```
+
+### Сигнатура
+
+```yql
+ListShuffle(List<T>[, U])->List<T>
+ListShuffle(List<T>?[, U])->List<T>?
+```
+
 ## ListIndexOf {#listindexof}
 
 Ищет элемент с указанным значением в списке и при первом обнаружении возвращает его индекс. Отсчет индексов начинается с 0, а в случае отсутствия элемента возвращается `NULL`.