严格模式
严格模式是您可以为数据加载配置的可选属性。它会影响加载行为和最终加载的数据。
本主题介绍什么是严格模式以及如何设置严格模式。
了解严格模式
在数据加载期间，源列的数据类型可能与目标列的数据类型不完全一致。 在这种情况下，StarRocks 会对数据类型不一致的源列值执行转换。 由于各种问题（例如不匹配的字段数据类型和字段长度溢出），数据转换可能会失败。 未能正确转换的源列值是不合格的列值，包含不合格列值的源行称为“不合格行”。 严格模式用于控制在数据加载期间是否过滤掉不合格的行。
严格模式的工作原理如下
- 如果启用严格模式，StarRocks 将仅加载合格的行。 它会过滤掉不合格的行，并返回有关不合格行的详细信息。
- 如果禁用严格模式，StarRocks 会将不合格的列值转换为
NULL，并将包含这些NULL值的不合格行与合格的行一起加载。
请注意以下几点
-
在实际业务场景中，合格行和不合格行都可能包含
NULL值。 如果目标列不允许NULL值，则 StarRocks 会报告错误并过滤掉包含NULL值的行。 -
可以过滤掉的加载作业的不合格行的最大百分比由一个可选的作业属性
max_filter_ratio控制。
INSERT 的 max_filter_ratio 属性从 v3.4.0 开始支持。
例如，您想从 CSV 格式的数据文件中将包含 \N (\N 表示 NULL 值)、abc、2000 和 1 值的四行加载到 StarRocks 表的列中，并且目标 StarRocks 表列的数据类型为 TINYINT [-128, 127]。
-
源列值
\N在转换为 TINYINT 时被处理为NULL。注意
无论目标数据类型如何，
\N在转换时始终被处理为NULL。 -
源列值
abc被处理为NULL，因为其数据类型不是 TINYINT 并且转换失败。 -
源列值
2000被处理为NULL，因为它超出了 TINYINT 支持的范围并且转换失败。 -
源列值
1可以正确转换为 TINYINT 类型的值1。
如果禁用严格模式，StarRocks 将加载所有四行。
如果启用严格模式，StarRocks 将仅加载包含 \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 禁用严格模式。 请注意，从 v3.4.0 开始，INSERT 支持 strict_mode 参数，默认值为 true。 现在，除了 Stream Load，对于所有其他加载方法，都在 PROPERTIES 子句中以相同的方式设置 strict_mode。
您还可以使用 enable_insert_strict 会话变量来设置严格模式。 有效值为 true 和 false。 默认值为 true。 值 true 启用严格模式，值 false 禁用严格模式。
从 v3.4.0 开始，当 enable_insert_strict 设置为 true 时，系统仅加载合格的行。 它会过滤掉不合格的行，并返回有关不合格行的详细信息。 相反，在早于 v3.4.0 的版本中，当 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。