Импорт данных из файла в существующую таблицу
С помощью подкоманды 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
В результате будут импортированы следующие данные:
┌──────────────┬───────────┬─────────────────────────────────────┬──────────────────┐
| 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" |
└──────────────┴───────────┴─────────────────────────────────────┴──────────────────┘