STREAM LOAD

Selena предоставляет метод загрузки на основе HTTP - STREAM LOAD, который помогает загружать данные из локальной файловой системы или потокового источника данных. После отправки задания загрузки Selena синхронно выполняет задание и возвращает результат после завершения. Вы можете определить успешность задания на основе результата. Информацию о сценариях применения, ограничениях, принципах и поддерживаемых форматах файлов данных Stream Load см. в разделе Загрузка из локальной файловой системы через Stream Load.

подсказка

Этот пример использует набор данных Local Climatological Data (LCD), представленный в руководстве Основы Selena для быстрого старта. Вы можете загрузить данные и попробовать пример самостоятельно.

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

УВЕДОМЛЕНИЕ

• После загрузки данных в таблицу Selena с помощью Stream Load данные материализованных представлений, созданных на основе этой таблицы, также обновляются.
• Вы можете загружать данные в таблицы Selena только как пользователь, имеющий привилегию INSERT для этих таблиц. Если у вас нет привилегии 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), как показано в этом разделе. Если вы не выбираете кодирование передачи по частям, вы должны ввести поле заголовка Content-Length для указания длины передаваемого содержимого, тем самым обеспечивая целостность данных.

  ПРИМЕЧАНИЕ

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

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

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

Параметры

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 может включать имя файла данных, формат, разделитель столбцов, разделитель строк, целевые разделы и сопоставление столбцов с таблицей 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	Нет	Разделы, в которые вы хотите загрузить файл данных. По умолчанию, если вы не указываете этот параметр, Selena загружает файл данных во все разделы таблицы Selena.
temporary_partitions	Нет	Имя временного раздела, в который вы хотите загрузить файл данных. Вы можете указать несколько временных разделов, которые должны быть разделены запятыми (,).
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 байт, в качестве текстового разделителя.
• Нулевые значения обозначаются с помощью \N. Например, файл данных состоит из трех столбцов, и запись из этого файла данных содержит данные в первом и третьем столбцах, но не содержит данных во втором столбце. В этой ситуации вам нужно использовать \N во втором столбце для обозначения нулевого значения. Это означает, что запись должна быть составлена как 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."

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 предотвращает повторную загрузку одних и тех же данных. Для соглашений об именовании меток см. Системные ограничения. По умолчанию Selena сохраняет метки заданий загрузки, которые были успешно завершены за последние три дня. Вы можете использовать параметр FE label_keep_max_second для изменения периода сохранения меток.
where	Нет	Условия, на основе которых Selena фильтрует предварительно обработанные данные. Selena загружает только предварительно обработанные данные, которые соответствуют условиям фильтра, указанным в предложении WHERE.
max_filter_ratio	Нет	Максимальная допустимая погрешность задания загрузки. Допустимая погрешность - это максимальный процент записей данных, которые могут быть отфильтрованы из-за неадекватного качества данных во всех записях данных, запрошенных заданием загрузки. Допустимые значения: от 0 до 1. Значение по умолчанию: 0. Мы рекомендуем сохранить значение по умолчанию 0. Таким образом, если обнаружены неквалифицированные записи данных, задание загрузки завершится неудачей, тем самым обеспечивая правильность данных. Если вы хотите игнорировать неквалифицированные записи данных, вы можете установить этот параметр в значение больше 0. Таким образом, задание загрузки может быть успешным, даже если файл данных содержит неквалифицированные записи данных. ПРИМЕЧАНИЕ Неквалифицированные записи данных не включают записи данных, которые отфильтрованы предложением WHERE.
log_rejected_record_num	Нет	Указывает максимальное количество неквалифицированных строк данных, которые могут быть зарегистрированы. Этот параметр поддерживается начиная с версии 1.5.0. Допустимые значения: 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. Часовой пояс, указанный этим параметром, является часовым поясом уровня сеанса. Для получения дополнительной информации см. Настройка часового пояса.
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 поддерживает условные обновления начиная с версии 1.5.0. ПРИМЕЧАНИЕ Столбец, который вы указываете, не может быть столбцом первичного ключа. Кроме того, только таблицы, использующие таблицу Primary Key, поддерживают условные обновления.

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

Настройка сопоставления столбцов для загрузки 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,
}

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

Параметр	Описание
TxnId	Идентификатор транзакции задания загрузки.
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.

Установка целевых разделов

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

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

Если вы хотите загрузить все данные из example5.csv в разделы 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-данных.