ストリクトモード
ストリクトモードは、データロードのために設定できるオプションのプロパティです。これはロードの動作や最終的にロードされるデータに影響を与えます。
このトピックでは、ストリクトモードとは何か、そしてストリクトモードをどのように設定するかを紹介します。
ストリクトモードを理解する
データロード中、ソースカラムのデータ型が宛先カラムのデータ型と完全に一致しない場合があります。そのような場合、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形式のデータファイルから StarRocks テーブルに \N（\N は NULL 値を示します）、abc、2000、および 1 の値を持つ4行をロードしたいとします。宛先の StarRocks テーブルカラムのデータ型は TINYINT [-128, 127] です。
-
ソースカラム値
\Nは TINYINT に変換される際にNULLに処理されます。NOTE
\Nは、宛先データ型に関係なく、常に変換時にNULLに処理されます。 -
ソースカラム値
abcは TINYINT ではないため、変換に失敗し、NULLに処理されます。 -
ソースカラム値
2000は TINYINT がサポートする範囲を超えているため、変換に失敗し、NULLに処理されます。 -
ソースカラム値
1は TINYINT 型の値1に正しく変換されます。
ストリクトモードが無効な場合、StarRocks は4行すべてをロードします。
ストリクトモードが有効な場合、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 がロードされます。 |
ストリクトモードを設定する
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 を参照してください。