CSVインポート前に前処理が必要な理由

CSVを別のシステムへ取り込む前は、ファイル形式だけでなく、列名・列順・欠損値・コード値・日付形式・キー重複・項目制約を取り込み先の仕様と照合する必要があります。この記事では、問題を含む顧客CSVを例に、元ファイルの確認から少量テストまでを順番に進めます。

利用場面確認が必要になる理由
システム移行旧システムと新システムで項目名やコード体系が異なる
顧客・商品マスター更新IDの一意性、必須項目、許容値などの制約がある
Excelで作成したデータ先頭0、日付、文字コードが意図せず変化することがある
取引先から受け取ったCSV区切り文字、Header、NULL表記などが自社仕様と異なる
毎日・毎月の定期取込形式が同じでも、その回のデータに欠損や重複が含まれる可能性がある

CSVの構文が正しいことと、取り込み先の業務仕様を満たすことは別です。前処理では、まず状態を確認し、仕様に必要な変更だけを行い、完成したCSVをもう一度検証します。

今回使用するCSVと取り込み仕様

次の架空の顧客データを、新しいシステムへ取り込む場面を考えます。この記事では、この同じCSVを最後まで使用します。

CUSTOMER_ID,CUSTOMER_NAME,STATUS_CD,CREATE_DATE,AMOUNT
001001,山田太郎,有効,2026/09/01,1200.50
001002,佐藤花子,無効,20260902,980
001003,鈴木一郎,保留,2026-09-03,ERROR
001002,佐藤花子,無効,2026/09/02,980
取り込み項目取り込み先の仕様
customer_id必須・固定6文字・重複不可
name必須・40文字以内
amount数値・0～999999.99
status0 / 1 / 9 のみ
created_atyyyy-MM-dd
company_code必須・固定値 JP01

元CSVには、列名の違い、不足列、日付形式の混在、amount = ERROR、日本語のstatus、customer_id = 001002の重複があります。どの値を直すべきかはCSVだけでは決められないため、以降はこの仕様を判断基準にします。

CSVインポート前処理の全体フロー

元CSVを診断し、列構造と値を変換してから制約確認とテスト取込を経て本番取込へ進む流れ
先に変換を始めず、元CSVの診断と取り込み仕様の確認を済ませてから工程を分けます。

すでに仕様と一致している工程は省けます。ただし、各工程でプレビューを確認し、変換後のファイルを次の工程へ渡すようにすると、どこでデータが変化したか追跡しやすくなります。

1. 元CSVを変更せずに保存する

受け取ったCSVを直接上書きせず、原本と作業用コピーを分けます。たとえば、customers_original.csv、customers_structure.csv、customers_values.csv、customers_final.csvのように主要工程ごとに保存すると、問題が起きたときに戻れます。

最終ファイルで意図した項目だけが変わったか確認する場合は、CSV 差分比較で原本と整形後を比較できます。ただし、列名や列構造を大きく変えた場合は、比較対象の列を揃えてから確認します。

2. 元CSVのファイル形式と列の状態を診断する

最初にCSV 文字コード・総合診断で文字コード、BOM、改行、区切り文字、Header、列数を確認します。Headerの空欄・重複・前後空白はCSV ヘッダー確認、レコードごとの項目数はCSV 列数チェックで詳しく確認できます。

次にCSV 列型判定で、各列の値が文字列、数値、日付などのどれに見えるかを把握します。今回の例では、次のような結果が想定されます。

UTF-8、BOMなし、カンマ区切り、5列のCSVでamount列の型混在とcustomer_idの重複候補が見つかった診断例
ファイル形式には大きな問題がなくても、列の値やキーには取り込み前に確認すべき点があります。
自動判定は確認の手掛かりです

文字コードや列型の推定は100%ではありません。特に001001のようなIDは数字だけでも文字列として扱う必要があります。推定結果をそのまま変換指示にせず、取り込み仕様と照合してください。

列ごとの最小値・最大値、小数桁数、値の一覧を調べて列定義表にまとめる手順は、CSVの各列のデータ型と値の範囲を調べる方法で詳しく解説しています。

3. 取り込み先に合わせて列構造を変更する

今回のCSVでは、足りないcompany_codeをCSV 列追加で追加し、全レコードへ仕様書で決められたJP01を設定します。固定値を入れてよいのは、すべての行が同じ会社に属することを確認できる場合だけです。

次にCSV 列名変換・マッピングでHeaderを変更し、CSV 列並び替えで取り込み先の列順へ揃えます。不要列がある場合だけ、CSV 列抽出で必要な列を選びます。

操作変わるもの変わらないもの
列名変換Headerの名前データセル・列位置・行順
列並び替え列の位置レコードの順序
列追加新しいHeaderとセル既存列の値
列抽出残す列残した列内の値と行順
変更前
CUSTOMER_ID,CUSTOMER_NAME,STATUS_CD,CREATE_DATE,AMOUNT

構造変更後
customer_id,name,amount,status,created_at,company_code

「CSV 列並び替え」は列の位置を変える操作です。値を基準にレコードの順序を変える「CSV 並び替え」と混同しないようにします。

4. 欠損値・コード値・日付形式を変換する

構造を揃えたら、セルの値を取り込み仕様へ合わせます。NULL、N/A、空欄などを統一する必要があればCSV 欠損値・NULL表記統一を使います。ハイフンなどが実データとして使われる列まで一括変換しないよう、対象列を確認します。

statusはCSV 値マッピング・置換で、セル全体が一致する値を有効 → 1、無効 → 0、保留 → 9へ変換します。CSV 日付形式チェック・統一では、2026/09/01や20260902を仕様のyyyy-MM-ddへ揃えます。

列名、固定列、status、日付を変換前・変換ルール・変換後の3列で比較した例
変換ルールはCSVから自動決定せず、取り込み先の正式な仕様に基づいて設定します。
amount = ERRORは自動修正しない

ERRORを0や空欄へ変えると、元の金額が不明なまま意味を変えてしまいます。データ担当者へ確認する、元システムから再取得する、または対象項目が空欄を許可する場合だけ仕様に従って空欄にします。必須項目なら、解決するまで本番インポートへ進めません。

同じ「有効」でも、取り込み先によって1、A、trueなどの表現があり得ます。KantanToolsはユーザーが指定した対応表を処理しますが、どのコードが業務上正しいかは決定しません。

5. ID・複合キーの重複を確認する

CSV 重複チェック・削除で、今回のcustomer_id = 001002のような重複候補を確認します。行全体が同じ「重複行」と、一部の値が異なってもIDが同じ「キー重複」は別の問題です。

重複が見つかっても、機械的に1行を削除できるとは限りません。更新日時が新しい方を残す、原本と照合する、複数の情報を統合するなど、業務上の根拠が必要です。また、実際の一意条件がcompany_code + customer_idなら、1列ではなく複合キーで確認します。

6. 取り込み仕様を列制約として検証する

CSV 列制約チェックへ取り込み仕様を設定し、必須、固定文字数、最大文字数、データ型、数値範囲、許容値、日付形式を確認します。キーの一意性は重複チェック結果と併せて判断します。

プロファイリング実際に何が入っているかを推定する
マッピング・変換仕様に合わせる変更ルールを実行する
バリデーション完成した値が仕様を満たすか検証する

たとえばstatusを変換する前に「0 / 1 / 9のみ」という制約を適用すれば、日本語の値は違反になります。これは診断の失敗ではありません。変換前は差を把握し、変換後のCSVに同じ制約を適用して最終合否を確認します。

7. 整形後のCSVを再診断する

変換処理が完了しただけでは、インポート準備完了とは判断できません。整形後のCSVをCSV 文字コード・総合診断とCSV 列制約チェックへもう一度通し、想定外の変更がないか確認します。

Header、列順、必須項目、status、日付形式、キー重複、文字コードを確認する最終チェック例
エラー件数だけでなく、設定した制約が取り込み先の最新仕様と一致しているかも確認します。

原本と完成版で変更箇所を確認する場合はCSV 差分比較も利用できます。列追加や列名変更を実施した場合は構造差分が出るため、意図した変更と予期しない値変更を分けて確認してください。

8. 完成したCSVを確認する

重複する001002について正式な記録を1件残し、amount = ERRORは「この項目では空欄を許可する」と担当者に確認できた場合、完成例は次のようになります。

customer_id,name,amount,status,created_at,company_code
001001,山田太郎,1200.50,1,2026-09-01,JP01
001002,佐藤花子,980,0,2026-09-02,JP01
001003,鈴木一郎,,9,2026-09-03,JP01

これは条件付きの例です。取り込み先でamountが必須なら、3件目はまだ取り込めません。ERRORを空欄や0に変えること、重複行のどちらを残すことも、ツールが自動で正解を判断した結果ではありません。

9. 5～10件の少量データでテストする

取り込み先がテストに対応している場合は、すぐに全件を投入せず、正常値・空欄・日本語・先頭0・日付・各statusを含む5～10件程度で試します。

  • 日本語が文字化けしていない
  • 001001の先頭0が残っている
  • 日付が意図した日として登録される
  • statusが正しい意味で登録される
  • 新規追加・更新のモードが想定どおり
  • 空欄がNULLや0へ誤変換されていない

テスト成功後も、件数上限、権限、参照先マスター、テンプレートの版など、取り込み先固有の条件を確認してから本番処理へ進みます。KantanToolsでエラーが0件でも、あらゆるシステムへの取り込み成功を保証するものではありません。

前処理とインポートエラー調査の違い

この記事は、正式な取り込み前に仕様を確認し、構造と値を計画的に整えるための手順です。すでにインポートに失敗しており、表示されたエラーや症状から原因を絞り込みたい場合は、CSVが読み込めない・インポートできない原因と確認方法を参照してください。