Snowflake：COPYコマンドで使用するオプション理解（ユースケース込み）

1.COPYコマンドとは

ステージングされたファイルから既存のテーブルにテーブルをロードするもの。
ファイルは、次のいずれかの場所にすでにステージングされている必要がある。

・内部ステージ
・外部ステージ

ここからはCOPYコマンドの際に使用するオプションの解説理解を記載しています。

FILES

ロードする１つ以上のファイル名のリストを指定するもの。
指定されたいずれのファイルも見つからない場合、COPYステートメントで別の
ON_ERRORオプションが明示的に設定されていない限り、デフォルトの動作
ON_ERROR = ABORT_STATEMENTはロード操作を中止します。

このように、明示的にロードしたいデータが決まっている場合は、FILESコマンドを使用してロードします。

// FILESオプションでファイルを指定してロード
copy into <table> from <stage名>
file_format = CSV
files = ('/data_2013_0_0_0.csv.gz', '/data_2013_0_1_0.csv.gz);

PETTERN

正規表現で、あるステージにあるファイルを選択することができます。

注釈
ステージングの設計にも繋がりますが、基本的にPETTERNはFILESよりも処理が遅いとされています。
そのため、やむを得ず、正規表現を使わないといけない場合以外は
PETTERNを使わないようにステージングを設計するのが良いです。

COPY INTO your_table
FROM @your_stage
PATTERN = '.*customer_txn.*\.csv'
-- FILE_FORMAT = (TYPE = 'CSV' FIELD_OPTIONALLY_ENCLOSED_BY='"' SKIP_HEADER=1);

注釈
FILES と PATTERN オプションを一緒に使うと、 FILES オプションで指定したパスだけが読み込まれます。この2つのオプションは併用しないことをお勧めします。

copyOptions

ON_ERROR

CONTINUE

エラーが見つかった場合は、ファイルのロードを続行します。COPY ステートメントは、データファイルごとに見つかった最大1つのエラーのエラーメッセージを返します。

ROWS_PARSED 列の値と ROWS_LOADED 列の値の差は、検出されたエラーを含む行の数を表します。
ただし、これらの各行には複数のエラーが含まれる可能性があります。データファイルのすべてのエラーを表示するには、 VALIDATION_MODE パラメーターを使用するか、 VALIDATE 関数をクエリします。

SKIP_FILE

エラーが見つかった場合は、スキップする

注釈
エラーが見つかったどうかに関係なく、ファイル全体をバッファーするため
CONTINUEやABORT_STATEMENTよりも低速です。

そのほかにもあまり使う機会が少ないですが
SKIP_FILE_<num>である数がエラーが起きた場合は、ファイルをスキップしたり
SKIP_FILE_<num>%でエラー行の割合が指定された割合を超えた場合に、ファイルをスキップしたりします。

SIZE_LIMIT

特定のCOPYステートメントに対してロードされるデータの最大サイズを指定する数値です。
通常、複数のCOPYステートメントを使用してファイルの共通グループをロードするために使用されます。

例えば、ステージパスの一連のファイルサイズがそれぞれ１０MBであり
複数のCOPYステートメントがそれぞれ２５MBで設定した場合、それぞれが３ファイルをロードした際、閾値を超えるため、エラーが起きます。

ロードする場合を除き、SIZE_LIMITに指定された値に関係なく、少なくとも１つのファイルはロードされます。

PURGE

データが正常にロードされた後、ステージからデータファイルを自動的に削除するかどうかを指定するブール値です。

RETURN_FAILED_ONLY

ステートメント結果でロードに失敗したファイルのみを返すかどうかを指定する

FORCE

以前にロードされたかどうか、ロード後に変更があったかどうかに関係なく、全てのファイルをロードするように指定するブール値。

TRUEにした場合、ファイルを再ロードし、テーブル内のデータを複製する可能性があります

データの変換ミスがあった場合に、再度ロードしたい場合などに有効です

ENFORCE_LENGTH

ターゲット列の長さを超えるテキスト文字列を切り捨てるかどうかを指定するブール値
デフォルトはTRUEのため、ステートメントはエラーを生成することになります。

FALSEにした場合は、ターゲットの長さに自動で切り捨てられます。

MATCH_BY_COLUMN_NAME

半構造化データをロードする際に、
ターゲットとのカラム名の順序が異なる場合に使用します。

例えば以下のようなテーブルとファイルがあるとします。

CREATE OR REPLACE TABLE employees (
    id INT,
    name STRING,
    department STRING
);

CSVデータ

name,department,id
Alice,HR,1
Bob,IT,2
Charlie,Finance,3

カラム名の順番が一致していないことがわかります。
このようなケースにこのオプションを使用します。

大文字や小文字を判別させたい場合は
MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

判別させなくても問題ない場合は
MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;