Перейти к содержимому
Последнее обновление

MySQL Load

Doris совместим с протоколом MySQL, поэтому для импорта локальных файлов можно использовать стандартный синтаксис MySQL LOAD DATA. MySQL Load представляет собой синхронный способ импорта: результат возвращается сразу после завершения импорта, а по возвращаемому значению оператора LOAD DATA можно определить, успешно ли он выполнен.

Как правило, MySQL Load можно использовать для импорта файлов размером менее 10 GB. Если файл слишком большой, сначала разделите его на части, а затем импортируйте их с помощью MySQL Load. MySQL Load гарантирует атомарность задания пакетного импорта: либо все строки успешно импортируются, либо не импортируется ни одна.

Сценарии использования​

Подходящие сценарии​

MySQL Load предназначен прежде всего для следующих сценариев:

  • Импорт локальных CSV-файлов с клиента в Doris.
  • Импорт данных из потока данных с помощью программы.

Ограничения​

При импорте CSV-файлов необходимо чётко различать неопределённые значения (null) и пустые строки (''):

Тип данныхПредставлениеПример данныхОписание
Неопределённое значение (null)\Na,\N,bСредний столбец содержит значение null.
Пустая строкаОставьте поле пустымa, ,bСредний столбец содержит пустую строку.

Основные принципы​

По своим возможностям MySQL Load похож на Stream Load: оба способа позволяют импортировать локальные файлы в кластер Doris. Поэтому реализация MySQL Load использует базовые возможности импорта Stream Load.

Основной процесс выполнения MySQL Load выглядит следующим образом:

  1. Пользователь отправляет запрос LOAD DATA в FE. FE разбирает запрос и преобразует его в запрос Stream Load.
  2. FE выбирает узел BE и отправляет запрос Stream Load.
  3. Во время отправки запроса FE асинхронно считывает данные локального файла с клиента MySQL в потоковом режиме и в реальном времени передаёт их в HTTP-запрос Stream Load.
  4. После того как клиент MySQL завершает передачу данных, FE ожидает завершения Stream Load и возвращает клиенту информацию об успехе или ошибке импорта.

Быстрый старт​

Предварительные проверки​

Перед запуском MySQL Load убедитесь, что выполнены следующие условия:

  • У текущего пользователя есть право INSERT для целевой таблицы. Если права INSERT нет, его можно предоставить командой GRANT.

Создание задания импорта​

Чтобы выполнить полный импорт с помощью MySQL Load, выполните следующие четыре шага.

1. Подготовьте тестовые данные​

Создайте файл с именем client_local.csv, содержащий следующие тестовые данные:

1,10
2,20
3,30
4,40
5,50
6,60

2. Подключите клиент​

Перед выполнением команды LOAD DATA подключитесь с помощью клиента MySQL:

mysql --local-infile  -h <fe_ip> -P <fe_query_port> -u root -D testdb
предупреждение

При использовании MySQL Load подключение клиента должно включать указанные параметры:

  1. При подключении с помощью клиента MySQL необходимо указать параметр --local-infile, иначе может возникнуть ошибка.
  2. При подключении через JDBC необходимо указать allowLoadLocalInfile=true в URL.

3. Создайте тестовую таблицу​

Создайте в Doris следующую таблицу:

CREATE TABLE testdb.t1 (
    pk     INT, 
    v1     INT SUM
) AGGREGATE KEY (pk) 
DISTRIBUTED BY hash (pk);

4. Выполните команду импорта LOAD DATA​

После подключения клиента MySQL создайте задание импорта следующей командой:

LOAD DATA LOCAL
INFILE 'client_local.csv'
INTO TABLE testdb.t1
COLUMNS TERMINATED BY ','
LINES TERMINATED BY '\n';

Просмотр результата задания импорта​

MySQL Load представляет собой синхронный способ импорта, поэтому результат возвращается пользователю непосредственно в командной строке. При сбое импорта выводится конкретное сообщение об ошибке.

При успешном импорте возвращается количество импортированных строк:

Query OK, 6 rows affected (0.17 sec)
Records: 6  Deleted: 0  Skipped: 0  Warnings: 0

При сбое импорта клиент выводит соответствующую ошибку:

ERROR 1105 (HY000): errCode = 2, detailMessage = [DATA_QUALITY_ERROR]too many filtered rows with load id b612907c-ccf4-4ac2-82fe-107ece655f0f

Сообщение об ошибке содержит loadId этого импорта. Для просмотра подробностей можно использовать команду show load warnings:

show load warnings where label='b612907c-ccf4-4ac2-82fe-107ece655f0f';

Отмена задания импорта​

Пользователи не могут вручную отменить импорт MySQL Load. Система автоматически отменяет MySQL Load при превышении времени ожидания или возникновении ошибки импорта.

Справочная информация​

Синтаксис импорта​

Полный синтаксис LOAD DATA:

LOAD DATA LOCAL
INFILE '<load_data_file>'
INTO TABLE [<db_name>.]<table_name>
[PARTITION (partition_name [, partition_name] ...)]
[COLUMNS TERMINATED BY '<column_terminated_operator>']
[LINES TERMINATED BY '<line_terminated_operator>']
[IGNORE <ignore_lines> LINES]
[(col_name_or_user_var[, col_name_or_user_var] ...)]
[SET col_name={expr | DEFAULT}[, col_name={expr | DEFAULT}] ...]
[PROPERTIES (key1 = value1 [, key2=value2]) ]

Описание каждой конструкции приведено ниже:

КонструкцияОписание
INFILEЗадаёт путь к локальному файлу. Путь может быть относительным или абсолютным. В настоящее время load_data_file поддерживает импорт только одного файла.
INTO TABLEЗадаёт имя базы данных и имя таблицы. Имя базы данных можно опустить.
PARTITIONЗадаёт партиции для импорта. Если можно определить, к какой партиции относится каждая строка, рекомендуется указать партиции явно. Строки, не соответствующие этим партициям, отфильтровываются.
COLUMNS TERMINATED BYЗадаёт разделитель столбцов для импорта.
LINES TERMINATED BYЗадаёт разделитель строк для импорта.
IGNORE num LINESЗадаёт количество строк, которые нужно пропустить в импортируемом CSV. Обычно указывается 1, чтобы пропустить заголовок.
col_name_or_user_varЗадаёт синтаксис сопоставления столбцов. О преобразовании данных см. раздел Сопоставление столбцов.
PROPERTIESПараметры импорта.

Параметры импорта​

Синтаксис PROPERTIES (key1 = value1 [, key2=value2]) позволяет задавать параметры импорта:

ПараметрОписание
max_filter_ratioМаксимально допустимая доля отфильтрованных строк. Должна находиться в диапазоне от 0 до 1 включительно. Значение по умолчанию: 0, то есть строки с ошибками не допускаются.
timeoutВремя ожидания завершения импорта в секундах. По умолчанию: 600 секунд. Допустимый диапазон: от 1s до 259200s.
strict_modeОпределяет, включён ли строгий режим для этого импорта. По умолчанию отключён.
timezoneЧасовой пояс, используемый при импорте. По умолчанию используется текущий часовой пояс кластера. Этот параметр влияет на результаты всех функций, связанных с часовыми поясами и используемых при импорте.
exec_mem_limitОграничение памяти для импорта. Значение по умолчанию: 2 GB. Единица измерения: байты.
trim_double_quotesЛогический тип. Значение по умолчанию: false. При значении true у каждого поля в импортируемом файле удаляются внешние двойные кавычки.
encloseЗадаёт символ обрамления. Если поля CSV содержат разделитель строк или столбцов, можно указать однобайтовый символ обрамления, чтобы предотвратить непреднамеренное усечение данных. Например, если разделитель столбцов имеет вид ,, символ обрамления имеет вид ', а данные имеют вид a,'b,c', то b,c разбирается как одно поле.
escapeЗадаёт символ экранирования. Используется для экранирования символов в полях, совпадающих с символом обрамления. Например, если данные имеют вид a,'b,'c', в качестве символа обрамления используется ', а b,'c должно разбираться как одно поле, необходимо указать однобайтовый символ экранирования, например \, и изменить данные на a,'b,\'c'.

Примеры импорта​

Следующие примеры охватывают распространённые сценарии импорта.

Указание времени ожидания завершения импорта​

Параметр PROPERTIES timeout позволяет настроить время ожидания завершения импорта. В следующем примере устанавливается время ожидания 100 секунд:

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
PROPERTIES ("timeout"="100");

Указание допустимой доли ошибок импорта​

Параметр PROPERTIES max_filter_ratio позволяет настроить допустимую долю ошибок импорта. В следующем примере устанавливается допустимая доля ошибок 20%:

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
PROPERTIES ("max_filter_ratio"="0.2");

Сопоставление столбцов при импорте​

В следующем примере изменяется порядок столбцов в CSV:

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
(k2, k1, v1);

Указание разделителей столбцов и строк​

Конструкции COLUMNS TERMINATED BY и LINES TERMINATED BY задают разделители столбцов и строк для импорта. В следующем примере в качестве разделителя столбцов используется запятая (,), а в качестве разделителя строк используется символ новой строки (\n):

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
COLUMNS TERMINATED BY ','
LINES TERMINATED BY '\n';

Указание партиций для импорта​

Конструкция PARTITION задаёт партиции для импорта. В следующем примере данные импортируются в партиции p1 и p2. Данные, не относящиеся к партициям p1 или p2, отфильтровываются:

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
PARTITION (p1, p2);

Указание часового пояса для импорта​

Параметр PROPERTIES timezone задаёт часовой пояс. В следующем примере устанавливается часовой пояс Africa/Abidjan:

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
PROPERTIES ("timezone"="Africa/Abidjan");

Ограничение памяти для импорта​

Параметр PROPERTIES exec_mem_limit задаёт ограничение памяти для импорта. В следующем примере устанавливается ограничение памяти для импорта 10 GB:

LOAD DATA LOCAL
INFILE 'testData'
INTO TABLE testDb.testTbl
PROPERTIES ("exec_mem_limit"="10737418240");

Часто задаваемые вопросы​

Вопрос 1: При выполнении LOAD DATA появляется ошибка The used command is not allowed with this MySQL version. Что делать?​

Обычно эта ошибка возникает, если на клиенте не включён параметр local-infile. Выполните следующие действия:

  • Подключение из командной строки: явно добавьте параметр --local-infile при подключении.
  • Подключение через JDBC: добавьте allowLoadLocalInfile=true в URL.

Вопрос 2: Файлы какого размера можно импортировать с помощью MySQL Load?​

Рекомендуется импортировать файлы размером менее 10 GB. Если файл слишком большой, сначала разделите его на части, а затем импортируйте их с помощью MySQL Load.

Вопрос 3: Поддерживает ли MySQL Load отмену вручную?​

Нет. Система автоматически отменяет MySQL Load при превышении времени ожидания или возникновении ошибки импорта.

Вопрос 4: Как определить конкретную причину сбоя импорта?​

Получите loadId из сообщения об ошибке, затем выполните следующую команду для просмотра подробной информации об ошибке:

show load warnings where label='<loadId>';

Вопрос 5: Как различать значения null и пустые строки в CSV?​

  • Неопределённое значение (null): используйте \N, например a,\N,b.
  • Пустая строка: оставьте поле пустым, например a, ,b.

Вопрос 6: Гарантирует ли импорт атомарность?​

Да. MySQL Load гарантирует атомарность задания пакетного импорта: либо все строки успешно импортируются, либо не импортируется ни одна.

Дополнительная информация​

Подробный синтаксис и рекомендации по использованию MySQL Load приведены в справочнике команды MySQL Load.

Report issue
На этой странице