From 7ec97fcd8f0fa5020cedb64d7eeb202b67d0f2bb Mon Sep 17 00:00:00 2001
From: Bulat Gayazov <brgayazov@yandex-team.ru>
Date: Fri, 22 Sep 2023 15:31:51 +0300
Subject: Added csv/tsv yql params description to docs

Added csv/tsv yql params description to docs

Pull Request resolved: 342
---
 ydb/docs/ru/core/_includes/parameterized-query.md  |   8 +-
 .../reference/ydb-cli/parameterized-queries-cli.md | 196 +++++++++++++++++----
 2 files changed, 165 insertions(+), 39 deletions(-)

diff --git a/ydb/docs/ru/core/_includes/parameterized-query.md b/ydb/docs/ru/core/_includes/parameterized-query.md
index fcc3da13b23..8bf79a00842 100644
--- a/ydb/docs/ru/core/_includes/parameterized-query.md
+++ b/ydb/docs/ru/core/_includes/parameterized-query.md
@@ -3,9 +3,11 @@
 Имя | Описание
 ---|---
 `-p, --param` | Значение одного параметра YQL-запроса в формате `$name=value`, где `$name` — имя параметра, а `value` — его значение (корректный [JSON value](https://www.json.org/json-ru.html)).
-`--param-file` | Имя файла в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} в кодировке [UTF-8]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/UTF-8){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/UTF-8){% endif %}, в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей.
-`--input-format` | Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или `stdin`).<br>Возможные значения:<ul><li>`json-unicode` (по умолчанию) — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}.</li><li>`json-base64` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}.</li></ul>
-`--stdin-format` | Формат представления параметров и фрейминг для `stdin`. Чтобы задать оба значения, укажите параметр дважды.<br>**Формат представления параметров на `stdin`**<br>Возможные значения:<ul><li>`json-unicode` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}.</li><li>`json-base64` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}.</li><li>`raw` - бинарные данные, имя параметра задается опцией `--stdin-par`.</li></ul>Если формат представления параметров на `stdin` не задан, то применяется формат, заданный параметром `--input-format`.<br><br>**Разделение наборов параметров (фрейминг) для `stdin`**<br>Возможные значения:<ul><li>`no-framing` (по умолчанию) — фрейминг не применяется</li><li>`newline-delimited` — символ перевода строки отмечает на `stdin` окончание одного набора параметров, отделяя его от следующего.</li></ul>
+`--param-file` | Имя файла в формате [JSON](https://{{lang}}.wikipedia.org/wiki/JSON) в кодировке [UTF-8](https://{{lang}}.wikipedia.org/wiki/UTF-8), в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей.
+`--input-format` | Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или `stdin`).<br>Возможные значения:<ul><li>`json-unicode` (по умолчанию) — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON).</li><li>`json-base64` — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON), в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64](https://{{lang}}.wikipedia.org/wiki/Base64).</li></ul>
+`--stdin-format` | Формат представления параметров и фрейминг для `stdin`. Чтобы задать оба значения, укажите параметр дважды.<br>**Формат представления параметров на `stdin`**<br>Возможные значения:<ul><li>`json-unicode` — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON).</li><li>`json-base64` — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON), в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64](https://{{lang}}.wikipedia.org/wiki/Base64).</li><li>`raw` — бинарные данные, имя параметра задается опцией `--stdin-par`.</li><li>`csv` — формат [CSV](https://{{lang}}.wikipedia.org/wiki/CSV).</li><li>`tsv` — формат [TSV](https://{{lang}}.wikipedia.org/wiki/TSV).</li></ul>Если формат представления параметров на `stdin` не задан, то применяется формат, заданный параметром `--input-format`.<br><br>**Разделение наборов параметров (фрейминг) для `stdin`**<br>Возможные значения:<ul><li>`no-framing` (по умолчанию) — фрейминг не применяется</li><li>`newline-delimited` — символ перевода строки отмечает на `stdin` окончание одного набора параметров, отделяя его от следующего.</li></ul>
+`--columns` | Строка с именами колонок, заменяющими header CSV/TSV документа, читаемого со stdin'а. Имена колонок должны быть в том же формате, что и сам документ.
+`--skip-rows` | Число строк с начала данных, читаемых со stdin'a, которые нужно пропустить, не включая строку header'a.
 `--stdin-par` | Имя параметра, значение которого будет передано через `stdin`, указывается без символа `$`.
 `--batch` | Режим пакетирования значений наборов параметров, получаемых через `stdin`.<br>Возможные значения:<ul><li>`iterative` (по умолчанию) — пакетирование выключено</li><li>`full` - полный пакет</li><li>`adaptive` - адаптивное пакетирование
 `--batch-limit` | Максимальное количество наборов параметров в пакете для адаптивного режима пакетирования. Установка в `0` снимает ограничение.<br><br>Значение по умолчанию — `1000`.<br><br>
diff --git a/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md b/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md
index 2d7b3647834..f4bc9b4a5a6 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/parameterized-queries-cli.md
@@ -10,7 +10,7 @@
 * [ydb scripting yql](scripting-yql.md);
 * [ydb table query execute](table-query-execute.md).
 
-Данные команды поддерживают одинаковый синтаксис и возможности передачи параметров запросов. Значения параметров могут быть заданы в командной строке, загружены из файлов в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, а также считаны с `stdin` в бинарном формате или в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}. При передаче параметров через `stdin` поддерживается многократное поточное исполнение YQL-запроса с разными значениями параметров и возможностью пакетирования.
+Данные команды поддерживают одинаковый синтаксис и возможности передачи параметров запросов. Значения параметров могут быть заданы в командной строке, загружены из файлов в формате [JSON](https://{{lang}}.wikipedia.org/wiki/JSON), а также считаны с `stdin` в бинарном формате или в формате [JSON](https://{{lang}}.wikipedia.org/wiki/JSON). При передаче параметров через `stdin` поддерживается многократное поточное исполнение YQL-запроса с разными значениями параметров и возможностью пакетирования.
 
 {% note warning %}
 
@@ -25,9 +25,11 @@
 Имя | Описание
 ---|---
 `-p, --param` | Выражение в формате `$name=value`, где `$name` — имя параметра YQL-запроса, а `value` — его значение (корректный [JSON value](https://www.json.org/json-ru.html)). Может быть указано несколько раз.<br><br>Все указываемые параметры должны быть декларированы в YQL-запросе [оператором DECLARE](../../yql/reference/syntax/declare.md), иначе будет выдана ошибка «Query does not contain parameter». Если один и тот же параметр указан несколько раз, будет выдана ошибка «Parameter value found in more than one source».<br><br>В зависимости от используемой операционной системы может понадобиться экранирование символа `$` или запись выражения в одинарных кавычках `'`.
-`--param-file` | Имя файла в формате [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %} в кодировке [UTF-8]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/UTF-8){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/UTF-8){% endif %}, в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей. Может быть указано несколько раз.<br><br>Если значения декларированного в YQL-запросе параметра будут обнаружены одновременно в нескольких файлах, или заданы в командной строке опцией `--param`, будет выдана ошибка «Parameter value found in more than one source».<br><br>Имена ключей в JSON-файле указываются без начального символа `$`. Ключи, которые присутствуют в файле, но не декларированы в YQL-запросе, будут проигнорированы без выдачи сообщения об ошибке.
-`--input-format` | Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или `stdin`).<br>Возможные значения:<ul><li>`json-unicode` (по умолчанию) — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}.</li><li>`json-base64` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}. Такая возможность позволяет передавать бинарные данные, декодирование которых из Base64 выполнит {{ ydb-short-name }} CLI.</li></ul>
-`--stdin-format` | Формат представления значений параметров на `stdin`.<br>{{ ydb-short-name }} CLI автоматически определяет что на стандартное устройство ввода `stdin` перенаправлен файл или выход другой команды командной оболочки, и в этом случае интерпретирует полученные данные в соответствии с возможными значениями:<ul><li>`json-unicode` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}.</li><li>`json-base64` — [JSON]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/JSON){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/JSON){% endif %}, в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Base64){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Base64){% endif %}.</li><li>`raw` - бинарные данные.</li></ul>Если формат представления параметров на `stdin` не задан, то применяется формат, заданный параметром `--input-format`.
+`--param-file` | Имя файла в формате [JSON](https://{{lang}}.wikipedia.org/wiki/JSON) в кодировке [UTF-8](https://{{lang}}.wikipedia.org/wiki/UTF-8), в котором заданы значения параметров, сопоставляемые с параметрами YQL-запроса по именам ключей. Может быть указано несколько раз.<br><br>Если значения декларированного в YQL-запросе параметра будут обнаружены одновременно в нескольких файлах, или заданы в командной строке опцией `--param`, будет выдана ошибка «Parameter value found in more than one source».<br><br>Имена ключей в JSON-файле указываются без начального символа `$`. Ключи, которые присутствуют в файле, но не декларированы в YQL-запросе, будут проигнорированы без выдачи сообщения об ошибке.
+`--input-format` | Формат представления значений параметров. Действует на все способы их передачи (через параметр команды, файл или `stdin`).<br>Возможные значения:<ul><li>`json-unicode` (по умолчанию) — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON).</li><li>`json-base64` — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON), в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64](https://{{lang}}.wikipedia.org/wiki/Base64). Такая возможность позволяет передавать бинарные данные, декодирование которых из Base64 выполнит {{ ydb-short-name }} CLI.</li></ul>
+`--stdin-format` | Формат представления значений параметров на `stdin`.<br>{{ ydb-short-name }} CLI автоматически определяет что на стандартное устройство ввода `stdin` перенаправлен файл или выход другой команды командной оболочки, и в этом случае интерпретирует полученные данные в соответствии с возможными значениями:<ul><li>`json-unicode` — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON).</li><li>`json-base64` — [JSON](https://{{lang}}.wikipedia.org/wiki/JSON), в котором значения параметров с типом «бинарная строка» (`DECLARE $par AS String`) представлены в кодировке [Base64](https://{{lang}}.wikipedia.org/wiki/Base64).</li><li>`raw` — бинарные данные.</li><li>`csv` — формат [CSV](https://{{lang}}.wikipedia.org/wiki/CSV). По умолчанию имена параметров должны находиться в header'е CSV файла. При единичном исполнении запроса допустима только одна строка в файле, не считая header'a.</li><li>`tsv` — формат [TSV](https://{{lang}}.wikipedia.org/wiki/TSV).</li></ul>Если формат представления параметров на `stdin` не задан, то применяется формат, заданный параметром `--input-format`.
+`--columns` | Строка с именами колонок, заменяющими header CSV/TSV документа, читаемого со stdin'а. Имена колонок должны быть в том же формате, что и сам документ. При указании опции считается, что header отсутствует. Опция допустима только с форматами stdin'a CSV и TSV.
+`--skip-rows` | Число строк с начала данных, читаемых со stdin'a, которые нужно пропустить, не включая строку header'a, если она имеется. Опция допустима только с форматами stdin'a CSV и TSV.
 `--stdin-par` | Имя параметра, значение которого передано через `stdin`. Указывается без символа `$`. Обязательно при использовании формата `raw` в `--stdin-format`.<br><br>При использовании с JSON-форматами `stdin` интерпретируется не как JSON-документ, а как JSON value, с передачей значения в параметр с указанным именем.
 
 Запрос будет отправлен на исполнение на сервер один раз, если значения заданы для всех параметров [в секции `DECLARE`](../../yql/reference/syntax/declare.md). Если хотя бы для одного параметра значение не задано, запрос не будет выполнен с выдачей сообщения об ошибке "Missing value for parameter".
@@ -128,6 +130,27 @@ curl -Ls http://ydb.tech/docs | {{ ydb-cli }} -p quickstart table query execute
 └─────────┘
 ```
 
+#### Передача файла в формате CSV {#example-csv}
+
+```bash
+echo '10,Some text' | {{ ydb-cli }} -p quickstart table query execute \
+  -q 'declare $a as Int32;
+      declare $b as String
+      select $a, $b' \
+  --stdin-format csv \
+  --columns 'a,b'
+```
+
+Вывод команды:
+
+```text
+┌─────────┬─────────────┐
+| column0 | column1     |
+├─────────┼─────────────┤
+| 10      | "Some text" |
+└─────────┴─────────────┘
+```
+
 ## Итеративная потоковая обработка {#streaming-iterate}
 
 {{ ydb-short-name }} CLI поддерживает возможность многократного исполнения YQL-запроса с разными наборами значений параметров, при их передаче через `stdin`. При этом соединение с базой данных устанавливается однократно, а план исполнения запроса кешируется, что существенно повышает производительность такого подхода по сравнению с отдельными вызовами CLI.
@@ -152,48 +175,149 @@ YQL-запрос выполняется столько раз, сколько н
 
 #### Потоковая обработка нескольких наборов параметров {#example-iterate}
 
-Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`:
+{% list tabs %}
 
-1. `a` = 10, `b` = 20
-2. `a` = 15, `b` = 25
-3. `a` = 35, `b` = 48
+- JSON
 
-Создадим файл, который будет содержать строки с JSON-представлением этих наборов:
+  Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`:
 
-```bash
-echo -e '{"a":10,"b":20}\n{"a":15,"b":25}\n{"a":35,"b":48}' > par1.txt
-cat par1.txt
-```
+  1. `a` = 10, `b` = 20
+  2. `a` = 15, `b` = 25
+  3. `a` = 35, `b` = 48
 
-Вывод команды:
+  Создадим файл, который будет содержать строки с JSON-представлением этих наборов:
 
-```text
-{"a":10,"b":20}
-{"a":15,"b":25}
-{"a":35,"b":48}
-```
+  ```bash
+  echo -e '{"a":10,"b":20}\n{"a":15,"b":25}\n{"a":35,"b":48}' > par1.txt
+  cat par1.txt
+  ```
 
-Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в JSON:
+  Вывод команды:
 
-```bash
-cat par1.txt | \
-{{ ydb-cli }} -p quickstart table query execute \
-  -q 'declare $a as Int64;
-      declare $b as Int64;
-      select $a+$b' \
-  --stdin-format newline-delimited \
-  --format json-unicode
-```
+  ```text
+  {"a":10,"b":20}
+  {"a":15,"b":25}
+  {"a":35,"b":48}
+  ```
 
-Вывод команды:
+  Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в JSON:
 
-```text
-{"column0":30}
-{"column0":40}
-{"column0":83}
-```
+  ```bash
+  cat par1.txt | \
+  {{ ydb-cli }} -p quickstart table query execute \
+    -q 'declare $a as Int64;
+        declare $b as Int64;
+        select $a+$b' \
+    --stdin-format newline-delimited \
+    --format json-unicode
+  ```
+
+  Вывод команды:
+
+  ```text
+  {"column0":30}
+  {"column0":40}
+  {"column0":83}
+  ```
+
+  Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса.
+
+- CSV
+
+  Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`:
+
+  1. `a` = 10, `b` = 20
+  2. `a` = 15, `b` = 25
+  3. `a` = 35, `b` = 48
+
+  Создадим файл c наборами значений параметров в формате CSV:
+
+  ```bash
+  echo -e 'a,b\n10,20\n15,25\n35,48' > par1.txt
+  cat par1.txt
+  ```
+
+  Вывод команды:
+
+  ```text
+  a,b
+  10,20
+  15,25
+  35,48
+  ```
+
+  Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в CSV:
+
+  ```bash
+  cat par1.txt | \
+  {{ ydb-cli }} -p quickstart table query execute \
+    -q 'declare $a as Int64;
+        declare $b as Int64;
+        select $a+$b, $a-$b' \
+    --stdin-format newline-delimited \
+    --stdin-format csv \
+    --format csv
+  ```
+
+  Вывод команды:
+
+  ```text
+  30,-10
+  40,-10
+  83,-13
+  ```
+
+  Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса, задав header данным в CSV формате опцией `--columns`.
+
+- TSV
+
+  Допустим, нам необходимо выполнить запрос трижды, со следующими наборами значений параметров `a` и `b`:
+
+  1. `a` = 10, `b` = row1
+  2. `a` = 15, `b` = row	2
+  3. `a` = 35, `b` = "row"\n3
+
+  Создадим файл c наборами значений параметров в формате TSV:
+
+  ```bash
+  echo -e 'a\tb\n10\trow1\n15\t"row\t2"\n35\t"""row""\n3"' > par1.txt
+  cat par1.txt
+  ```
+
+  Вывод команды:
+
+  ```text
+  a	b
+  10	row1
+  15	"row	2"
+  35	"""row""
+  3"
+  ```
+
+  Исполним запрос, передав на `stdin` содержимое данного файла, с форматированием вывода в TSV:
+
+  ```bash
+  cat par1.txt | \
+  {{ ydb-cli }} -p quickstart table query execute \
+    -q 'declare $a as Int64;
+        declare $b as Utf8;
+        select $a, $b' \
+    --stdin-format newline-delimited \
+    --stdin-format tsv \
+    --format tsv
+  ```
+
+  Вывод команды:
+
+  ```text
+  10	"row1"
+  15	"row\t2"
+  35	"\"row\"\n3"
+  ```
+
+  Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса, задав header данным в TSV формате опцией `--columns`.
 
-Полученный в таком формате результат можно использовать для передачи на вход команде исполнения следующего YQL-запроса.
+{% endlist %}
 
 #### Потоковая обработка с объединением значений параметров из разных источников {#example-iterate-union}
 
-- 
cgit v1.3