バージョン: 26.2 Preview

Strict mode

Strict mode はデータロードのために設定できるオプションのプロパティです。これはロードの動作と最終的にロードされるデータに影響を与えます。

このトピックでは、strict mode とは何か、そして strict mode をどのように設定するかを紹介します。

Strict mode を理解する

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

Strict mode の動作は次の通りです：

Strict mode が有効な場合、PhoenixAI は適格な行のみをロードします。不適格な行をフィルタリングし、不適格な行の詳細を返します。
Strict mode が無効な場合、PhoenixAI は不適格な列値を NULL に変換し、これらの NULL 値を含む不適格な行を適格な行と一緒にロードします。

次の点に注意してください：

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

例えば、CSV形式のデータファイルから PhoenixAI テーブルに \N（\N は NULL 値を示す）、abc、2000、および 1 の値をそれぞれ持つ4行をロードしたいとします。宛先の PhoenixAI テーブル列のデータ型は TINYINT [-128, 127] です。

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

Strict mode が無効な場合、PhoenixAI はこれら4行すべてをロードします。

Strict mode が有効な場合、PhoenixAI は \N または 1 を持つ行のみをロードし、abc または 2000 を持つ行をフィルタリングします。フィルタリングされた行は、max_filter_ratio パラメータで指定された不十分なデータ品質のためにフィルタリングできる行の最大割合に対してカウントされます。

Strict mode 無効時の最終ロードデータ

ソース列の値	TINYINT への変換時の列値	宛先列が NULL 値を許可する場合のロード結果	宛先列が NULL 値を許可しない場合のロード結果
\N	NULL	値 `NULL` がロードされます。	エラーが報告されます。
abc	NULL	値 `NULL` がロードされます。	エラーが報告されます。
2000	NULL	値 `NULL` がロードされます。	エラーが報告されます。
1	1	値 `1` がロードされます。	値 `1` がロードされます。

Strict mode 有効時の最終ロードデータ

ソース列の値	TINYINT への変換時の列値	宛先列が NULL 値を許可する場合のロード結果	宛先列が NULL 値を許可しない場合のロード結果
\N	NULL	値 `NULL` がロードされます。	エラーが報告されます。
abc	NULL	値 `NULL` は許可されていないためフィルタリングされます。	エラーが報告されます。
2000	NULL	値 `NULL` は許可されていないためフィルタリングされます。	エラーが報告されます。
1	1	値 `1` がロードされます。	値 `1` がロードされます。

Strict mode を設定する

データをロードするために Stream Load 、Broker Load 、または Routine Load ジョブを実行する場合、strict_mode パラメータを使用してロードジョブの strict mode を設定します。有効な値は true と false です。デフォルト値は false です。値 true は strict mode を有効にし、値 false は strict mode を無効にします。

INSERT を実行してデータをロードする場合、enable_insert_strict セッション変数を使用して strict mode を設定します。有効な値は true と false です。デフォルト値は true です。値 true は strict mode を有効にし、値 false は strict mode を無効にします。

例は以下の通りです：

Stream Load

curl --location-trusted -u <username>:<password> \
    -H "strict_mode: {true | false}" \
    -T <file_name> -XPUT \
    http://<fe_host>/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 を参照してください。

INSERT

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

INSERT の詳細な構文とパラメータについては、INSERT を参照してください。

Strict mode を理解する​

Strict mode を設定する​

Stream Load​

Broker Load​

Routine Load​

INSERT​