Версия: 2.0.x

Строгий режим

Строгий режим — это необязательное свойство, которое можно настроить для загрузки данных. Он влияет на поведение загрузки и окончательные загруженные данные.

В этой теме рассказывается, что такое строгий режим и как его настроить.

Понимание строгого режима

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

Строгий режим работает следующим образом:

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

Обратите внимание на следующее:

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

примечание

Свойство max_filter_ratio для INSERT поддерживается начиная с версии v1.5.2.

Например, вы хотите загрузить четыре строки со значениями \N (\N обозначает значение NULL), abc, 2000 и 1 соответственно в столбце из CSV-файла данных в таблицу Selena, и тип данных целевого столбца таблицы Selena — TINYINT [-128, 127].

Значение исходного столбца \N обрабатывается в NULL при преобразовании в TINYINT.

ПРИМЕЧАНИЕ

\N всегда обрабатывается в NULL при преобразовании независимо от целевого типа данных.
Значение исходного столбца abc обрабатывается в NULL, потому что его тип данных не является TINYINT, и преобразование завершается неудачей.
Значение исходного столбца 2000 обрабатывается в NULL, потому что оно выходит за пределы диапазона, поддерживаемого TINYINT, и преобразование завершается неудачей.
Значение исходного столбца 1 может быть правильно преобразовано в значение типа TINYINT 1.

Если строгий режим отключён, Selena загружает все четыре строки.

Если строгий режим включён, Selena загружает только строки со значениями \N или 1 и отфильтровывает строки со значениями abc или 2000. Отфильтрованные строки учитываются в максимальном проценте строк, которые могут быть отфильтрованы из-за недостаточного качества данных, как указано параметром max_filter_ratio.

Окончательные загруженные данные при отключённом строгом режиме

Значение исходного столбца	Значение столбца при преобразовании в TINYINT	Результат загрузки, когда целевой столбец допускает NULL	Результат загрузки, когда целевой столбец не допускает NULL
\N	NULL	Значение `NULL` загружено.	Сообщается об ошибке.
abc	NULL	Значение `NULL` загружено.	Сообщается об ошибке.
2000	NULL	Значение `NULL` загружено.	Сообщается об ошибке.
1	1	Значение `1` загружено.	Значение `1` загружено.

Окончательные загруженные данные при включённом строгом режиме

Значение исходного столбца	Значение столбца при преобразовании в TINYINT	Результат загрузки, когда целевой столбец допускает NULL	Результат загрузки, когда целевой столбец не допускает NULL
\N	NULL	Значение `NULL` загружено.	Сообщается об ошибке.
abc	NULL	Значение `NULL` не допускается и поэтому отфильтровывается.	Сообщается об ошибке.
2000	NULL	Значение `NULL` не допускается и поэтому отфильтровывается.	Сообщается об ошибке.
1	1	Значение `1` загружено.	Значение `1` загружено.

Настройка строгого режима

Вы можете использовать параметр strict_mode для установки строгого режима для задания загрузки. Допустимые значения: true и false. Значение по умолчанию — false. Значение true включает строгий режим, а значение false отключает строгий режим. Обратите внимание, что параметр strict_mode поддерживается для INSERT начиная с версии v1.5.2, со значением по умолчанию true. Теперь, за исключением Stream Load, для всех других методов загрузки strict_mode устанавливается одинаково в разделе PROPERTIES.

Вы также можете использовать сессионную переменную enable_insert_strict для установки строгого режима. Допустимые значения: true и false. Значение по умолчанию — true. Значение true включает строгий режим, а значение false отключает строгий режим.

примечание

Начиная с версии v1.5.2, когда enable_insert_strict установлено в true, система загружает только квалифицированные строки. Неквалифицированные строки отфильтровываются, и возвращаются сведения о неквалифицированных строках. В версиях ранее v1.5.2, когда enable_insert_strict установлено в true, задания INSERT завершаются неудачей при наличии неквалифицированных строк.

Примеры:

Stream Load

curl --location-trusted -u <username>:<password> \
    -H "strict_mode: {true | false}" \
    -T <file_name> -XPUT \
    http://<fe_host>:<fe_http_port>/api/<database_name>/<table_name>/_stream_load

Подробный синтаксис и параметры Stream Load см. в STREAM LOAD.

Broker Load

LOAD LABEL [<database_name>.]<label_name>
(
    DATA INFILE ("<file_path>"[, "<file_path>" ...])
    INTO TABLE <table_name>
)
WITH BROKER
(
    "username" = "<hdfs_username>",
    "password" = "<hdfs_password>"
)
PROPERTIES
(
    "strict_mode" = "{true | false}"
)

В приведённом выше фрагменте кода в качестве примера используется HDFS. Подробный синтаксис и параметры Broker Load см. в BROKER LOAD.

Routine Load

CREATE ROUTINE LOAD [<database_name>.]<job_name> ON <table_name>
PROPERTIES
(
    "strict_mode" = "{true | false}"
)
FROM KAFKA
(
    "kafka_broker_list" ="<kafka_broker1_ip>:<kafka_broker1_port>[,<kafka_broker2_ip>:<kafka_broker2_port>...]",
    "kafka_topic" = "<topic_name>"
)

В приведённом выше фрагменте кода в качестве примера используется Apache Kafka. Подробный синтаксис и параметры Routine Load см. в CREATE ROUTINE LOAD.

Spark Load

LOAD LABEL [<database_name>.]<label_name>
(
    DATA INFILE ("<file_path>"[, "<file_path>" ...])
    INTO TABLE <table_name>
)
WITH RESOURCE <resource_name>
(
    "spark.executor.memory" = "3g",
    "broker.username" = "<hdfs_username>",
    "broker.password" = "<hdfs_password>"
)
PROPERTIES
(
    "strict_mode" = "{true | false}"
)

В приведённом выше фрагменте кода в качестве примера используется HDFS. Подробный синтаксис и параметры Spark Load см. в SPARK LOAD.

INSERT

INSERT INTO [<database_name>.]<table_name>
PROPERTIES(
    "strict_mode" = "{true | false}"
)
<query_statement>

Подробный синтаксис и параметры INSERT см. в INSERT.

Понимание строгого режима​

Окончательные загруженные данные при отключённом строгом режиме​

Окончательные загруженные данные при включённом строгом режиме​

Настройка строгого режима​

Stream Load​

Broker Load​

Routine Load​

Spark Load​

INSERT​