--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ydb.tech/docs/en/reference/ydb-cli/export-import/import-file.md - https://ydb.tech/docs/ru/reference/ydb-cli/export-import/import-file.md sourcePath: ru/core/reference/ydb-cli/export-import/import-file.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Импорт данных из файла в существующую таблицу С помощью подкоманды `import file` вы можете импортировать данные из файлов форматов [CSV](https://ru.wikipedia.org/wiki/CSV), [JSON](https://ru.wikipedia.org/wiki/JSON), [Parquet](https://parquet.apache.org/docs/overview/), [TSV](https://ru.wikipedia.org/wiki/TSV) в существующую таблицу. При импорте файл читается пакетами, размер которых задан параметром `--batch-bytes`. Каждый пакет записывается в БД отдельным запросом. Запросы выполняются асинхронно. Когда число выполняемых запросов достигает указанного в `--max-in-flight`, чтение из файла приостанавливается. Вы можете импортировать данные из нескольких файлов одной командой. В этом случае данные из них будут читаться одновременно. Импорт выполняется методом `BulkUpsert`, который обеспечивает высокоэффективную пакетную вставку большого количества строк без гарантий атомарности. Запись данных разбивается на несколько независимых транзакций, каждая их которых затрагивает единственную партицию, с параллельным исполнением. В случае успеха гарантируется вставка всех данных. Если в таблице уже содержатся данные, они будут заменены импортируемыми при совпадении первичного ключа. Импортируемый файл должен быть в кодировке [UTF-8](https://ru.wikipedia.org/wiki/UTF-8). Обработка переноса строки внутри поля данных не поддерживается. {% note info %} Если таблица еще не создана, можно использовать команду [ydb tools infer csv](https://ydb.tech/docs/ru/reference/ydb-cli/tools-infer.md) для получения текста `CREATE TABLE` на основе имеющегося CSV-файла. При попытке выполнить импорт в несуществующую таблицу будет предложено выполнить [ydb tools infer csv](https://ydb.tech/docs/ru/reference/ydb-cli/tools-infer.md) с нужными опциями. {% endnote %} Общий вид команды: ```bash ydb [connection options] import file csv|json|parquet|tsv [options] ``` , где `[connection options]` — опции [соединения с БД](https://ydb.tech/docs/ru/reference/ydb-cli/connect.md#command-line-pars) , `` — пути к файлам на локальной файловой системе, данные которых нужно импортировать. ## Параметры подкоманды {#options} ### Обязательные параметры {#required} * `-p, --path STRING` — путь к таблице в базе данных. ### Дополнительные параметры {#optional} * `--timeout VAL` — время, в течение которого должна быть выполнена операция на сервере. Значение по умолчанию: `300s`. * `--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`. * `--threads VAL` — максимальное число потоков, выполняющих загрузку данных. Значение по умолчанию: число логических процессоров. * `--columns` — список имен столбцов данных в файле, разделенный `,` для формата `csv` или символом табуляции для формата `tsv`. Если указан параметр `--header`, переданные через него имена столбцов будут заменены именами из списка. Если число столбцов в списке не совпадает с числом столбцов в данных, будет выдана ошибка. * `--newline-delimited` — флаг гарантии отсутствия переносов строк внутри записей. Если данный флаг установлен, и загрузка производится из файла, то разные потоки загрузки будут работать с разными частями исходного файла. Это позволяет обеспечить максимальную производительность загрузки отсортированных датасетов в партицированные таблицы, за счет распределения нагрузки по всем партициям. ## Примеры {#examples} {% note info %} В примерах используется профиль `quickstart`, подробнее смотрите в [Создание профиля для соединения с тестовой БД](https://ydb.tech/docs/ru/reference/ydb-cli/profile/create.md#quickstart). {% endnote %} Перед выполнением примеров [создайте таблицу](https://ydb.tech/docs/ru/quickstart.md) `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](https://ydb.tech/docs/ru/yql/reference/types/primitive.md#datetime), поэтому дата релиза в файле для импорта представлена в виде числа. Чтобы импортировать значения в формате [timestamp](https://ru.wikipedia.org/wiki/ISO_8601), используйте для них столбцы таблицы строкового типа, либо импортируйте их во временную таблицу и выполните преобразование к нужному типу. {% endnote %} Чтобы импортировать такой файл, выполните команду: ```bash ydb import file csv -p series 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" | └──────────────┴───────────┴───────────────────────────────────────────────────────────┴──────────────────┘ ``` ### Импортировать несколько файлов {#multiple-files} Следующие файлы содержат данные в формате CSV без дополнительной информации: * series1.csv: ```text 1,Айтишники,The IT Crowd is a British sitcom.,13182 ``` * series2.csv: ```text 2,Silicon Valley,Silicon Valley is an American comedy television series.,16166 ``` Чтобы импортировать такие файлы, выполните команду: ```bash ydb import file csv -p series series1.csv series2.csv ``` ### Импортировать файл с разделителем `|` {#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 --delimiter "|" series.csv ``` ### Пропустить строки и считать заголовки столбцов {#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 --skip-rows 2 --header series.csv ``` ### Заменить значения на `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 --null-value "\N" series.csv ``` В результате будут импортированы следующие данные: ```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" | └──────────────┴───────────┴─────────────────────────────────────┴──────────────────┘ ```