目次 › 第3章 › 3-2

第3章 データロード・アンロードと接続 / 想定学習時間:30〜40分 / 最終確認:2026年8月

3-2. COPY INTOによるバルクロード(検証・エラー処理・ロードメタデータ)

1. COPY INTO の基本:ステージからテーブルへ

ステージに置いたファイルをテーブルにロードする中心的なコマンドが COPY INTO <table> です。これはバルクロード(bulk load)と呼ばれる、まとまったデータを一括で取り込む方式です。

-- 最も基本的な形:ステージのファイルをテーブルへロードする
COPY INTO sales
  FROM @my_stage
  FILE_FORMAT = (FORMAT_NAME = 'my_csv_format');

-- 対象ファイルを絞り込む2つの方法
COPY INTO sales FROM @my_stage
  FILES = ('sales_01.csv.gz', 'sales_02.csv.gz');  -- ファイル名を列挙

COPY INTO sales FROM @my_stage
  PATTERN = '.*sales_2026.*[.]csv[.]gz';           -- 正規表現で指定

COPY INTO の実行には、実行中の仮想ウェアハウスが必要です(ここが 3-3 のサーバーレスな Snowpipe との大きな違いです)。ウェアハウスのサイズは「大きいほど速い」と単純には言えず、並列処理できるのはファイル数までなので、ファイル数に応じたサイズを選ぶのが基本です。ファイルが1つしかなければ、ウェアハウスを大きくしてもそのファイルのロードは速くなりません。

2. ロードメタデータ:64日間の再ロード防止

COPY INTO は、どのファイルをいつロードしたかというメタデータをテーブルごとに 64日間保持します。このおかげで、同じ COPY 文を誤って再実行しても、ロード済みのファイルは自動的にスキップされ、データが二重に入ることを防げます。

• 判定はファイル名と内容(変更の有無)に基づきます。同名でも内容が変わったファイルは再ロード対象になります。
• あえて同じファイルをもう一度ロードしたい場合は、FORCE = TRUE を指定します。この場合は重複チェックを行わずロードするため、データが重複する可能性を理解した上で使います。
• 64日を過ぎたファイルはメタデータが期限切れになり、再実行すると再ロードされ得る点にも注意が必要です。

3. ON_ERROR:エラー行に出会ったときの振る舞い

ロード中に形式不正な行などのエラーに遭遇したとき、どう振る舞うかを決めるのが ON_ERROR オプションです。

4. VALIDATION_MODE:ロードせずに検証する

本番のロードを実行する前に「このファイルはエラーなくロードできるか」を確かめたいことがあります。VALIDATION_MODE を指定した COPY INTO は、データを一切ロードせずに検証だけを行います。

-- ファイルの先頭10行を解析し、変換結果を表示する(ロードはしない)
COPY INTO sales FROM @my_stage
  VALIDATION_MODE = 'RETURN_10_ROWS';

-- すべてのファイルを検証し、見つかったエラーを一覧で返す(ロードはしない)
COPY INTO sales FROM @my_stage
  VALIDATION_MODE = 'RETURN_ERRORS';

-- 過去に実行した COPY のエラーを後から確認する VALIDATE 関数
SELECT * FROM TABLE(VALIDATE(sales, JOB_ID => '_last'));

• RETURN_n_ROWS:先頭 n 行を検証し、問題なければその行を表示します。最初のエラーで停止します。
• RETURN_ERRORS:対象ファイル全体を検証し、すべてのエラーを返します。
• VALIDATE 関数:実行済みの COPY ジョブについて、エラーになった行を後から確認できるテーブル関数です。

5. ロード時の基本変換:できること・できないこと

COPY INTO は、FROM 句に SELECT を書くことで、ロードと同時に簡単な変換を行えます。ただし、できる変換は限定的です。

-- ステージファイルの1列目と3列目だけを、型変換しながらロードする
COPY INTO sales (sale_id, amount)
  FROM (
    SELECT t.$1, CAST(t.$3 AS NUMBER(10,2))
    FROM @my_stage t
  )
  FILE_FORMAT = (FORMAT_NAME = 'my_csv_format');

-- 列名でマッピングする(Parquet などの列名付き形式で便利)
COPY INTO sales FROM @my_stage
  FILE_FORMAT = (TYPE = 'PARQUET')
  MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE;

-- ロード成功後にステージのファイルを自動削除する
COPY INTO sales FROM @my_stage PURGE = TRUE;

6. ロード履歴の確認:COPY_HISTORY と LOAD_HISTORY

「どのファイルがいつ、何行ロードされ、エラーは何件だったか」は、次の手段で確認できます。

-- 直近のロード状況をテーブル関数で確認する
SELECT file_name, row_count, error_count, last_load_time
FROM TABLE(INFORMATION_SCHEMA.COPY_HISTORY(
  TABLE_NAME => 'SALES',
  START_TIME => DATEADD(hour, -24, CURRENT_TIMESTAMP())
));

練習問題