目次 › 第2章 › 2-2

第2章 データ取り込みとロード / 想定学習時間:30〜40分 / 最終確認:2026年8月

2-2. COPY INTOによるクラウドストレージからの増分ロード

1. COPY INTO とは:SQL で書ける冪等な増分ロード

COPY INTO は、クラウドオブジェクトストレージ(S3 / ADLS / GCS)上のファイルを Delta テーブルへ読み込む SQL コマンドです。最大の特徴は冪等性(idempotency)にあります。COPY INTO は「どのファイルをロード済みか」をターゲットテーブル側で記録しており、同じコマンドを何度実行しても、一度ロードしたファイルはスキップされ、新しく追加されたファイルだけが取り込まれます。

このため、同じ COPY INTO 文を毎日スケジュール実行するだけで、増分ロードのパイプラインが完成します。「再実行しても二重ロードにならない」性質は、ジョブの失敗リトライ時にも安全に働きます。

2. 基本構文

構文の骨格は「どのテーブルへ」「どこから」「何形式で」「どんなオプションで」の4要素です。

COPY INTO main.bronze.sales
FROM 's3://my-bucket/landing/sales/'
FILEFORMAT = CSV
FORMAT_OPTIONS (
  'header' = 'true',
  'inferSchema' = 'true'
)
COPY_OPTIONS (
  'mergeSchema' = 'true'
);

FORMAT_OPTIONS と COPY_OPTIONS の役割の違いは選択肢の作り分けに使われます。「ファイルをどう解釈するか」は FORMAT_OPTIONS、「ロード動作をどう制御するか」は COPY_OPTIONS、と対応づけて覚えてください。

3. mergeSchema:スキーマ差分の吸収

ソースファイルに新しい列が増えたとき、既定の COPY INTO はターゲットテーブルのスキーマと一致しないためエラーになります。COPY_OPTIONS ('mergeSchema' = 'true') を指定すると、新しい列をターゲットテーブルのスキーマに自動追加してロードを続行できます。

-- 列が増えたファイルも受け入れる
COPY INTO main.bronze.events
FROM 's3://my-bucket/landing/events/'
FILEFORMAT = JSON
COPY_OPTIONS ('mergeSchema' = 'true');

また、SELECT 句を挟んで列の変換・選択をしながらロードすることもできます。

COPY INTO main.bronze.sales
FROM (
  SELECT
    _c0::INT   AS sale_id,
    _c1::DATE  AS sale_date,
    _c2::DOUBLE AS amount,
    current_timestamp() AS ingested_at
  FROM 's3://my-bucket/landing/sales/'
)
FILEFORMAT = CSV;

4. 実行の流れ

5. COPY INTO が適する場面と Auto Loader との比較

COPY INTO と Auto Loader(2-3)はどちらも「クラウドストレージからの増分ファイルロード」を担うため、使い分けが問われます。

6. 運用上の注意

• ストレージへの認証:Unity Catalog の外部ロケーション(external location)とストレージ資格情報を使ってアクセスを構成するのが標準です。パスへの読み取り権限がなければ COPY INTO は失敗します。
• 再ロードしたい場合:意図的に同じファイルを読み直したいときは COPY_OPTIONS ('force' = 'true') でスキップを無効化できます。ただし重複挿入になるため、通常運用では使いません。
• スケジュール実行:COPY INTO 文を含む SQL を Lakeflow Jobs(旧 Workflows)のタスクとして登録し、日次・時間ごとなどの周期で実行するのが典型パターンです(第4章)。

練習問題