Strict mode

厳密モード

厳密モードは、データのロードに対して設定できるオプションの一つであり、ロードの動作や最終的にロードされるデータに影響を与えます。

このトピックでは、厳密モードとその設定方法について説明します。

厳密モードの理解

データのロード中、ソースのカラムのデータ型が宛先のカラムのデータ型と完全に一致しない場合があります。このような場合、StarRocksはデータ型が一致しないソースのカラム値に対して変換を行います。データの変換が失敗することがあり、フィールドのデータ型の不一致やフィールド長のオーバーフローなど、様々な問題が原因です。適切に変換できなかったソースのカラム値は、不適格なカラム値となり、これらの不適格なカラム値を含むソースの行は「不適格な行」と呼ばれます。厳密モードは、データのロード中に不適格な行をフィルタリングするかどうかを制御するために使用されます。

厳密モードの動作は以下の通りです。

厳密モードが有効な場合、StarRocksは適格な行のみをロードします。不適格な行はフィルタリングされ、不適格な行に関する詳細な情報が返されます。
厳密モードが無効な場合、StarRocksは不適格なカラム値をNULLに変換し、これらのNULL値を含む不適格な行と共に適格な行をロードします。

以下に注意点を示します。

実際のビジネスシナリオでは、適格な行と不適格な行の両方にNULL値が含まれる場合があります。宛先のカラムがNULL値を許可していない場合、StarRocksはエラーを報告し、NULL値を含む行はフィルタリングされます。
Stream Load、Broker Load、Routine Load、またはSpark Load ジョブの場合、フィルタリングできる不適格な行の最大割合は、オプションのジョブプロパティ max_filter_ratio で制御されます。INSERT では、max_filter_ratio プロパティの設定はサポートされていません。

たとえば、CSV形式のデータファイルから、TINYINT [-128, 127] のデータ型を持つStarRocksテーブルのカラムに、\N（\NはNULL値を示す）やabc、2000、1 の値を持つ4つの行をロードしたい場合を考えます。

ソースのカラム値 \N は、TINYINT への変換時に NULL に変換されます。

注意

\N は、宛先のデータ型に関係なく、変換時に常に NULL に変換されます。
ソースのカラム値 abc は、TINYINT のデータ型ではないため変換に失敗し、NULL に変換されます。
ソースのカラム値 2000 は、TINYINT でサポートされる範囲を超えているため変換に失敗し、NULL に変換されます。
ソースのカラム値 1 は、TINYINT のデータ型として適切に変換されます。

厳密モードが無効な場合、StarRocksはこれらの4つの行をすべてロードします。

厳密モードが有効な場合、StarRocksはNULLや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 を参照してください。

厳密モード

厳密モードの理解​

厳密モードが無効な場合の最終的にロードされるデータ​

厳密モードが有効な場合の最終的にロードされるデータ​

厳密モードの設定​

Stream Load​

Broker Load​

Routine Load​

Spark Load​

INSERT​