Snowflake COPY INTO実務設計ガイド｜ロード・アンロード・FILE FORMAT

COPY INTOはSnowflakeのデータロード/アンロードの中核コマンドです。ステージからテーブルへのバルクロードとテーブルからステージへのデータエクスポートの両方を1つのコマンドで実行でき、FILE FORMAT・ON_ERROR・VALIDATION_MODEなどの豊富なオプションにより柔軟なデータパイプラインを構築できます。

SnowPro Core試験ではDomain 4（Data Loading & Unloading / 配点10〜15%）で出題され、Data Engineer試験ではさらに深いオプション知識が問われます。この記事では、実務設計の観点からCOPY INTOの全体像を整理し、試験頻出ポイントを解説します。

COPY INTO（ロード）構文

ステージからテーブルにデータをロードする基本構文です。

COPY INTO <テーブル名>
  FROM @<ステージ名>/<パス>/
  FILE_FORMAT = (FORMAT_NAME = '<ファイルフォーマット名>'
                 | TYPE = CSV | JSON | PARQUET | AVRO | ORC | XML)
  PATTERN = '.*\.csv\.gz'
  ON_ERROR = ABORT_STATEMENT | CONTINUE | SKIP_FILE | SKIP_FILE_<N>
  PURGE = TRUE | FALSE
  FORCE = TRUE | FALSE;

主要パラメータ

COPY INTOのロード重複防止メカニズム

COPY INTOはデフォルトで64日間のロード履歴メタデータを保持し、同じファイルの重複ロードを自動的に防止します。ファイルのパス・サイズ・最終更新日時がメタデータと一致する場合、そのファイルはスキップされます。この動作はFORCE = TRUEで上書きできますが、通常は重複防止を有効にしたまま運用するのがベストプラクティスです。

COPY INTO（アンロード）構文

テーブルからステージにデータをエクスポートする構文です。

COPY INTO @<ステージ名>/<パス>/
  FROM <テーブル名> | (<SELECT文>)
  FILE_FORMAT = (TYPE = CSV | JSON | PARQUET)
  SINGLE = TRUE | FALSE
  MAX_FILE_SIZE = <バイト数>
  HEADER = TRUE | FALSE
  OVERWRITE = TRUE | FALSE;

主要パラメータ

アンロード時のFROM句にはSELECT文を直接指定できるため、テーブル全体ではなくフィルタリング・集計・変換を行った結果をエクスポートすることが可能です。

FILE FORMAT の設計

FILE FORMATはデータの形式と解析ルールを定義するオブジェクトです。名前付きFILE FORMATとして事前に作成しておくことで、COPY INTO文のたびにオプションを記述する必要がなくなります。

CREATE FILE FORMAT my_csv_format
  TYPE = CSV
  FIELD_DELIMITER = ','
  RECORD_DELIMITER = '\n'
  SKIP_HEADER = 1
  FIELD_OPTIONALLY_ENCLOSED_BY = '"'
  NULL_IF = ('NULL', 'null', '')
  EMPTY_FIELD_AS_NULL = TRUE
  COMPRESSION = GZIP;

対応フォーマットと用途

ON_ERROR オプションの使い分け

ON_ERRORはデータロード時のエラーハンドリング戦略を決定する重要なパラメータです。

ON_ERROR = CONTINUEを使用した場合、スキップされたエラー行の詳細はVALIDATE関数で事後確認できます。SELECT * FROM TABLE(VALIDATE(my_table, JOB_ID => '_last'))で直前のCOPY INTOのエラー行を取得できます。

VALIDATION_MODE（ドライラン）

VALIDATION_MODEを指定するとデータのロードは行われず、ファイルの検証結果のみを返します。本番ロード前の事前チェックに必須の機能です。

COPY INTO my_table
  FROM @my_stage/data/
  FILE_FORMAT = (FORMAT_NAME = 'my_csv_format')
  VALIDATION_MODE = 'RETURN_ERRORS';

ステージの種類と選択基準

実務設計のベストプラクティス

1. 名前付きFILE FORMATを必ず作成する

COPY INTO文にインラインでフォーマットオプションを記述すると、メンテナンスが困難になります。CREATE FILE FORMATで名前付きオブジェクトを作成し、COPY INTO文ではFORMAT_NAME参照を使用してください。フォーマットの変更が発生した場合、FILE FORMATオブジェクト1箇所の修正で全COPY INTO文に反映されます。

2. VALIDATION_MODEで事前検証を行う

特に外部パートナーから受領したCSVファイルなど、品質が保証されていないデータをロードする場合は、VALIDATION_MODE = 'RETURN_ERRORS'で事前検証を実施してください。ファイルフォーマットの不一致・データ型エラー・NULL制約違反を本番ロード前に検出できます。

3. PURGE = TRUEでステージをクリーンに保つ

ロード完了後のファイルをステージに残したままにすると、ストレージコストが累積し、次回のCOPY INTO実行時にファイル一覧の取得が遅くなります。PURGE = TRUEを指定してロード済みファイルを自動削除するか、定期的にREMOVE @stageでクリーンアップしましょう。

4. ファイルサイズを100〜250MBに最適化する

Snowflakeのドキュメントでは、COPY INTOの最適なファイルサイズとして圧縮後100〜250MBを推奨しています。ファイルが小さすぎると（数KB〜数MB）オーバーヘッドが大きくなり、大きすぎると（1GB超）並列処理の効率が低下します。

問題で確認

よくある質問（FAQ）