Загрузка данных из локальной файловой системы

Selena предоставляет два метода загрузки данных из локальной файловой системы:

• Синхронная загрузка с использованием Stream Load
• Асинхронная загрузка с использованием Broker Load

Каждый из этих вариантов имеет свои преимущества:

• Stream Load поддерживает форматы файлов CSV и JSON. Этот метод рекомендуется, если вы хотите загрузить данные из небольшого количества файлов, размер которых не превышает 10 ГБ.
• Broker Load поддерживает форматы файлов Parquet, ORC, CSV и JSON (формат JSON поддерживается начиная с версии 1.5.0). Этот метод рекомендуется, если вы хотите загрузить данные из большого количества файлов, размер которых превышает 10 ГБ, или если файлы хранятся на сетевом устройстве хранения (NAS). Использование Broker Load для загрузки данных из локальной файловой системы поддерживается начиная с версии 1.5.0.

Для данных CSV обратите внимание на следующие моменты:

• Вы можете использовать строку UTF-8, такую как запятая (,), табуляция или вертикальная черта (|), длина которой не превышает 50 байт, в качестве разделителя текста.
• Нулевые значения обозначаются с помощью \N. Например, файл данных состоит из трех столбцов, и запись из этого файла данных содержит данные в первом и третьем столбцах, но не содержит данных во втором столбце. В этой ситуации вам нужно использовать \N во втором столбце для обозначения нулевого значения. Это означает, что запись должна быть составлена как a,\N,b вместо a,,b. a,,b означает, что второй столбец записи содержит пустую строку.

Stream Load и Broker Load поддерживают преобразование данных при загрузке и поддерживают изменения данных, выполняемые операциями UPSERT и DELETE во время загрузки данных. Для получения дополнительной информации см. Преобразование данных при загрузке и Изменение данных через загрузку.

Перед началом работы

Проверка привилегий

Вы можете загружать данные в таблицы Selena только как пользователь, имеющий привилегию INSERT на эти таблицы Selena. Если у вас нет привилегии INSERT, следуйте инструкциям в GRANT, чтобы предоставить привилегию INSERT пользователю, которого вы используете для подключения к вашему кластеру Selena. Синтаксис: GRANT INSERT ON TABLE <table_name> IN DATABASE <database_name> TO { ROLE <role_name> | USER <user_identity>}.

Проверка конфигурации сети

Убедитесь, что машина, на которой находятся данные, которые вы хотите загрузить, может получить доступ к узлам FE и BE кластера Selena через http_port (по умолчанию: 8030) и be_http_port (по умолчанию: 8040) соответственно.

Загрузка из локальной файловой системы через Stream Load

Stream Load — это синхронный метод загрузки на основе HTTP PUT. После отправки задания загрузки Selena синхронно выполняет задание и возвращает результат задания после его завершения. Вы можете определить, было ли задание успешным, на основе результата задания.

УВЕДОМЛЕНИЕ

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

Как это работает

Вы можете отправить запрос на загрузку с вашего клиента на FE согласно HTTP, и FE затем использует HTTP-перенаправление для пересылки запроса на загрузку конкретному BE или CN. Вы также можете напрямую отправить запрос на загрузку с вашего клиента на выбранный вами BE или CN.

примечание

Если вы отправляете запросы на загрузку на FE, FE использует механизм опроса для определения того, какой BE или CN будет служить координатором для получения и обработки запросов на загрузку. Механизм опроса помогает достичь балансировки нагрузки в вашем кластере Selena. Поэтому мы рекомендуем отправлять запросы на загрузку на FE.

BE или CN, который получает запрос на загрузку, работает как Coordinator BE или CN для разделения данных на основе используемой схемы на части и назначения каждой части данных другим участвующим BE или CN. После завершения загрузки Coordinator BE или CN возвращает результат задания загрузки вашему клиенту. Обратите внимание, что если вы остановите Coordinator BE или CN во время загрузки, задание загрузки завершится неудачей.

На следующем рисунке показан рабочий процесс задания Stream Load.

Ограничения

Stream Load не поддерживает загрузку данных CSV-файла, содержащего столбец в формате JSON.

Типичный пример

В этом разделе используется curl в качестве примера для описания того, как загрузить данные CSV или JSON файла из вашей локальной файловой системы в Selena. Для подробного описания синтаксиса и параметров см. STREAM LOAD.

Обратите внимание, что в Selena некоторые литералы используются как зарезервированные ключевые слова языком SQL. Не используйте эти ключевые слова напрямую в SQL-операторах. Если вы хотите использовать такое ключевое слово в SQL-операторе, заключите его в пару обратных кавычек (`). См. Ключевые слова.

Загрузка данных CSV

Подготовка наборов данных

В вашей локальной файловой системе создайте CSV-файл с именем example1.csv. Файл состоит из трех столбцов, которые представляют ID пользователя, имя пользователя и оценку пользователя по порядку.

1,Lily,23
2,Rose,23
3,Alice,24
4,Julia,25

Создание базы данных и таблицы

Создайте базу данных и переключитесь на неё:

CREATE DATABASE IF NOT EXISTS mydatabase;
USE mydatabase;

Создайте таблицу Primary Key с именем table1. Таблица состоит из трех столбцов: id, name и score, где id является первичным ключом.

CREATE TABLE `table1`
(
    `id` int(11) NOT NULL COMMENT "user ID",
    `name` varchar(65533) NULL COMMENT "user name",
    `score` int(11) NOT NULL COMMENT "user score"
)
ENGINE=OLAP
PRIMARY KEY(`id`)
DISTRIBUTED BY HASH(`id`);

примечание

Начиная с версии 1.5.0, Selena может автоматически устанавливать количество корзин (BUCKETS) при создании таблицы или добавлении раздела. Вам больше не нужно вручную устанавливать количество корзин. Для получения подробной информации см. установка количества корзин.

Запуск Stream Load

Выполните следующую команду для загрузки данных из example1.csv в table1:

curl --location-trusted -u <username>:<password> -H "label:123" \
    -H "Expect:100-continue" \
    -H "column_separator:," \
    -H "columns: id, name, score" \
    -T example1.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/mydatabase/table1/_stream_load

примечание

• Если вы используете учетную запись, для которой не установлен пароль, вам нужно ввести только <username>:.
• Вы можете использовать SHOW FRONTENDS для просмотра IP-адреса и HTTP-порта узла FE.

example1.csv состоит из трех столбцов, которые разделены запятыми (,) и могут быть последовательно сопоставлены со столбцами id, name и score таблицы table1. Поэтому вам нужно использовать параметр column_separator для указания запятой (,) в качестве разделителя столбцов. Вам также нужно использовать параметр columns для временного именования трех столбцов example1.csv как id, name и score, которые последовательно сопоставляются с тремя столбцами table1.

После завершения загрузки вы можете запросить table1, чтобы убедиться, что загрузка прошла успешно:

SELECT * FROM table1;
+------+-------+-------+
| id   | name  | score |
+------+-------+-------+
|    1 | Lily  |    23 |
|    2 | Rose  |    23 |
|    3 | Alice |    24 |
|    4 | Julia |    25 |
+------+-------+-------+
4 rows in set (0.00 sec)

Загрузка данных JSON

Начиная с версии 1.5.0, Stream Load поддерживает сжатие данных JSON во время передачи, что снижает нагрузку на пропускную способность сети. Пользователи могут указывать различные алгоритмы сжатия, используя параметры compression и Content-Encoding. Поддерживаемые алгоритмы сжатия включают GZIP, BZIP2, LZ4_FRAME и ZSTD. Для синтаксиса см. STREAM LOAD.

Подготовка наборов данных

В вашей локальной файловой системе создайте JSON-файл с именем example2.json. Файл состоит из двух столбцов, которые представляют ID города и название города по порядку.

{"name": "Beijing", "code": 2}

Создание базы данных и таблицы

Создайте базу данных и переключитесь на неё:

CREATE DATABASE IF NOT EXISTS mydatabase;
USE mydatabase;

Создайте таблицу Primary Key с именем table2. Таблица состоит из двух столбцов: id и city, где id является первичным ключом.

CREATE TABLE `table2`
(
    `id` int(11) NOT NULL COMMENT "city ID",
    `city` varchar(65533) NULL COMMENT "city name"
)
ENGINE=OLAP
PRIMARY KEY(`id`)
DISTRIBUTED BY HASH(`id`);

примечание

Начиная с версии 1.5.0, Selena может автоматически устанавливать количество корзин (BUCKETS) при создании таблицы или добавлении раздела. Вам больше не нужно вручную устанавливать количество корзин. Для получения подробной информации см. установка количества корзин.

Запуск Stream Load

Выполните следующую команду для загрузки данных из example2.json в table2:

curl -v --location-trusted -u <username>:<password> -H "strict_mode: true" \
    -H "Expect:100-continue" \
    -H "format: json" -H "jsonpaths: [\"$.name\", \"$.code\"]" \
    -H "columns: city,tmp_id, id = tmp_id * 100" \
    -T example2.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/mydatabase/table2/_stream_load

примечание

• Если вы используете учетную запись, для которой не установлен пароль, вам нужно ввести только <username>:.
• Вы можете использовать SHOW FRONTENDS для просмотра IP-адреса и HTTP-порта узла FE.

example2.json состоит из двух ключей, name и code, которые сопоставляются со столбцами id и city таблицы table2, как показано на следующем рисунке.

Сопоставления, показанные на предыдущем рисунке, описываются следующим образом:

• Selena извлекает ключи name и code из example2.json и сопоставляет их с полями name и code, объявленными в параметре jsonpaths.

• Selena извлекает поля name и code, объявленные в параметре jsonpaths, и сопоставляет их по порядку с полями city и tmp_id, объявленными в параметре columns.

• Selena извлекает поля city и tmp_id, объявленные в параметре columns, и сопоставляет их по имени со столбцами city и id таблицы table2.

примечание

В предыдущем примере значение code в example2.json умножается на 100 перед загрузкой в столбец id таблицы table2.

Для подробных сопоставлений между jsonpaths, columns и столбцами таблицы Selena см. раздел "Сопоставления столбцов" в STREAM LOAD.

После завершения загрузки вы можете запросить table2, чтобы убедиться, что загрузка прошла успешно:

SELECT * FROM table2;
+------+--------+
| id   | city   |
+------+--------+
| 200  | Beijing|
+------+--------+
4 rows in set (0.01 sec)

Проверка прогресса Stream Load

После завершения задания загрузки Selena возвращает результат задания в формате JSON. Для получения дополнительной информации см. раздел "Возвращаемое значение" в STREAM LOAD.

Stream Load не позволяет запрашивать результат задания загрузки с помощью оператора SHOW LOAD.

Отмена задания Stream Load

Stream Load не позволяет отменить задание загрузки. Если задание загрузки истекает по времени или сталкивается с ошибками, Selena автоматически отменяет задание.

Конфигурации параметров

В этом разделе описываются некоторые системные параметры, которые вам нужно настроить, если вы выбираете метод загрузки Stream Load. Эти конфигурации параметров действуют на все задания Stream Load.

• streaming_load_max_mb: максимальный размер каждого файла данных, который вы хотите загрузить. Максимальный размер по умолчанию составляет 10 ГБ. Для получения дополнительной информации см. Настройка динамических параметров BE или CN.

  Мы рекомендуем не загружать более 10 ГБ данных за раз. Если размер файла данных превышает 10 ГБ, мы рекомендуем разделить файл данных на небольшие файлы размером менее 10 ГБ каждый, а затем загружать эти файлы один за другим. Если вы не можете разделить файл данных размером более 10 ГБ, вы можете увеличить значение этого параметра на основе размера файла.

  После увеличения значения этого параметра новое значение может вступить в силу только после перезапуска BE или CN вашего кластера Selena. Кроме того, производительность системы может ухудшиться, а затраты на повторные попытки в случае сбоев загрузки также увеличиваются.

  примечание

  При загрузке данных JSON-файла обратите внимание на следующие моменты:

  • Размер каждого JSON-объекта в файле не может превышать 4 ГБ. Если какой-либо JSON-объект в файле превышает 4 ГБ, Selena выдает ошибку "This parser can't support a document that big."

  • По умолчанию тело JSON в HTTP-запросе не может превышать 100 МБ. Если тело JSON превышает 100 МБ, Selena выдает ошибку "The size of this batch exceed the max size [104857600] of json type data data [8617627793]. Set ignore_json_size to skip check, although it may lead huge memory consuming." Чтобы предотвратить эту ошибку, вы можете добавить "ignore_json_size:true" в заголовок HTTP-запроса, чтобы игнорировать проверку размера тела JSON.

• stream_load_default_timeout_second: период тайм-аута каждого задания загрузки. Период тайм-аута по умолчанию составляет 600 секунд. Для получения дополнительной информации см. Настройка динамических параметров FE.

  Если многие из создаваемых вами заданий загрузки истекают по времени, вы можете увеличить значение этого параметра на основе результата расчета, который вы получаете из следующей формулы:

  Период тайм-аута каждого задания загрузки > Объем данных для загрузки/Средняя скорость загрузки

  Например, если размер файла данных, который вы хотите загрузить, составляет 10 ГБ, а средняя скорость загрузки вашего кластера Selena составляет 100 МБ/с, установите период тайм-аута более 100 секунд.

  примечание

  Средняя скорость загрузки в предыдущей формуле — это средняя скорость загрузки вашего кластера Selena. Она варьируется в зависимости от дискового ввода-вывода и количества BE или CN в вашем кластере Selena.

  Stream Load также предоставляет параметр timeout, который позволяет указать период тайм-аута отдельного задания загрузки. Для получения дополнительной информации см. STREAM LOAD.

Примечания по использованию

Если поле отсутствует для записи в файле данных, который вы хотите загрузить, и столбец, на который поле сопоставляется в вашей таблице Selena, определен как NOT NULL, Selena автоматически заполняет значение NULL в соответствующем столбце вашей таблицы Selena во время загрузки записи. Вы также можете использовать функцию ifnull() для указания значения по умолчанию, которое вы хотите заполнить.

Например, если поле, представляющее ID города в предыдущем файле example2.json, отсутствует, и вы хотите заполнить значение x в соответствующем столбце table2, вы можете указать "columns: city, tmp_id, id = ifnull(tmp_id, 'x')".

Загрузка из локальной файловой системы через Broker Load

В дополнение к Stream Load вы также можете использовать Broker Load для загрузки данных из локальной файловой системы. Эта функция поддерживается начиная с версии 1.5.0.

Broker Load — это асинхронный метод загрузки. После отправки задания загрузки Selena асинхронно выполняет задание и не возвращает результат задания немедленно. Вам нужно запросить результат задания вручную. См. Проверка прогресса Broker Load.

Ограничения

• В настоящее время Broker Load поддерживает загрузку из локальной файловой системы только через один брокер, версия которого v2.5 или более поздняя.
• Высококонкурентные запросы к одному брокеру могут вызвать проблемы, такие как тайм-аут и OOM. Чтобы смягчить воздействие, вы можете использовать переменную pipeline_dop (см. Системная переменная) для установки параллелизма запросов для Broker Load. Для запросов к одному брокеру мы рекомендуем установить pipeline_dop на значение меньше 16.

Типичный пример

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

Обратите внимание, что в Selena некоторые литералы используются как зарезервированные ключевые слова языком SQL. Не используйте эти ключевые слова напрямую в SQL-операторах. Если вы хотите использовать такое ключевое слово в SQL-операторе, заключите его в пару обратных кавычек (`). См. Ключевые слова.

Подготовка наборов данных

Используйте формат CSV-файла в качестве примера. Войдите в вашу локальную файловую систему и создайте два CSV-файла, file1.csv и file2.csv, в определенном месте хранения (например, /home/disk1/business/). Оба файла состоят из трех столбцов, которые представляют ID пользователя, имя пользователя и оценку пользователя по порядку.

• file1.csv

  1,Lily,21
  2,Rose,22
  3,Alice,23
  4,Julia,24

• file2.csv

  5,Tony,25
  6,Adam,26
  7,Allen,27
  8,Jacky,28

Создание базы данных и таблицы

Создайте базу данных и переключитесь на неё:

CREATE DATABASE IF NOT EXISTS mydatabase;
USE mydatabase;

Создайте таблицу Primary Key с именем mytable. Таблица состоит из трех столбцов: id, name и score, где id является первичным ключом.

CREATE TABLE `mytable`
(
    `id` int(11) NOT NULL COMMENT "User ID",
    `name` varchar(65533) NULL DEFAULT "" COMMENT "User name",
    `score` int(11) NOT NULL DEFAULT "0" COMMENT "User score"
)
ENGINE=OLAP
PRIMARY KEY(`id`)
DISTRIBUTED BY HASH(`id`)
PROPERTIES("replication_num"="1");

Запуск Broker Load

Выполните следующую команду для запуска задания Broker Load, которое загружает данные из всех файлов данных (file1.csv и file2.csv), хранящихся в пути /home/disk1/business/ вашей локальной файловой системы, в таблицу Selena mytable:

LOAD LABEL mydatabase.label_local
(
    DATA INFILE("file:///home/disk1/business/csv/*")
    INTO TABLE mytable
    COLUMNS TERMINATED BY ","
    (id, name, score)
)
WITH BROKER "sole_broker"
PROPERTIES
(
    "timeout" = "3600"
);

Это задание имеет четыре основных раздела:

• LABEL: Строка, используемая при запросе состояния задания загрузки.
• Объявление LOAD: Исходный URI, формат исходных данных и имя целевой таблицы.
• PROPERTIES: Значение тайм-аута и любые другие свойства для применения к заданию загрузки.

Для подробного описания синтаксиса и параметров см. BROKER LOAD.

Проверка прогресса Broker Load

В версиях v3.0 и более ранних используйте оператор SHOW LOAD или команду curl для просмотра прогресса заданий Broker Load.

В версиях v3.1 и более поздних вы можете просматривать прогресс заданий Broker Load из представления information_schema.loads:

SELECT * FROM information_schema.loads;

Если вы отправили несколько заданий загрузки, вы можете фильтровать по LABEL, связанному с заданием. Пример:

SELECT * FROM information_schema.loads WHERE LABEL = 'label_local';

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

SELECT * FROM mytable;
+------+-------+-------+
| id   | name  | score |
+------+-------+-------+
|    3 | Alice |    23 |
|    5 | Tony  |    25 |
|    6 | Adam  |    26 |
|    1 | Lily  |    21 |
|    2 | Rose  |    22 |
|    4 | Julia |    24 |
|    7 | Allen |    27 |
|    8 | Jacky |    28 |
+------+-------+-------+
8 rows in set (0.07 sec)

Отмена задания Broker Load

Когда задание загрузки не находится в стадии CANCELLED или FINISHED, вы можете использовать оператор CANCEL LOAD для отмены задания.

Например, вы можете выполнить следующий оператор для отмены задания загрузки с меткой label_local в базе данных mydatabase:

CANCEL LOAD
FROM mydatabase
WHERE LABEL = "label_local";

Загрузка из NAS через Broker Load

Существует два способа загрузки данных из NAS с использованием Broker Load:

• Рассматривать NAS как локальную файловую систему и выполнять задание загрузки с брокером. См. предыдущий раздел "Загрузка из локальной системы через Broker Load".
• (Рекомендуется) Рассматривать NAS как систему облачного хранения и выполнять задание загрузки без брокера.

В этом разделе представлен второй способ. Подробные операции следующие:

1. Смонтируйте ваше устройство NAS по одному и тому же пути на всех узлах BE или CN и узлах FE вашего кластера Selena. Таким образом, все BE или CN могут получить доступ к устройству NAS так же, как они получают доступ к своим локально хранящимся файлам.

2. Используйте Broker Load для загрузки данных с устройства NAS в целевую таблицу Selena. Пример:

   LOAD LABEL test_db.label_nas
   (
       DATA INFILE("file:///home/disk1/sr/*")
       INTO TABLE mytable
       COLUMNS TERMINATED BY ","
   )
   WITH BROKER
   PROPERTIES
   (
       "timeout" = "3600"
   );

   Это задание имеет четыре основных раздела:

   • LABEL: Строка, используемая при запросе состояния задания загрузки.
   • Объявление LOAD: Исходный URI, формат исходных данных и имя целевой таблицы. Обратите внимание, что DATA INFILE в объявлении используется для указания пути к папке точки монтирования устройства NAS, как показано в приведенном выше примере, где file:/// является префиксом, а /home/disk1/sr — путем к папке точки монтирования.
   • BROKER: Вам не нужно указывать имя брокера.
   • PROPERTIES: Значение тайм-аута и любые другие свойства для применения к заданию загрузки.

   Для подробного описания синтаксиса и параметров см. BROKER LOAD.

После отправки задания вы можете просмотреть прогресс загрузки или отменить задание по мере необходимости. Для подробных операций см. "Проверка прогресса Broker Load" и "Отмена задания Broker Load в этой теме.