Импорт данных из файла в существующую таблицу

С помощью подкоманды import file вы можете импортировать данные из файлов форматов CSV, JSON, Parquet, TSV в существующую таблицу.

При импорте файл читается пакетами, размер которых задан параметром --batch-bytes. Каждый пакет записывается в БД отдельным запросом. Запросы выполняются асинхронно. Когда число выполняемых запросов достигает указанного в --max-in-flight, чтение из файла приостанавливается. Вы можете импортировать данные из нескольких файлов одной командой. В этом случае данные из них будут читаться одновременно.

Импорт выполняется методом BulkUpsert, который обеспечивает высокоэффективную пакетную вставку большого количества строк без гарантий атомарности. Запись данных разбивается на несколько независимых транзакций, каждая их которых затрагивает единственную партицию, с параллельным исполнением. В случае успеха гарантируется вставка всех данных.

Если в таблице уже содержатся данные, они будут заменены импортируемыми при совпадении первичного ключа.

Импортируемый файл должен быть в кодировке UTF-8. Обработка переноса строки внутри поля данных не поддерживается.

Общий вид команды:

ydb [connection options] import file csv|json|parquet|tsv [options] <input files...>

, где [connection options] — опции соединения с БД

, <input files> — пути к файлам на локальной файловой системе, данные которых нужно импортировать.

Параметры подкоманды

Обязательные параметры

-p, --path STRING — путь к таблице в базе данных.

Дополнительные параметры

--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 — флаг гарантии отсутствия переносов строк внутри записей. Если данный флаг установлен, и загрузка производится из файла, то разные потоки загрузки будут работать с разными частями исходного файла. Это позволяет обеспечить максимальную производительность загрузки отсортированных датасетов в партицированные таблицы, за счет распределения нагрузки по всем партициям.

Примеры

Примечание

В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.

Перед выполнением примеров создайте таблицу series.

Импортировать файл

Файл содержит данные без дополнительной информации. В качестве разделителя используется символ ,:

1,Айтишники,The IT Crowd is a British sitcom.,13182
2,Silicon Valley,Silicon Valley is an American comedy television series.,16166

Примечание

Столбец release_date таблицы series имеет тип Date, поэтому дата релиза в файле для импорта представлена в виде числа. Чтобы импортировать значения в формате timestamp, используйте для них столбцы таблицы строкового типа, либо импортируйте их во временную таблицу и выполните преобразование к нужному типу.

Чтобы импортировать такой файл, выполните команду:

ydb import file csv -p series series.csv

В результате будут импортированы следующие данные:

┌──────────────┬───────────┬───────────────────────────────────────────────────────────┬──────────────────┐
| 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" |
└──────────────┴───────────┴───────────────────────────────────────────────────────────┴──────────────────┘

Импортировать несколько файлов

Следующие файлы содержат данные в формате CSV без дополнительной информации:

series1.csv:

1,Айтишники,The IT Crowd is a British sitcom.,13182

series2.csv:

2,Silicon Valley,Silicon Valley is an American comedy television series.,16166

Чтобы импортировать такие файлы, выполните команду:

ydb import file csv -p series series1.csv series2.csv

Импортировать файл с разделителем `|`

Файл содержит данные без дополнительной информации. В качестве разделителя используется символ |:

1|IT Crowd|The IT Crowd is a British sitcom.|13182
2|Silicon Valley|Silicon Valley is an American comedy television series.|16166

Чтобы импортировать такой файл, укажите параметр --delimiter со значением |:

ydb import file csv -p series --delimiter "|" series.csv

Пропустить строки и считать заголовки столбцов

Файл содержит дополнительную информацию в первой и второй строке, а также заголовки столбцов в третьей. Порядок данных в строках файла не соответствует порядку столбцов в таблице:

#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:

ydb import file csv -p series --skip-rows 2 --header series.csv

Заменить значения на `NULL`

Файл содержит часто используемое для NULL обозначение — \N, а также пустую строку.

1,Айтишники,The IT Crowd is a British sitcom.,13182
2,Silicon Valley,"",\N
3,Lost,,\N

Укажите параметр --null-value "\N", чтобы интерпретировать значение \N как NULL:

ydb import file csv -p series --null-value "\N" series.csv