BROKER LOAD

Описание

Broker Load — это способ загрузки данных в Doris, предназначенный главным образом для загрузки больших объёмов данных из удалённых систем хранения, таких как HDFS или S3. Загрузка запускается через MySQL API и выполняется асинхронно. Ход и результаты загрузки можно проверить с помощью оператора SHOW LOAD.

В более ранних версиях S3 Load и HDFS Load зависели от процесса Broker. Теперь данные считываются непосредственно из источника данных без дополнительного процесса Broker. Тем не менее из-за схожего синтаксиса S3 Load, HDFS Load и Broker Load объединяют под общим названием Broker Load.

Синтаксис

LOAD LABEL [<db_name>.]<load_label>
(
[ { MERGE | APPEND | DELETE } ]
DATA INFILE
(
"<file_path>"[, ...]
)
[ NEGATIVE ]
INTO TABLE `<table_name>`
[ PARTITION ( <partition_name> [ , ... ] ) ]
[ COLUMNS TERMINATED BY "<column_separator>" ]
[ LINES TERMINATED BY "<line_delimiter>" ]
[ FORMAT AS "<file_type>" ]
[ COMPRESS_TYPE AS "<compress_type>" ]
[ (<column_list>) ]
[ COLUMNS FROM PATH AS (<column_name> [ , ... ] ) ]
[ SET (<column_mapping>) ]
[ PRECEDING FILTER <predicate> ]
[ WHERE <predicate> ]
[ DELETE ON <expr> ]
[ ORDER BY <source_sequence> ]
[ PROPERTIES ("<key>"="<value>" [, ...] ) ]
)
WITH BROKER "<broker_name>"
(   <broker_properties>
    [ , ... ])
[ PROPERTIES (
    <load_properties>
    [ , ... ]) ]
[COMMENT "<comment>" ];

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

1. <db_name>

Указывает имя базы данных для загрузки.

2. <load_label>

Для каждой задачи загрузки необходимо указать уникальную метку Label. Впоследствии по этой метке можно проверить ход выполнения задачи.

3. <table_name>

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

4. <file_path>

Указывает путь к файлу для загрузки. Можно указать несколько путей и использовать подстановочные символы. Путь должен в конечном итоге соответствовать файлу; если он соответствует только каталогу, загрузка завершится ошибкой.

5. <broker_name>

Указывает имя используемого сервиса Broker. Например, в Doris в публичном облаке сервис Broker называется bos.

6. <broker_properties>

Задаёт сведения, необходимые Broker. Обычно они используются для предоставления Broker доступа к удалённой системе хранения, такой как BOS или HDFS.

 (
     "username" = "user",
     "password" = "pass",
     ...
 )

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

1. merge | append | delete

Тип объединения данных. По умолчанию используется append, то есть обычная операция добавления данных. Типы merge и delete применимы только к таблицам с моделью уникального ключа. Тип merge необходимо использовать совместно с оператором [delete on] для обозначения столбца с флагом удаления. Тип delete означает, что все данные в этой загрузке предназначены для удаления.

2. negative

Задаёт «отрицательную» загрузку. Этот способ применим только к таблицам с агрегированными данными, в которых используется агрегация sum для целочисленных значений. Он меняет знак целочисленных значений в столбцах загружаемых данных, соответствующих столбцам с агрегацией sum, что позволяет компенсировать ошибочные данные.

3. <partition_name>

Указывает, что данные нужно загрузить только в определённые партиции таблицы, например: partition (p1, p2,...). Данные за пределами диапазона этих партиций будут проигнорированы.

4. <column_separator>

Задаёт разделитель столбцов. Применим только к формату CSV; допускаются только однобайтовые разделители.

5. <line_delimiter>

Задаёт разделитель строк. Применим только к формату CSV; допускаются только однобайтовые разделители.

6. <file_type>

Задаёт формат файла. Поддерживаются форматы csv (по умолчанию), parquet и orc.

7. <compress_type>

Задаёт тип сжатия файла. Поддерживаются gz, bz2 и lz4frame.

8. <column_list>

Задаёт порядок столбцов в исходном файле.

9. columns from path as (<c1>, <c2>,...)

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

10. <column_mapping>

Задаёт функцию преобразования столбцов.

11. preceding filter <predicate>

Сначала исходные строки данных формируются в соответствии с column list и columns from path as, затем фильтруются по условию предварительной фильтрации.

12. where <predicate>

Фильтрует загружаемые данные по заданному условию.

13. delete on <expr>

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

14. <source_sequence>

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

15. properties ("<key>"="<value>",...)

Задаёт параметры формата загружаемого файла. Применим к таким форматам, как CSV, JSON и другим. Например, можно задать параметры json_root, jsonpaths и fuzzy_parse.
enclose: символ обрамления. Если поле данных CSV содержит разделитель строк или столбцов, можно задать однобайтовый символ обрамления, чтобы предотвратить непреднамеренное разбиение поля. Например, если разделитель столбцов равен ",", символ обрамления равен "'", а данные имеют вид "a,'b,c'", то "b,c" будет обработано как одно поле.
Примечание: если для enclose задано значение ", для trim_double_quotes необходимо задать true.
escape: символ экранирования, используемый для экранирования символов внутри поля, совпадающих с символом обрамления. Например, если данные имеют вид "a,'b,'c'", символ обрамления равен "'", а "b,'c" нужно обработать как одно поле, необходимо указать однобайтовый символ экранирования, например "", а затем изменить данные на "a,'b,'c'".

16. <load_properties>

Ниже перечислены необязательные параметры, которые можно добавлять с учётом используемой среды.

Параметр	Описание параметра
timeout	Время ожидания завершения загрузки. По умолчанию составляет 4 часа, задаётся в секундах.
max_filter_ratio	Максимально допустимая доля отфильтрованных данных, например из-за некорректного формата. По умолчанию отфильтрованные данные не допускаются; диапазон значений от 0 до 1.
exec_mem_limit	Ограничение памяти для загрузки. По умолчанию составляет 2GB, задаётся в байтах.
strict_mode	Определяет, применяются ли к данным строгие ограничения. Значение по умолчанию: false.
partial_columns	Логический параметр. Значение true включает частичное обновление столбцов; значение по умолчанию: false. Можно задать только для таблиц модели Unique, использующих Merge on Write.
timezone	Задаёт часовой пояс, который влияет на зависящие от него функции, такие как strftime, alignment_timestamp, from_unixtime и другие. Подробнее см. в документации Часовой пояс. Если параметр не указан, используется "Asia/Shanghai".
load_parallelism	Параллелизм загрузки. Значение по умолчанию: 1. Увеличение параллелизма запускает несколько планов выполнения, которые одновременно выполняют задачу загрузки, ускоряя процесс.
send_batch_parallelism	Задаёт параллелизм отправки пакетов данных. Если значение превышает max_send_batch_parallelism_per_job в конфигурации BE, используется значение max_send_batch_parallelism_per_job.
load_to_single_tablet	Логический параметр. Значение true разрешает загрузку данных в один tablet соответствующей партиции; значение по умолчанию: false. Количество задач в задании зависит от общего параллелизма. Параметр можно задать только при загрузке в таблицу OLAP со случайным распределением по бакетам.
priority	Задаёт приоритет задачи загрузки. Допустимые значения: HIGH/NORMAL/LOW; значение по умолчанию: NORMAL. Среди задач загрузки в состоянии PENDING задачи с более высоким приоритетом первыми переходят в состояние LOADING.
comment	Задаёт комментарий к задаче загрузки.

Требования к правам доступа

Пользователи, выполняющие эту команду SQL, должны иметь как минимум следующие права:

Право	Объект	Примечания
LOAD_PRIV	Таблица	Право на загрузку данных в указанную таблицу базы данных.

Примеры

Полные примеры загрузки из S3 и HDFS, использования формата JSON и режима Merge, извлечения партиций из пути и других возможностей приведены в разделе Broker Load руководства по загрузке данных.