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

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

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

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

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

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

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

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

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

• Максимальный процент неквалифицированных строк, которые могут быть отфильтрованы для задания Stream Load, Broker Load, Routine Load или Spark Load, контролируется дополнительным свойством задания max_filter_ratio. INSERT не поддерживает установку свойства max_filter_ratio.

Например, вы хотите загрузить четыре строки, содержащие значения \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 загружается.

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

Если вы запускаете задание Stream Load, Broker Load, Routine Load или Spark Load для загрузки данных, используйте параметр strict_mode для настройки строгого режима для задания загрузки. Допустимые значения: true и false. Значение по умолчанию — false. Значение true включает строгий режим, а значение false отключает строгий режим.

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

Примеры приведены ниже:

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

SET enable_insert_strict = {true | false};
INSERT INTO <table_name> ...

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