Перейти к основному содержимому
Версия: 2.0.x

STREAM LOAD

Selena предоставляет метод загрузки на основе HTTP — STREAM LOAD, который помогает загружать данные из локальной файловой системы или из источника потоковых данных. После отправки загрузочного задания Selena синхронно выполняет задание и возвращает результат задания после его завершения. Вы можете определить, было ли задание успешным, на основе результата задания. Для получения информации о сценариях применения, ограничениях, принципах и поддерживаемых форматах файлов данных Stream Load см. Loading from a local file system via Stream Load.

подсказка

Для быстрого старта с Selena см. раздел Быстрый старт.

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

Начиная с версии 3.4.0, система поддерживает объединение нескольких запросов Stream Load. Для получения дополнительной информации см. Параметры Merge Commit.

ПРИМЕЧАНИЕ

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

Синтаксис​

curl --location-trusted -u <username>:<password> -XPUT <url>
(
    data_desc
)
[opt_properties]

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

  • Вы можете использовать chunked transfer encoding, как показано в этом разделе. Если вы не выбираете chunked transfer encoding, вы должны ввести поле заголовка Content-Length, чтобы указать длину содержимого, которое необходимо передать, тем самым обеспечивая целостность данных.

    ПРИМЕЧАНИЕ

    Если вы используете curl для выполнения Stream Load, Selena автоматически добавляет поле заголовка Content-Length, и вам не нужно вводить его вручную.

  • Вы должны добавить поле заголовка Expect и указать его значение как 100-continue, как в "Expect:100-continue". Это помогает предотвратить ненужные передачи данных и снизить потребление ресурсов в случае отклонения вашего запроса на задание.

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

Параметры​

username и password​

Укажите имя пользователя и пароль учетной записи, которую вы используете для подключения к вашему кластеру Selena. Это обязательный параметр. Если вы используете учетную запись, для которой не установлен пароль, вам нужно ввести только <username>:.

XPUT​

Указывает метод HTTP-запроса. Это обязательный параметр. Stream Load поддерживает только метод PUT.

url​

Указывает URL-адрес таблицы Selena. Синтаксис:

http://<fe_host>:<fe_http_port>/api/<database_name>/<table_name>/_stream_load

В следующей таблице описываются параметры в URL.

ПараметрОбязательныйОписание
fe_hostДаIP-адрес узла FE в вашем кластере Selena.
ПРИМЕЧАНИЕ
Если вы отправляете загрузочное задание на конкретный узел BE или CN, вы должны ввести IP-адрес узла BE или CN.
fe_http_portДаНомер порта HTTP узла FE в вашем кластере Selena. Номер порта по умолчанию — 8030.
ПРИМЕЧАНИЕ
Если вы отправляете загрузочное задание на конкретный узел BE или CN, вы должны ввести номер порта HTTP узла BE или CN. Номер порта по умолчанию — 8030.
database_nameДаИмя базы данных, к которой принадлежит таблица Selena.
table_nameДаИмя таблицы Selena.

ПРИМЕЧАНИЕ

Вы можете использовать SHOW FRONTENDS для просмотра IP-адреса и порта HTTP узла FE.

data_desc​

Описывает файл данных, который вы хотите загрузить. Дескриптор data_desc может включать имя файла данных, формат, разделитель столбцов, разделитель строк, целевые partition и сопоставление столбцов с таблицей Selena. Синтаксис:

-T <file_path>
-H "format: CSV | JSON"
-H "column_separator: <column_separator>"
-H "row_delimiter: <row_delimiter>"
-H "columns: <column1_name>[, <column2_name>, ... ]"
-H "partitions: <partition1_name>[, <partition2_name>, ...]"
-H "temporary_partitions: <temporary_partition1_name>[, <temporary_partition2_name>, ...]"
-H "jsonpaths: [ \"<json_path1>\"[, \"<json_path2>\", ...] ]"
-H "strip_outer_array: true | false"
-H "json_root: <json_path>"
-H "ignore_json_size: true | false"
-H "compression: <compression_algorithm> | Content-Encoding: <compression_algorithm>"

Параметры в дескрипторе data_desc можно разделить на три типа: общие параметры, параметры CSV и параметры JSON.

Общие параметры​

ПараметрОбязательныйОписание
file_pathДаПуть сохранения файла данных. При желании вы можете включить расширение имени файла.
formatНетФормат файла данных. Допустимые значения: CSV и JSON. Значение по умолчанию: CSV.
partitionsНетPartition, в которые вы хотите загрузить файл данных. По умолчанию, если вы не укажете этот параметр, Selena загружает файл данных во все partition таблицы Selena.
temporary_partitionsНетИмя временного partition, в который вы хотите загрузить файл данных. Вы можете указать несколько временных partition, которые должны быть разделены запятыми (,).
columnsНетСопоставление столбцов между файлом данных и таблицей Selena.
Если поля в файле данных могут быть последовательно сопоставлены со столбцами в таблице Selena, вам не нужно указывать этот параметр. Вместо этого вы можете использовать этот параметр для выполнения преобразований данных. Например, если вы загружаете файл данных CSV, и файл состоит из двух столбцов, которые могут быть последовательно сопоставлены с двумя столбцами id и city таблицы Selena, вы можете указать "columns: city,tmp_id, id = tmp_id * 100". Для получения дополнительной информации см. раздел "Сопоставление столбцов" в этом разделе.

Параметры CSV​

ПараметрОбязательныйОписание
column_separatorНетСимволы, которые используются в файле данных для разделения полей. Если вы не укажете этот параметр, этот параметр по умолчанию равен \t, что указывает на табуляцию.
Убедитесь, что разделитель столбцов, который вы указываете с помощью этого параметра, совпадает с разделителем столбцов, используемым в файле данных.
ПРИМЕЧАНИЕ
- Для данных CSV вы можете использовать строку UTF-8, такую как запятая (,), табуляция или вертикальная черта (|), длина которой не превышает 50 байт, в качестве текстового разделителя.
- Если файл данных использует последовательные непечатаемые символы (например, \r\n) в качестве разделителя столбцов, вы должны установить этот параметр как \\x0D0A.
row_delimiterНетСимволы, которые используются в файле данных для разделения строк. Если вы не укажете этот параметр, этот параметр по умолчанию равен \n.
ПРИМЕЧАНИЕ
Если файл данных использует последовательные непечатаемые символы (например, \r\n) в качестве разделителя строк, вы должны установить этот параметр как \\x0D0A.
skip_headerНетУказывает, следует ли пропускать первые несколько строк файла данных, когда файл данных в формате CSV. Тип: INTEGER. Значение по умолчанию: 0.
В некоторых файлах данных в формате CSV первые несколько строк в начале используются для определения метаданных, таких как имена столбцов и типы данных столбцов. Установив параметр skip_header, вы можете включить Selena для пропуска первых нескольких строк файла данных во время загрузки данных. Например, если вы установите этот параметр в 1, Selena пропустит первую строку файла данных во время загрузки данных.
Первые несколько строк в начале в файле данных должны быть разделены с помощью разделителя строк, который вы указываете в команде загрузки.
trim_spaceНетУказывает, следует ли удалять пробелы перед и после разделителей столбцов из файла данных, когда файл данных в формате CSV. Тип: BOOLEAN. Значение по умолчанию: false.
Для некоторых баз данных пробелы добавляются к разделителям столбцов при экспорте данных в виде файла данных в формате CSV. Такие пробелы называются начальными или конечными пробелами в зависимости от их расположения. Установив параметр trim_space, вы можете включить Selena для удаления таких ненужных пробелов во время загрузки данных.
Обратите внимание, что Selena не удаляет пробелы (включая начальные и конечные пробелы) внутри поля, заключенного в пару символов, указанных в enclose. Например, следующие значения полей используют вертикальную черту (|) в качестве разделителя столбцов и двойные кавычки (") в качестве символа, указанного в enclose:
|"Love Selena"|
|" Love Selena "|
| "Love Selena" |
Если вы установите trim_space в true, Selena обрабатывает предыдущие значения полей следующим образом:
|"Love Selena"|
|" Love Selena "|
|"Love Selena"|
encloseНетУказывает символ, который используется для обертывания значений полей в файле данных в соответствии с RFC4180, когда файл данных в формате CSV. Тип: однобайтовый символ. Значение по умолчанию: NONE. Наиболее распространенными символами являются одинарная кавычка (') и двойная кавычка (").
Все специальные символы (включая разделители строк и разделители столбцов), обернутые с помощью символа, указанного в enclose, считаются обычными символами. Selena может сделать больше, чем RFC4180, поскольку позволяет вам указать любой однобайтовый символ в качестве символа, указанного в enclose.
Если значение поля содержит символ, указанный в enclose, вы можете использовать тот же символ для экранирования этого символа, указанного в enclose. Например, вы устанавливаете enclose в ", и значение поля — a "quoted" c. В этом случае вы можете ввести значение поля как "a ""quoted"" c" в файл данных.
escapeНетУказывает символ, который используется для экранирования различных специальных символов, таких как разделители строк, разделители столбцов, символы экранирования и символы, указанные в enclose, которые затем считаются Selena обычными символами и анализируются как часть значений полей, в которых они находятся. Тип: однобайтовый символ. Значение по умолчанию: NONE. Наиболее распространенным символом является косая черта (\), которая должна быть записана как двойные косые черты (\\) в операторах SQL.
ПРИМЕЧАНИЕ
Символ, указанный в escape, применяется как внутри, так и вне каждой пары символов, указанных в enclose.
Два примера следующие:
  • Когда вы устанавливаете enclose в " и escape в \, Selena анализирует "say \"Hello world\"" в say "Hello world".
  • Предположим, что разделитель столбцов — запятая (,). Когда вы устанавливаете escape в \, Selena анализирует a, b\, c в два отдельных значения полей: a и b, c.

ПРИМЕЧАНИЕ

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

Параметры JSON​

ПараметрОбязательныйОписание
jsonpathsНетИмена ключей, которые вы хотите загрузить из файла данных JSON. Вам нужно указать этот параметр только при загрузке данных JSON с использованием режима сопоставления. Значение этого параметра в формате JSON. См. Настройка сопоставления столбцов для загрузки данных JSON.
strip_outer_arrayНетУказывает, следует ли удалять самую внешнюю структуру массива. Допустимые значения: true и false. Значение по умолчанию: false.
В реальных бизнес-сценариях данные JSON могут иметь самую внешнюю структуру массива, обозначенную парой квадратных скобок []. В этой ситуации мы рекомендуем установить этот параметр в true, чтобы Selena удаляла самые внешние квадратные скобки [] и загружала каждый внутренний массив как отдельную запись данных. Если вы установите этот параметр в false, Selena анализирует весь файл данных JSON в один массив и загружает массив как одну запись данных.
Например, данные JSON — [ {"category" : 1, "author" : 2}, {"category" : 3, "author" : 4} ]. Если вы установите этот параметр в true, {"category" : 1, "author" : 2} и {"category" : 3, "author" : 4} анализируются в отдельные записи данных, которые загружаются в отдельные строки таблицы Selena.
json_rootНетКорневой элемент данных JSON, которые вы хотите загрузить из файла данных JSON. Вам нужно указать этот параметр только при загрузке данных JSON с использованием режима сопоставления. Значение этого параметра — действительная строка JsonPath. По умолчанию значение этого параметра пусто, что указывает на то, что все данные из файла данных JSON будут загружены. Для получения дополнительной информации см. раздел "Загрузка данных JSON с использованием режима сопоставления с указанным корневым элементом" этого раздела.
ignore_json_sizeНетУказывает, следует ли проверять размер тела JSON в HTTP-запросе.
ПРИМЕЧАНИЕ
По умолчанию размер тела JSON в HTTP-запросе не может превышать 100 МБ. Если тело JSON превышает 100 МБ в размере, возникает ошибка "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-запроса, чтобы указать Selena не проверять размер тела JSON.
compression, Content-EncodingНЕТАлгоритм кодирования, который применяется к данным во время передачи. Поддерживаемые алгоритмы включают GZIP, BZIP2, LZ4_FRAME и ZSTD. Пример: curl --location-trusted -u root: -v 'http://127.0.0.1:18030/api/db0/tbl_simple/_stream_load' \-X PUT -H "expect:100-continue" \-H 'format: json' -H 'compression: lz4_frame' -T ./b.json.lz4.

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

Параметры Merge Commit​

Включает Merge Commit для нескольких параллельных запросов Stream Load в пределах указанного временного окна и объединяет их в одну транзакцию.

warning

Обратите внимание, что оптимизация Merge Commit подходит для сценария с параллельными заданиями Stream Load на одной таблице. Она не рекомендуется, если параллелизм равен единице. В то же время дважды подумайте, прежде чем устанавливать merge_commit_async в false и merge_commit_interval_ms в большое значение, поскольку они могут привести к снижению производительности загрузки.

ПараметрОбязательныйОписание
enable_merge_commitНетВключить ли Merge Commit для запроса на загрузку. Допустимые значения: true и false (по умолчанию).
merge_commit_asyncНетРежим возврата сервера. Допустимые значения:
  • true: Включает асинхронный режим, где сервер возвращается немедленно после получения данных. Этот режим не гарантирует успешную загрузку.
  • false(по умолчанию): Включает синхронный режим, где сервер возвращается только после фиксации объединенной транзакции, гарантируя успешную загрузку и видимость.
merge_commit_interval_msДаРазмер окна слияния времени. Единица измерения: миллисекунды. Merge Commit пытается объединить запросы на загрузку, полученные в этом окне, в одну транзакцию. Большее окно повышает эффективность слияния, но увеличивает задержку.
merge_commit_parallelДаСтепень параллелизма для плана загрузки, созданного для каждого окна слияния. Параллелизм можно настроить на основе нагрузки на прием. Увеличьте это значение, если много запросов и/или большое количество данных для загрузки. Параллелизм ограничен количеством узлов BE, рассчитывается как min(merge_commit_parallel, количество узлов BE).
примечание
  • Merge Commit поддерживает объединение только однородных запросов на загрузку в одну базу данных и таблицу. "Однородные" означает, что параметры Stream Load идентичны, включая: общие параметры, параметры формата JSON, параметры формата CSV, opt_properties и параметры Merge Commit.
  • Для загрузки данных в формате CSV вы должны убедиться, что каждая строка заканчивается разделителем строк. skip_header не поддерживается.
  • Сервер автоматически генерирует метки для транзакций. Они будут проигнорированы, если указаны.
  • Merge Commit объединяет несколько запросов на загрузку в одну транзакцию. Если один запрос содержит проблемы с качеством данных, все запросы в транзакции завершатся неудачей.

opt_properties​

Указывает некоторые необязательные параметры, которые применяются ко всему загрузочному заданию. Синтаксис:

-H "label: <label_name>"
-H "where: <condition1>[, <condition2>, ...]"
-H "max_filter_ratio: <num>"
-H "timeout: <num>"
-H "strict_mode: true | false"
-H "timezone: <string>"
-H "load_mem_limit: <num>"
-H "partial_update: true | false"
-H "partial_update_mode: row | column"
-H "merge_condition: <column_name>"

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

ПараметрОбязательныйОписание
labelНетМетка загрузочного задания. Если вы не укажете этот параметр, Selena автоматически сгенерирует метку для загрузочного задания.
Selena не позволяет использовать одну метку для многократной загрузки партии данных. Таким образом, Selena предотвращает повторную загрузку одних и тех же данных. Для правил именования меток см. System limits.
По умолчанию Selena сохраняет метки загрузочных заданий, которые были успешно завершены за последние три дня. Вы можете использовать параметр FE label_keep_max_second для изменения периода хранения меток.
whereНетУсловия, на основе которых Selena фильтрует предварительно обработанные данные. Selena загружает только предварительно обработанные данные, которые соответствуют условиям фильтра, указанным в предложении WHERE.
max_filter_ratioНетМаксимальная ошибочная терпимость загрузочного задания. Ошибочная терпимость — это максимальный процент записей данных, которые могут быть отфильтрованы из-за неадекватного качества данных во всех записях данных, запрошенных загрузочным заданием. Допустимые значения: от 0 до 1. Значение по умолчанию: 0.
Мы рекомендуем сохранить значение по умолчанию 0. Таким образом, если обнаружены неквалифицированные записи данных, загрузочное задание завершается неудачей, тем самым обеспечивая правильность данных.
Если вы хотите игнорировать неквалифицированные записи данных, вы можете установить этот параметр в значение больше 0. Таким образом, загрузочное задание может быть успешным, даже если файл данных содержит неквалифицированные записи данных.
ПРИМЕЧАНИЕ
Неквалифицированные записи данных не включают записи данных, которые фильтруются предложением WHERE.
log_rejected_record_numНетУказывает максимальное количество неквалифицированных строк данных, которые могут быть зарегистрированы. Этот параметр поддерживается начиная с версии 3.1. Допустимые значения: 0, -1 и любое ненулевое положительное целое число. Значение по умолчанию: 0.
  • Значение 0 указывает, что строки данных, которые фильтруются, не будут зарегистрированы.
  • Значение -1 указывает, что все строки данных, которые фильтруются, будут зарегистрированы.
  • Ненулевое положительное целое число, такое как n, указывает, что до n строк данных, которые фильтруются, могут быть зарегистрированы на каждом BE или CN.
timeoutНетПериод времени ожидания загрузочного задания. Допустимые значения: от 1 до 259200. Единица измерения: секунда. Значение по умолчанию: 600.
ПРИМЕЧАНИЕ В дополнение к параметру timeout вы также можете использовать параметр FE stream_load_default_timeout_second для централизованного управления периодом времени ожидания для всех заданий Stream Load в вашем кластере Selena. Если вы укажете параметр timeout, период времени ожидания, указанный параметром timeout, будет иметь приоритет. Если вы не укажете параметр timeout, период времени ожидания, указанный параметром stream_load_default_timeout_second, будет иметь приоритет.
strict_modeНетУказывает, следует ли включить строгий режим. Допустимые значения: true и false. Значение по умолчанию: false. Значение true указывает на включение строгого режима, а значение false указывает на отключение строгого режима.
timezoneНетЧасовой пояс, используемый загрузочным заданием. Значение по умолчанию: Asia/Shanghai. Значение этого параметра влияет на результаты, возвращаемые функциями, такими как strftime, alignment_timestamp и from_unixtime. Часовой пояс, указанный этим параметром, является часовым поясом уровня сеанса. Для получения дополнительной информации см. Configure a time zone.
load_mem_limitНетМаксимальный объем памяти, который может быть выделен для загрузочного задания. Единица измерения: байты. По умолчанию максимальный размер памяти для загрузочного задания составляет 2 ГБ. Значение этого параметра не может превышать максимальный объем памяти, который может быть выделен для каждого BE или CN.
partial_updateНетИспользовать ли частичные обновления. Допустимые значения: TRUE и FALSE. Значение по умолчанию: FALSE, что указывает на отключение этой функции.
partial_update_modeНетУказывает режим частичных обновлений. Допустимые значения: row и column.
  • Значение row (по умолчанию) означает частичные обновления в режиме строк, что более подходит для обновлений в реальном времени с множеством столбцов и небольшими партиями.
  • Значение column означает частичные обновления в режиме столбцов, что более подходит для пакетных обновлений с небольшим количеством столбцов и множеством строк. В таких сценариях включение режима столбцов обеспечивает более быструю скорость обновления. Например, в таблице со 100 столбцами, если обновляется только 10 столбцов (10% от общего числа) для всех строк, скорость обновления в режиме столбцов в 10 раз быстрее.
merge_conditionНетУказывает имя столбца, который вы хотите использовать в качестве условия для определения того, могут ли обновления вступить в силу. Обновление из исходной записи в целевую запись вступает в силу только тогда, когда исходная запись данных имеет большее или равное значение, чем целевая запись данных в указанном столбце. Selena поддерживает условные обновления начиная с версии 2.5.
ПРИМЕЧАНИЕ
Указанный вами столбец не может быть столбцом первичного ключа. Кроме того, только таблицы, использующие таблицу первичного ключа, поддерживают условные обновления.

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

Настройка сопоставления столбцов для загрузки данных CSV​

Если столбцы файла данных могут быть последовательно сопоставлены один к одному со столбцами таблицы Selena, вам не нужно настраивать сопоставление столбцов между файлом данных и таблицей Selena.

Если столбцы файла данных не могут быть последовательно сопоставлены один к одному со столбцами таблицы Selena, вам нужно использовать параметр columns для настройки сопоставления столбцов между файлом данных и таблицей Selena. Это включает следующие два случая использования:

  • Одинаковое количество столбцов, но разная последовательность столбцов. Кроме того, данные из файла данных не нужно вычислять с помощью функций перед загрузкой в соответствующие столбцы таблицы Selena.

    В параметре columns вам нужно указать имена столбцов таблицы Selena в той же последовательности, в которой расположены столбцы файла данных.

    Например, таблица Selena состоит из трех столбцов, которые по порядку col1, col2 и col3, и файл данных также состоит из трех столбцов, которые могут быть сопоставлены со столбцами таблицы Selena col3, col2 и col1 по порядку. В этом случае вам нужно указать "columns: col3, col2, col1".

  • Разное количество столбцов и разная последовательность столбцов. Кроме того, данные из файла данных необходимо вычислить с помощью функций перед загрузкой в соответствующие столбцы таблицы Selena.

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

    • Таблица Selena состоит из трех столбцов, которые по порядку col1, col2 и col3. Файл данных состоит из четырех столбцов, среди которых первые три столбца могут быть последовательно сопоставлены со столбцами таблицы Selena col1, col2 и col3, а четвертый столбец не может быть сопоставлен ни с одним из столбцов таблицы Selena. В этом случае вам нужно временно указать имя для четвертого столбца файла данных, и временное имя должно отличаться от любого из имен столбцов таблицы Selena. Например, вы можете указать "columns: col1, col2, col3, temp", в котором четвертый столбец файла данных временно назван temp.
    • Таблица Selena состоит из трех столбцов, которые по порядку year, month и day. Файл данных состоит только из одного столбца, который содержит значения даты и времени в формате yyyy-mm-dd hh:mm:ss. В этом случае вы можете указать "columns: col, year = year(col), month=month(col), day=day(col)", в котором col — временное имя столбца файла данных, а функции year = year(col), month=month(col) и day=day(col) используются для извлечения данных из столбца файла данных col и загрузки данных в сопоставляемые столбцы таблицы Selena. Например, year = year(col) используется для извлечения данных yyyy из столбца файла данных col и загрузки данных в столбец таблицы Selena year.

Для получения подробных примеров см. Настройка сопоставления столбцов.

Настройка сопоставления столбцов для загрузки данных JSON​

Если ключи документа JSON имеют те же имена, что и столбцы таблицы Selena, вы можете загрузить данные в формате JSON, используя простой режим. В простом режиме вам не нужно указывать параметр jsonpaths. Этот режим требует, чтобы данные в формате JSON были объектом, обозначенным фигурными скобками {}, таким как {"category": 1, "author": 2, "price": "3"}. В этом примере category, author и price — это имена ключей, и эти ключи могут быть сопоставлены один к одному по имени со столбцами category, author и price таблицы Selena.

Если ключи документа JSON имеют разные имена, чем столбцы таблицы Selena, вы можете загрузить данные в формате JSON, используя режим сопоставления. В режиме сопоставления вам нужно использовать параметры jsonpaths и COLUMNS для указания сопоставления столбцов между документом JSON и таблицей Selena:

  • В параметре jsonpaths укажите ключи JSON в последовательности, в которой они расположены в документе JSON.
  • В параметре COLUMNS укажите сопоставление между ключами JSON и столбцами таблицы Selena:
    • Имена столбцов, указанные в параметре COLUMNS, сопоставляются один к одному в последовательности с ключами JSON.
    • Имена столбцов, указанные в параметре COLUMNS, сопоставляются один к одному по имени со столбцами таблицы Selena.

Для примеров загрузки данных в формате JSON с использованием режима сопоставления см. Загрузка данных JSON с использованием режима сопоставления.

Возвращаемое значение​

После завершения загрузочного задания Selena возвращает результат задания в формате JSON. Пример:

{
    "TxnId": 1003,
    "Label": "label123",
    "Status": "Success",
    "Message": "OK",
    "NumberTotalRows": 1000000,
    "NumberLoadedRows": 999999,
    "NumberFilteredRows": 1,
    "NumberUnselectedRows": 0,
    "LoadBytes": 40888898,
    "LoadTimeMs": 2144,
    "BeginTxnTimeMs": 0,
    "StreamLoadPlanTimeMs": 1,
    "ReadDataTimeMs": 0,
    "WriteDataTimeMs": 11,
    "CommitAndPublishTimeMs": 16,
}

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

ПараметрОписание
TxnIdID транзакции загрузочного задания.
LabelМетка загрузочного задания.
StatusКонечный статус загруженных данных.
  • Success: Данные успешно загружены и могут быть запрошены.
  • Publish Timeout: Загрузочное задание успешно отправлено, но данные все еще не могут быть запрошены. Вам не нужно повторять попытку загрузки данных.
  • Label Already Exists: Метка загрузочного задания уже использовалась для другого загрузочного задания. Данные могли быть успешно загружены или загружаются.
  • Fail: Не удалось загрузить данные. Вы можете повторить попытку загрузочного задания.
MessageСтатус загрузочного задания. Если загрузочное задание завершается с ошибкой, возвращается подробная причина сбоя.
NumberTotalRowsОбщее количество записей данных, которые читаются.
NumberLoadedRowsОбщее количество записей данных, которые успешно загружены. Этот параметр действителен только тогда, когда значение, возвращенное для Status, равно Success.
NumberFilteredRowsКоличество записей данных, которые фильтруются из-за неадекватного качества данных.
NumberUnselectedRowsКоличество записей данных, которые фильтруются предложением WHERE.
LoadBytesОбъем загруженных данных. Единица измерения: байты.
LoadTimeMsВремя, затраченное на загрузочное задание. Единица измерения: мс.
BeginTxnTimeMsВремя, затраченное на выполнение транзакции для загрузочного задания.
StreamLoadPlanTimeMsВремя, затраченное на создание плана выполнения для загрузочного задания.
ReadDataTimeMsВремя, затраченное на чтение данных для загрузочного задания.
WriteDataTimeMsВремя, затраченное на запись данных для загрузочного задания.
CommitAndPublishTimeMsВремя, затраченное на фиксацию и публикацию данных для загрузочного задания.

Если загрузочное задание завершается с ошибкой, Selena также возвращает ErrorURL. Пример:

{"ErrorURL": "http://172.26.195.68:8045/api/_load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be"}

ErrorURL предоставляет URL-адрес, из которого вы можете получить подробную информацию о неквалифицированных записях данных, которые были отфильтрованы. Вы можете указать максимальное количество неквалифицированных строк данных, которые могут быть зарегистрированы, используя необязательный параметр log_rejected_record_num, который устанавливается при отправке загрузочного задания.

Вы можете выполнить curl "url", чтобы напрямую просмотреть подробную информацию об отфильтрованных неквалифицированных записях данных. Вы также можете выполнить wget "url", чтобы экспортировать подробную информацию об этих записях данных:

wget http://172.26.195.68:8045/api/_load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be

Экспортированные подробные сведения о записях данных сохраняются в локальный файл с именем, похожим на _load_error_log?file=error_log_3a4eb8421f0878a6_9a54df29fd9206be. Вы можете использовать команду cat для просмотра файла.

Затем вы можете настроить конфигурацию загрузочного задания и снова отправить загрузочное задание.

Примеры​

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

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

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

Ваша база данных Selena test_db содержит таблицу с именем table1. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example1.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col1, col2 и col3 таблицы table1.

Если вы хотите загрузить все данные из example1.csv в table1 в течение до 100 секунд, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:label1" \
    -H "Expect:100-continue" \
    -H "timeout:100" \
    -H "max_filter_ratio:0.2" \
    -T example1.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table1/_stream_load

Установка ошибочной терпимости​

Ваша база данных Selena test_db содержит таблицу с именем table2. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example2.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col1, col2 и col3 таблицы table2.

Если вы хотите загрузить все данные из example2.csv в table2 с максимальной ошибочной терпимостью 0.2, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:label2" \
    -H "Expect:100-continue" \
    -H "max_filter_ratio:0.2" \
    -T example2.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table2/_stream_load

Настройка сопоставления столбцов​

Ваша база данных Selena test_db содержит таблицу с именем table3. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example3.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col2, col1 и col3 таблицы table3.

Если вы хотите загрузить все данные из example3.csv в table3, выполните следующую команду:

curl --location-trusted -u <username>:<password>  -H "label:label3" \
    -H "Expect:100-continue" \
    -H "columns: col2, col1, col3" \
    -T example3.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table3/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере столбцы example3.csv не могут быть сопоставлены со столбцами table3 в той же последовательности, в которой эти столбцы расположены в table3. Поэтому вам нужно использовать параметр columns для настройки сопоставления столбцов между example3.csv и table3.

Установка условий фильтра​

Ваша база данных Selena test_db содержит таблицу с именем table4. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example4.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col1, col2 и col3 таблицы table4.

Если вы хотите загрузить только записи данных, значения которых в первом столбце example4.csv равны 20180601, в table4, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:label4" \
    -H "Expect:100-continue" \
    -H "columns: col1, col2, col3"\
    -H "where: col1 = 20180601" \
    -T example4.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table4/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере example4.csv и table4 имеют одинаковое количество столбцов, которые могут быть последовательно сопоставлены, но вам нужно использовать предложение WHERE для указания условий фильтра на основе столбцов. Поэтому вам нужно использовать параметр columns для определения временных имен для столбцов example4.csv.

Установка целевых partition​

Ваша база данных Selena test_db содержит таблицу с именем table5. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example5.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col1, col2 и col3 таблицы table5.

Если вы хотите загрузить все данные из example5.csv в partition p1 и p2 таблицы table5, выполните следующую команду:

curl --location-trusted -u <username>:<password>  -H "label:label5" \
    -H "Expect:100-continue" \
    -H "partitions: p1, p2" \
    -T example5.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table5/_stream_load

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

Ваша база данных Selena test_db содержит таблицу с именем table6. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example6.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col1, col2 и col3 таблицы table6.

Если вы хотите загрузить все данные из example6.csv в table6, используя строгий режим и часовой пояс Africa/Abidjan, выполните следующую команду:

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "strict_mode: true" \
    -H "timezone: Africa/Abidjan" \
    -T example6.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table6/_stream_load

Загрузка данных в таблицы, содержащие столбцы типа HLL​

Ваша база данных Selena test_db содержит таблицу с именем table7. Таблица состоит из двух столбцов типа HLL, которые по порядку col1 и col2.

Ваш файл данных example7.csv также состоит из двух столбцов, среди которых первый столбец может быть сопоставлен с col1 таблицы table7, а второй столбец не может быть сопоставлен ни с одним столбцом таблицы table7. Значения в первом столбце example7.csv могут быть преобразованы в данные типа HLL с помощью функций перед загрузкой в col1 таблицы table7.

Если вы хотите загрузить данные из example7.csv в table7, выполните следующую команду:

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "columns: temp1, temp2, col1=hll_hash(temp1), col2=hll_empty()" \
    -T example7.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table7/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере два столбца example7.csv названы temp1 и temp2 по порядку с использованием параметра columns. Затем функции используются для преобразования данных следующим образом:

  • Функция hll_hash используется для преобразования значений в temp1 example7.csv в данные типа HLL и сопоставления temp1 example7.csv с col1 table7.

  • Функция hll_empty используется для заполнения указанного значения по умолчанию в col2 table7.

Для использования функций hll_hash и hll_empty см. hll_hash и hll_empty.

Загрузка данных в таблицы, содержащие столбцы типа BITMAP​

Ваша база данных Selena test_db содержит таблицу с именем table8. Таблица состоит из двух столбцов типа BITMAP, которые по порядку col1 и col2.

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

Если вы хотите загрузить данные из example8.csv в table8, выполните следующую команду:

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "columns: temp1, temp2, col1=to_bitmap(temp1), col2=bitmap_empty()" \
    -T example8.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table8/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере два столбца example8.csv названы temp1 и temp2 по порядку с использованием параметра columns. Затем функции используются для преобразования данных следующим образом:

  • Функция to_bitmap используется для преобразования значений в temp1 example8.csv в данные типа BITMAP и сопоставления temp1 example8.csv с col1 table8.

  • Функция bitmap_empty используется для заполнения указанного значения по умолчанию в col2 table8.

Для использования функций to_bitmap и bitmap_empty см. to_bitmap и bitmap_empty.

Установка skip_header, trim_space, enclose и escape​

Ваша база данных Selena test_db содержит таблицу с именем table9. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example9.csv также состоит из трех столбцов, которые последовательно сопоставлены с col2, col1 и col3 таблицы table13.

Если вы хотите загрузить все данные из example9.csv в table9 с намерением пропустить первые пять строк example9.csv, удалить пробелы перед и после разделителей столбцов и установить enclose в \ и escape в \, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:3875" \
    -H "Expect:100-continue" \
    -H "trim_space: true" -H "skip_header: 5" \
    -H "column_separator:," -H "enclose:\"" -H "escape:\\" \
    -H "columns: col2, col1, col3" \
    -T example9.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl9/_stream_load

Установка column_separator и row_delimiter​

Ваша база данных Selena test_db содержит таблицу с именем table10. Таблица состоит из трех столбцов, которые по порядку col1, col2 и col3.

Ваш файл данных example10.csv также состоит из трех столбцов, которые могут быть последовательно сопоставлены с col1, col2 и col3 таблицы table10. Столбцы в строке данных разделены запятыми (,), а строки данных разделены двумя последовательными непечатаемыми символами \r\n.

Если вы хотите загрузить все данные из example10.csv в table10, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:label10" \
    -H "Expect:100-continue" \
    -H "column_separator:," \
    -H "row_delimiter:\\x0D0A" \
    -T example10.csv -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/table10/_stream_load

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

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

Ваша база данных Selena test_db содержит таблицу с именем tbl1, схема которой следующая:

`category` varchar(512) NULL COMMENT "",`author` varchar(512) NULL COMMENT "",`title` varchar(512) NULL COMMENT "",`price` double NULL COMMENT ""

Загрузка данных JSON с использованием простого режима​

Предположим, что ваш файл данных example1.json состоит из следующих данных:

{"category":"C++","author":"avc","title":"C++ primer","price":895}

Чтобы загрузить все данные из example1.json в tbl1, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:label6" \
    -H "Expect:100-continue" \
    -H "format: json" \
    -T example1.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl1/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере параметры columns и jsonpaths не указаны. Поэтому ключи в example1.json сопоставляются по имени со столбцами tbl1.

Для увеличения пропускной способности Stream Load поддерживает загрузку нескольких записей данных одновременно. Пример:

[{"category":"C++","author":"avc","title":"C++ primer","price":89.5},{"category":"Java","author":"avc","title":"Effective Java","price":95},{"category":"Linux","author":"avc","title":"Linux kernel","price":195}]

Загрузка данных JSON с использованием режима сопоставления​

Selena выполняет следующие шаги для сопоставления и обработки данных JSON:

  1. (Необязательно) Удаляет самую внешнюю структуру массива в соответствии с настройкой параметра strip_outer_array.

    ПРИМЕЧАНИЕ

    Этот шаг выполняется только тогда, когда самый внешний слой данных JSON — это структура массива, обозначенная парой квадратных скобок []. Вам нужно установить strip_outer_array в true.

  2. (Необязательно) Сопоставляет корневой элемент данных JSON в соответствии с настройкой параметра json_root.

    ПРИМЕЧАНИЕ

    Этот шаг выполняется только тогда, когда данные JSON имеют корневой элемент. Вам нужно указать корневой элемент, используя параметр json_root.

  3. Извлекает указанные данные JSON в соответствии с настройкой параметра jsonpaths.

Загрузка данных JSON с использованием режима сопоставления без указания корневого элемента​

Предположим, что ваш файл данных example2.json состоит из следующих данных:

[{"category":"xuxb111","author":"1avc","title":"SayingsoftheCentury","price":895},{"category":"xuxb222","author":"2avc","title":"SayingsoftheCentury","price":895},{"category":"xuxb333","author":"3avc","title":"SayingsoftheCentury","price":895}]

Чтобы загрузить только category, author и price из example2.json, выполните следующую команду:

curl --location-trusted -u <username>:<password> -H "label:label7" \
    -H "Expect:100-continue" \
    -H "format: json" \
    -H "strip_outer_array: true" \
    -H "jsonpaths: [\"$.category\",\"$.price\",\"$.author\"]" \
    -H "columns: category, price, author" \
    -T example2.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl1/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере самый внешний слой данных JSON — это структура массива, обозначенная парой квадратных скобок []. Структура массива состоит из нескольких объектов JSON, каждый из которых представляет собой запись данных. Поэтому вам нужно установить strip_outer_array в true, чтобы удалить самую внешнюю структуру массива. Ключ title, который вы не хотите загружать, игнорируется во время загрузки.

Загрузка данных JSON с использованием режима сопоставления с указанным корневым элементом​

Предположим, что ваш файл данных example3.json состоит из следующих данных:

{"id": 10001,"RECORDS":[{"category":"11","title":"SayingsoftheCentury","price":895,"timestamp":1589191587},{"category":"22","author":"2avc","price":895,"timestamp":1589191487},{"category":"33","author":"3avc","title":"SayingsoftheCentury","timestamp":1589191387}],"comments": ["3 records", "there will be 3 rows"]}

Чтобы загрузить только category, author и price из example3.json, выполните следующую команду:

curl --location-trusted -u <username>:<password> \
    -H "Expect:100-continue" \
    -H "format: json" \
    -H "json_root: $.RECORDS" \
    -H "strip_outer_array: true" \
    -H "jsonpaths: [\"$.category\",\"$.price\",\"$.author\"]" \
    -H "columns: category, price, author" -H "label:label8" \
    -T example3.json -XPUT \
    http://<fe_host>:<fe_http_port>/api/test_db/tbl1/_stream_load

ПРИМЕЧАНИЕ

В предыдущем примере самый внешний слой данных JSON — это структура массива, обозначенная парой квадратных скобок []. Структура массива состоит из нескольких объектов JSON, каждый из которых представляет собой запись данных. Поэтому вам нужно установить strip_outer_array в true, чтобы удалить самую внешнюю структуру массива. Ключи title и timestamp, которые вы не хотите загружать, игнорируются во время загрузки. Кроме того, параметр json_root используется для указания корневого элемента, который является массивом, данных JSON.

Объединение запросов Stream Load​

  • Выполните следующую команду, чтобы запустить задание Stream Load с включенным Merge Commit в синхронном режиме и установить окно слияния на 5000 миллисекунд и степень параллелизма на 2:

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

  • Выполните следующую команду, чтобы запустить задание Stream Load с включенным Merge Commit в асинхронном режиме и установить окно слияния на 60000 миллисекунд и степень параллелизма на 2:

    curl --location-trusted -u <username>:<password> \
        -H "Expect:100-continue" \
        -H "column_separator:," \
        -H "columns: id, name, score" \
        -H "enable_merge_commit:true" \
        -H "merge_commit_async:true" \
        -H "merge_commit_interval_ms:60000" \
        -H "merge_commit_parallel:2" \
        -T example1.csv -XPUT \
        http://<fe_host>:<fe_http_port>/api/mydatabase/table1/_stream_load