Snowflake COPY INTO 失敗原因と解決チェックリスト

はじめに：COPY INTOで詰まったときはここを見て!
COPY INTOってそもそも何をしている?
エラー別チェックリスト
原因特定に便利な2つのオプション
まとめ
参考リンク
関連記事
1. ▶次に読むべき記事

はじめに：COPY INTOで詰まったときはここを見て!

こんにちは!Snowflakeにデータを取り込むときの定番コマンドといえば COPY INTO ですよね。でも、いざ実行すると「ファイルが見つかりません」「型が合いません」など、思いがけないエラーで止まってしまうことが結構あります。

この記事では、初心者の方が COPY INTO でつまずきやすい原因をエラー別チェックリスト形式で整理します。

COPY INTOってそもそも何をしている?

COPY INTOは、Snowflakeのステージ(クラウドストレージのような置き場)にあるファイルを読み込み、テーブルに行として書き込むコマンドです。流れはざっくり以下の4ステップ。

① ステージにあるファイルを探す
② ファイルフォーマット(CSV/JSON/Parquetなど)で中身を解釈する
③ 各列をテーブルのカラムにマッピングする
④ テーブルへ書き込む

失敗するときは、この4ステップのどこかで引っかかっています。原因をこの単位で切り分けると、ぐっと解決しやすくなります。

エラー別チェックリスト

1. 「File not found」「No files matched」が出る

ステップ①の問題です。指定したパスにファイルが本当に存在しているか、まず LIST で確認しましょう。

LIST @my_stage/path/;
-- ファイルが見えるか?パターンは正しいか?

注意点としては、ステージのパスは大文字小文字を区別することと、すでに一度ロードしたファイルは LOAD_HISTORY によりスキップされる点です。再ロードしたい場合は FORCE = TRUE を付けます。

2. 「Number of columns in file does not match…」が出る

ステップ②③の問題で、ファイルの列数とテーブルの列数がズレている時に発生します。CSVの区切り文字やエスケープ設定が合っていないことも原因です。

CREATE OR REPLACE FILE FORMAT my_csv
  TYPE = CSV
  FIELD_DELIMITER = ','
  SKIP_HEADER = 1
  FIELD_OPTIONALLY_ENCLOSED_BY = '"';

ヘッダー行をスキップしていなかったり、ダブルクォートで囲まれた値の中にカンマがあったりするケースが多いので、ファイルフォーマットを丁寧に見直してみてください。

3. 「Numeric value is not recognized」「Date is not recognized」

これはデータ型変換の失敗です。CSVの文字列をテーブルの DATE や NUMBER に入れようとして失敗します。日付フォーマットの指定不足が定番なので、Snowflake「Date is not recognized」エラーの原因とTO_DATE/TRY_TO_DATEの使い分けも合わせて読むと理解が深まりますよ。

CREATE OR REPLACE FILE FORMAT my_csv
  TYPE = CSV
  DATE_FORMAT = 'YYYY/MM/DD'
  NULL_IF = ('', 'NULL');

4. 「String ‘…’ is too long and would be truncated」

VARCHAR の桁数より長い文字列を入れようとした時のエラーです。テーブル定義の桁数を広げるか、ファイル側を見直しましょう。詳しくは「String is too long」エラーの対処法で解説しています。

5. 「Insufficient privileges」「Object does not exist or not authorized」

ステージやテーブルに対する権限不足です。現在のロールで USAGE(ステージ)や INSERT(テーブル)が付与されているか確認しましょう。

SHOW GRANTS ON STAGE my_stage;
SHOW GRANTS ON TABLE my_table;

権限エラーは Insufficient privileges to operate on の解決手順やObject does not exist or not authorized エラーの記事が参考になります。

原因特定に便利な2つのオプション

失敗を未然に防いだり、原因を切り分けたりするのに役立つのが VALIDATION_MODE と ON_ERROR です。

-- 実際にロードせず、エラー行だけ返す
COPY INTO my_table
  FROM @my_stage
  FILE_FORMAT = (FORMAT_NAME = my_csv)
  VALIDATION_MODE = 'RETURN_ERRORS';

-- エラー行はスキップして続行
COPY INTO my_table
  FROM @my_stage
  FILE_FORMAT = (FORMAT_NAME = my_csv)
  ON_ERROR = 'CONTINUE';

本番投入前に VALIDATION_MODE = 'RETURN_ERRORS' を使うのが安全です。また、過去の失敗履歴は COPY_HISTORY ビューで確認できます。