Describe the command ydb import file

initial

ref:06b3ea0ad4824fcf221f7faa6c3f90e36ba37765

4 files changed, 138 insertions, 3 deletions

diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
index 63610403ed2..353fb2f4067 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
@@ -31,8 +31,8 @@
 [discovery list](../commands/discovery-list.md) | Список эндпоинтов
 [discovery whoami](../commands/discovery-whoami.md) | Проверка аутентификации
 [export s3](../export_import/s3_export.md) | Экспорт данных в хранилище S3
-import file csv | Импорт данных из CSV-файла
-import file tsv | Импорт данных из TSV-файла
+[import file csv](../export_import/import-file.md) | Импорт данных из CSV-файла
+[import file tsv](../export_import/import-file.md) | Импорт данных из TSV-файла
 [import s3](../export_import/s3_import.md) | Импорт данных из хранилища S3
 [init](../profile/create.md) | Инициализация CLI, создание [профиля](../profile/index.md)
 operation cancel | Прерывание исполнения фоновой операции
diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/_includes/import-file.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/_includes/import-file.md
new file mode 100644
index 00000000000..e95e5d66e86
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/export_import/_includes/import-file.md
@@ -0,0 +1,133 @@
+# Импорт данных из файла в существующую таблицу
+
+С помощью подкоманды `import file` вы можете импортировать данные из [CSV]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/CSV){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Comma-separated_values){% endif %}- или [TSV]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/TSV){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/Tab-separated_values){% endif %}-файлов в существующую таблицу.
+
+Импорт выполняется методом `BulkUpsert`, который не гарантирует транзакционность. Если в таблице уже содержатся данные, они будут заменены импортируемыми при совпадении первичного ключа.
+
+Импортируемый файл должен быть в кодировке [UTF-8]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/UTF-8){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/UTF-8){% endif %}. Обработка переноса строки внутри поля данных не поддерживается.
+
+Общий вид команды:
+
+```bash
+{{ ydb-cli }} [connection options] import file csv|tsv [options]
+```
+
+{% include [conn_options_ref.md](../../commands/_includes/conn_options_ref.md) %}
+
+## Параметры подкоманды {#options}
+
+### Обязательные параметры {#required}
+
+* `-p, --path STRING` — путь к таблице в базе данных.
+* `--input-file STRING` — путь к файлу на локальной файловой системе, данные которого нужно импортировать.
+
+### Дополнительные параметры {#optional}
+
+* `--skip-rows NUM` — количество строк от начала файла, которое будет пропущено при импорте. Значение по умолчанию: `0`.
+* `--header` — укажите этот параметр, если первая строка (исключая пропущенные при использовании параметра `--skip-rows`) содержит имена столбцов данных, которые будут сопоставлены соответствующим столбцам таблицы. Если строка заголовка не указана, данные будут сопоставлены в порядке следования столбцов в схеме таблицы.
+* `--delimiter STRING` — символ-разделитель столбцов данных. В этом параметре нельзя указать символ табуляции в качестве разделителя. Чтобы импортировать файл с таким разделителем, используйте подкоманду `import file tsv`. Значение по умолчанию: `,`.
+* `--null-value STRING` — значение, которое будет импортировано как `NULL`. Значение по умолчанию: `""`.
+* `--batch-bytes VAL` — разбивать загружаемый файл на пакеты указанного размера. Если строка не умещается в пакет целиком, она будет отброшена и передана в следующем пакете. При любом значении размера пакет будет состоять минимум из одной строки. Значение по умолчанию: `1 Миб`.
+* `--max-in-flight VAL` — количество одновременно загружаемых пакетов данных. Для ускорения импорта больших файлов можно увеличить значение этого параметра. Значение по умолчанию: `100`.
+
+## Примеры {#examples}
+
+{% include [example_db1.md](../../_includes/example_db1.md) %}
+
+Перед выполнением примеров [создайте таблицу](../../../../getting_started/yql.md#create-table) `series`.
+
+### Импортировать файл {#simple}
+
+Файл содержит данные без дополнительной информации. в качестве разделителя используется символ `,`:
+
+```text
+1,Айтишники,The IT Crowd is a British sitcom.,13182
+2,Silicon Valley,Silicon Valley is an American comedy television series.,16166
+```
+
+{% note info %}
+
+Столбец `release_date` таблицы `series` имеет тип [Date](../../../../yql/reference/types/primitive.md#datetime), поэтому дата релиза в файле для импорта представлена в виде числа. Чтобы импортировать значения в формате [timestamp]{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/ISO_8601){% endif %}{% if lang == "en" %}(https://en.wikipedia.org/wiki/ISO_8601){% endif %}, используйте для них столбцы таблицы строкового типа, либо импортируйте их во временную таблицу и выполните преобразование к нужному типу.
+
+{% endnote %}
+
+Чтобы импортировать такой файл, выполните команду:
+
+```bash
+ydb import file csv -p series --input-file series.csv
+```
+
+В результате будут импортированы следующие данные:
+
+```text
+┌──────────────┬───────────┬───────────────────────────────────────────────────────────┬──────────────────┐
+| release_date | series_id | series_info                                               | title            |
+├──────────────┼───────────┼───────────────────────────────────────────────────────────┼──────────────────┤
+| "2006-02-03" | 1         | "The IT Crowd is a British sitcom."                       | "Айтишники"      |
+├──────────────┼───────────┼───────────────────────────────────────────────────────────┼──────────────────┤
+| "2014-04-06" | 2         | "Silicon Valley is an American comedy television series." | "Silicon Valley" |
+└──────────────┴───────────┴───────────────────────────────────────────────────────────┴──────────────────┘
+```
+
+### Импортировать файл с разделителем `|` {#custom-delimiter}
+
+Файл содержит данные без дополнительной информации. в качестве разделителя используется символ `|`:
+
+```text
+1|IT Crowd|The IT Crowd is a British sitcom.|13182
+2|Silicon Valley|Silicon Valley is an American comedy television series.|16166
+```
+
+Чтобы импортировать такой файл, укажите параметр `--delimiter` со значением `|`:
+
+```bash
+ydb import file csv -p series --input-file series.csv  --delimiter "|"
+```
+
+### Пропустить строки и считать заголовки столбцов {#skip}
+
+Файл содержит дополнительную информацию в первой и второй строке, а также заголовки столбцов в третьей. Порядок данных в строках файла не соответствует порядку столбцов в таблице:
+
+```text
+#The file contains data about the series.
+#
+series_id,title,release_date,series_info
+1,Айтишники,13182,The IT Crowd is a British sitcom.
+2,Silicon Valley,16166,Silicon Valley is an American comedy television series.
+```
+
+Чтобы пропустить комментарии в первой и второй строке, укажите параметр `--skip-rows 2`. Чтобы обработать строку третью строку как заголовки и сопоставить данные файла нужным столбцам таблицы, укажите параметр `--header`:
+
+```bash
+ydb import file csv -p series --input-file series.csv --skip-rows 2 --header
+```
+
+### Заменить значения на `NULL` {#replace-with-null}
+
+Файл содержит часто используемое для `NULL` обозначение — `\N`, а также пустую строку.
+
+```text
+1,Айтишники,The IT Crowd is a British sitcom.,13182
+2,Silicon Valley,"",\N
+3,Lost,,\N
+```
+
+Укажите параметр `--null-value "\N"`, чтобы интерпретировать значение `\N` как `NULL`:
+
+```bash
+ydb import file csv -p series --input-file series.csv --null-value "\N"
+```
+
+В результате будут импортированы следующие данные:
+
+```text
+┌──────────────┬───────────┬─────────────────────────────────────┬──────────────────┐
+| release_date | series_id | series_info                         | title            |
+├──────────────┼───────────┼─────────────────────────────────────┼──────────────────┤
+| "2006-02-03" | 1         | "The IT Crowd is a British sitcom." | "Айтишники"      |
+├──────────────┼───────────┼─────────────────────────────────────┼──────────────────┤
+| null         | 2         | ""                                  | "Silicon Valley" |
+├──────────────┼───────────┼─────────────────────────────────────┼──────────────────┤
+| null         | 3         | ""                                  | "Lost"           |
+└──────────────┴───────────┴─────────────────────────────────────┴──────────────────┘
+```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/import-file.md b/ydb/docs/ru/core/reference/ydb-cli/export_import/import-file.md
new file mode 100644
index 00000000000..49e7eb5a643
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/export_import/import-file.md
@@ -0,0 +1 @@
+{% include [file_structure.md](_includes/import-file.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml
index bcfd46a3f01..73b547b49fe 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/export_import/toc_i.yaml
@@ -11,4 +11,5 @@ items:
   href: s3_export.md
 - name: Загрузка из S3
   href: s3_import.md
-
+- name: Импорт данных из файла в существующую таблицу
+  href: import-file.md