CSVインポートのカラムマッピングUI：安全な照合、デフォルト、プレビュー

なぜCSVインポートはイライラするのか

多くの人がCSVインポートに期待するのはひとつだけです：「スプレッドシートをアプリに入れてほしい」。でも最初の画面で理解できない判断を求められ、インポートはランダムに失敗したように感じられることが多いです。

CSVは見た目よりずっと散らかっています。ヘッダーがないこともあれば、フィールド名と綴りが違ったり重複したりします（「Email」「email」「Email Address」）。日付は奇妙な形式だったり、電話番号の先頭ゼロが消えたり、住所内のカンマが列を壊したりします。いわゆる「きれいな」エクスポートでも、メモや内部ID、末尾の空列のような余計な列が混ざっていることがあります。

恐れは現実的です：間違って推測すると、正しいデータが上書きされるのか、何百件もの壊れたレコードが作られるのか、あるいはシステム全体にゴミが散らばるのか。良いCSVインポートのカラムマッピングUIは、何も書き込む前に何が起きるかを見せて、その不安を取り除きます。

「マッピング」は単に照合することです。つまり、このCSV列はアプリのあのフィールドに入ります、という意味です。たとえばCSVの「Company」は「Account name」に対応し、「Start Date」は「Customer since」に対応する、というように。理論上は単純ですが、名前が一致しないと簡単に間違えます。

安全なインポートは期待値を明確にし、予測可能な手順に従います：

• 列をフィールドにマッチさせる（マッピング）
• データが欠けているときの扱いを決める（デフォルト）
• 問題をチェックする（検証）
• 結果を表示する（プレビュー）
• そして初めてレコードを書き込む

ユーザーがこの順序を理解すると、インポートは罠ではなくガイド付きのチェックリストになります：照合を行い、空白を埋められる場所を補い、見えるエラーを直して、自信を持ってインポートするのです。

良いカラムマッピング画面が果たすべきこと

CSVインポートのカラムマッピングUIの仕事は一つ：何も保存される前に何が起きるかを明確に示すことです。ユーザーは、新しいレコードが作られるのか、既存が更新されるのか、行がスキップされるのかを推測してはいけません。

画面は次の問いに明確に答えるべきです：

• 何が作成されるのか（新規レコード）、どのテーブルやオブジェクトに入るのか
• 何が更新されるのか、そしてどのフィールドでマッチを探すのか（例：emailや外部ID）
• 何がスキップされるのか、そしてその理由（必須フィールドの欠落、重複、無効な値）
• アップロードされたファイルから得た実際の件数で、各グループに影響する行数
• 値が空の場合にシステムがどうするか（空のまま、デフォルトを使う、既存値を保持する）

必須フィールドは特別に扱う必要があります。上部に表示し、必須であることを明示し、各必須フィールドがマップされるか明示的なデフォルトが設定されるまでマッピングを完了させないでください。任意のフィールドはマッピングしなくても構いませんが、UIはユーザーが何を無視することを選んでいるかを示すべきです。

ユーザーは式を書くことなく基本的なクリーンアップを期待します。マッピングの場で簡単な変換を提供しましょう。余分な空白をトリムする、数値形式を変換する、日付形式を選ぶなどです。たとえばCSVに " New York " があれば、トリムオプションはプレビューで "New York" に変わることを示すべきです。

すべての問題がインポートを止めるべきではありません。問題をブロック（必須）と警告に分け、その違いを平易な言葉で説明してください。

• ブロック：必須フィールドがない、日付が解析できない、更新のキーが空など
• 警告：電話番号の書式が異常、値が切り詰められる、未知のフィールドで無視されるなど
• 警告がある場合でもインポートを許可し、そのときに何行影響を受けるかを示す

これらの基本を正しく実装すれば、インポートフロー全体が穏やかになります：ユーザーがコントロール感を持ち、「なぜ間違ってインポートされた？」というサポートチケットが減ります。

CSV列とフィールドの照合を助ける方法

良いCSVインポートのマッピングUIは、パズルではなく助けるアシスタントのように感じられるべきです。まずは最初の行をヘッダーとして読み取り、すぐに候補を提示しましょう。単純な類似度（"email" -> "Email"）や小さな同義語リスト（"Phone" vs "Mobile", "Zip" vs "Postal code", "Company" vs "Organization"）を使います。

候補は穏やかで明確に伝わるのがベストです。マッチを「完全一致」「可能性高」「不確か」のように示します。ヒントは小さなラベルやアイコンに留め、ユーザーが速くスキャンできるようにします。

ユーザーがいつでも上書きできる手段を用意してください。ドロップダウンは十分ですが、検索ボックスを加え、ユーザーが素早くフィールド名を入力して選べるようにします。フィールドが多い場合はカテゴリ（Contact, Address, Billingなど）でグループ化してリストを圧倒的でないものにします。

誤ったインポートを防ぐために、競合を作りにくくします：

• デフォルトではターゲットフィールドに対して1つのCSV列のみ許可する
• 既にマップされているフィールドを選ぶと明確な警告を表示し、既存のマッピングを上書きするか尋ねる
• サポートされている場合のみ明示的な「結合」オプションを提供する（例：First name + Last name）
• まだマップされていない必須ターゲットフィールドを強調表示する

小さな例：ユーザーがスプレッドシートから「Mobile」と「Phone」をインポートした場合、両方を同じ「Phone」フィールドにマップすると上書きが発生します。UIはそれを止めて、どちらかを「Mobile」にマップするか、一方を無視するなどの代替策を提案すべきです。

AppMasterでこれを構築するなら、マッピングステップを高速に：自動提案、検索、競合選択のブロックを入れてください。多くのインポート問題はここで始まるので、驚きを減らすほどデータはきれいになります。

空や間違ったレコードを防ぐデフォルト

マッピング画面はフィールドを照合するだけでなく、CSVのセルが空だったときにどうするかを決めるべきです。これを怠ると、中途半端に埋まったレコードや、見た目は妥当でも間違ったデータが生まれます。

マップされた各フィールドに対して、明確な「空の場合の動作（When blank）」の選択肢を提供してください。これを同じマッピング行内で見えるようにして、一覧を見ているときに見落とさないようにします。

多くのチームが必要とする3つの振る舞いは次の通りです：

• 空のままにする（行はインポートされ、フィールドは空欄）
• デフォルト値を使う（既知のフォールバックでインポート）
• 行を拒否する（その行を失敗させ、理由を示す）

デフォルトは追加のセットアップなしで単純なケースをサポートするべきです。例：status = Active、country = US、owner = current user、source = “CSV import”。CSVインポートのマッピングUIでは、こうしたデフォルトが初回のインポートをきれいにするかどうかの差になります。

create（新規作成）とupdate（更新）の扱いでユーザーが混乱しがちです。更新が可能なインポートの場合（例：emailやIDで更新する）、デフォルトの挙動を明示してください：

• 作成時（On create）：デフォルトは新規レコードの欠損値を埋める
• 更新時（On update）：デフォルトは通常既存データを上書きしない（ユーザーが選ばない限り）

実用的なルール："CSV内で空" と "フィールドがそもそもマップされていない" を区別してください。ユーザーがフィールドをマップして「Leave empty」を選んでいる場合は「クリアする」意図かもしれません。マップしていない場合は通常「触らないでほしい」という意図です。

最後に、デフォルト値はマップされたフィールドの隣に表示してください。設定アイコンの奥に隠さないでください。小さなインラインのピル（例：「Default: Active」）と一行のヒント（「空の場合のみ使用」）が驚きを防ぎ、サポートチケットを減らします。

書き込み前に結果とエラーをプレビューする

プレビューはCSVインポートの信頼を得る瞬間です。ユーザーは何も保存される前に何が起きるかを見られるべきで、問題が理解可能で修正可能であると感じるべきです。

まずは小さく高速なサンプルプレビュー（例：最初の20〜50行）と、ファイル全体の簡単な件数サマリを出します。サマリは人々が実際に知りたい問いに答えるべきです：作成される行数、更新される行数、問題のある行数、スキップされる行数。

エラーは視覚的かつ具体的に示します。失敗する正確なセルをハイライトし、セル横かサイドパネルに短い理由を出します。行に複数の問題がある場合は最初の問題を明確に示し、展開して残りを見られるようにします。

平易な言葉で説明する一般的な理由は：

• 必須値がない（例：Emailは必須です）
• 形式が間違っている（例：Invalid date format: use YYYY-MM-DD）
• 型が違う（例：Quantityは数値である必要があります）
• 未知の値（例：Statusは Active, Paused, Closed のいずれか）
• 長すぎる（例：Notesは最大500文字まで）

フィルタリングは大きなQOL向上です。「エラーだけ表示」トグルや、プレビュー内を検索できるボックスを追加してください。これによりユーザーは大量のOK行をスクロールする代わりに、注目すべき行に集中できます。

技術的な言葉は避けてください。ユーザーは「Parse exception」や「Constraint violation」を見てはいけません。何が、どこ（行と列）、次に何をすればいいかを伝えます。AppMasterのような製品では、この種のプレビューが特に役立ちます。ユーザーは単なるテーブルではなく実際のビジネスロジックや検証にインポートしていることが多いからです。

インポート内でデータを修正する方法

良いCSVインポートのマッピングUIは、問題を指摘するだけで終わってはいけません。ユーザーがその場で素早く安全に修正できる手段を与えるべきです。

失敗している列の横にインラインで修正手段を置くことから始めましょう。システムが日付を解析できない場合、期待する日付形式（MM/DD/YYYYやDD/MM/YYYYなど）を選ばせ、即座にプレビューを再実行します。列に "Yes/No" が入っていてフィールドが true/false を期待しているなら、単純な変換トグルを提供します。

固定された値集合を持つフィールド（status, state, plan）では、値マッピングが最大の時間短縮になります。インポートが "NY" を見てアプリが "New York" を保存している場合、ユーザーは一度マップすればすべての行に適用できます。同様に "active", "Active", "ACTIVE" を単一の許容値に統一するのも同じ考えです。

よくある修正のクイックアクション例：

• 先頭・末尾の空白をトリムする
• 空白をデフォルトで置き換える（例：「Unknown」）
• 桁区切りを削除する（"1,200" -> "1200"）
• 電話番号を正規化（数字のみを保持）
• 名前をTitle Caseに変換する

これらのアクションは可逆にしてください。何が変わるか、何行に影響するかを示し、Undoを許可します。選択した列に対する小さな「ビフォー/アフター」プレビューは驚きを防ぎます。

アプリ内で修正できないことについては明確に伝えてください。列が丸ごと欠けている、エスケープされていないカンマで行がずれている、ファイルが途中で別のヘッダーを混ぜている、などの場合はCSVを編集するのが最良です。そのことを平易に説明してください。

単純な例：600行が "CA "（末尾にスペース）を持っているなら、ワンクリックでそれをクリーンにして検証を通過させるべきです。

シンプルなステップバイステップのインポートフロー

良いCSVインポートのマッピングUIは、いくつかの小さな判断に仕事を分けることで落ち着いて見えます。ユーザーは次に何が起きるか、データに何が起きるかを常に知っているべきです。

アップロードから始めます。ファイルを選んだらすぐに区切り文字とエンコーディングを検出し、簡単なプレビュー（ヘッダーと最初の1〜2行）を表示します。ここで区切り文字ミスで一列しかない、またはエンコーディングの問題で文字化けがあることに気づきます。

次にインポートの振る舞いを尋ねます。新規作成するのか、既存を更新するのか、あるいはアップサートか。更新やアップサートを選ぶ場合は識別子（email、外部ID、注文番号など）を必須にし、その識別子列に空や重複があると警告を出します。

次にマッピングとデフォルトに移り、検証を実行します。どのCSV列が各フィールドを満たすか、どのフィールドがデフォルトを使うか、どのフィールドが空のままになるかを確認させます。検証は高速で具体的に行い、型、必須フィールド、重複、参照ルールをチェックします。

シンプルなフロー例は以下の通りです：

• ファイルをアップロードして数行をプレビュー
• モードを選択：create, update by key, または upsert（キーを選ぶ）
• マッピングとデフォルトを確認して検証を実行
• エラーを確認して修正（またはエラー行のみをエクスポート）
• インポートを実行し完了サマリを表示

エラーレビューの段階ではユーザーが先に進めるようにします。エラータイプごとの件数を表示し、エラー行だけにフィルタでき、次のアクションを分かりやすく：その場で修正、行を無視、問題行をダウンロードして編集して再アップロード、などを示します。

終了時には「作成」「更新」「スキップ」「失敗」した件数と、どのキーで照合したかを明確に示すサマリを出します。AppMasterのようなツールなら、このサマリはUIが期待したものではなく、バックエンドが実際に書き込んだ内容と一致するべきです。

避けるべきよくある落とし穴

カラムマッピング画面は、ユーザーがフィールドをマッチさせて「インポート」をクリックできれば「完成」と見なされがちです。本当の問題はデータがシステムに入ったあとに現れます：重複、静かな変更、誰も修正できないエラーなどです。

古典的な落とし穴の一つは、固有の識別子なしで更新スタイルのインポートを実行できてしまうことです。ユーザーがCustomer IDやEmailなどの一意を保証するフィールドをマップできない場合、既存レコードを確実に更新できません。結果として重複した見かけ上有効なレコードが生まれます。識別子が欠けている場合は、UIで明確に伝え、次の選択肢を提示してください：「新規としてインポートする」か「停止してIDを追加する」か、など。

もう一つの微妙な問題は、静かな型変換です。"00123" のような値は番号に見えても実際にはコードかもしれません。インポートで123に変換すると先頭ゼロが失われ、後で照合が壊れます。ZIPやSKU、アカウントコードのような数値っぽい文字列は慎重に扱ってください。型を変換する場合は、プレビューでビフォー・アフターを示します。

検証は二つの方向で失敗し得ます。厳しすぎると害のない行をブロックする（任意の電話番号がないなど）。ゆるすぎるとゴミを作る（空の名前、無効なメール、意味のない日付）。より良いアプローチは区別することです：

• ブロッキングエラー（インポート前に修正が必要）
• 警告（インポートは可能だが確認が必要）
• 自動修正（空白トリム、ケース正規化など）はプレビューで見えるようにする

エラーメッセージが役に立たなくなる理由は、それが正確なセルを指していないからです。フィードバックは常に特定の行と列に結び付け、元の値を含めてください。"Row 42, Email: 'bob@' is not a valid email" は "Invalid data found" よりずっと役に立ちます。

最後に、最終確認を曖昧にしないでください。ユーザーは何が起きるかを見たいのです：何件が作成され、何件が更新され、何件がスキップされるのか。更新がある場合は、どの識別子で照合するかを示して、誤ったマッピングで実データを上書きする前に検出できるようにします。

ユーザーがインポートをクリックする前の簡単チェック

クリック直前、ユーザーは単純な問いをしています：「私のデータを壊そうとしているか？」良いCSVインポートのカラムマッピングUIは、明確で退屈だが信頼感を与えるチェックリストでそれに答えます。

まずは小さな実データのプレビューを見せます。10〜20行のサンプルで、多くの人は列のずれ、奇妙な日付形式、余分な空白などの明らかな問題に気づけます。プレビューは現在のマッピングを反映するべきで、生のCSVではなく「どのように書き込まれるか」を示す必要があります。

次に必須フィールドを見落とせないようにします。必須フィールドがマップされていない場合は決定を強制します：マップする、デフォルトを設定する、または停止する。失敗インポートの後で必須値が欠けていたことに気づかせてはいけません。

空セルの扱いを平易な言葉で示します。空が「空のままになる」のか「更新時は既存値を保持する」のか「デフォルトを適用する」のかを伝えます。マッピング行に小さなテキスト（例：「Blank = keep existing value」）を置くだけで多くの失敗を防げます。

最後に、ユーザーが問題に集中できるようにします。問題がある場合はエラーや警告だけにフィルタするビューを提供し、理由を行のそばに表示してください。修正が現実的に感じられます。

ここに最終ボタンの上に置ける簡単な事前チェックリストを示します：

• プレビューは現在のマッピングが適用されたサンプル行を表示している
• すべての必須フィールドがマップされているかデフォルトがある
• 空セルの扱いが作成と更新で明確に示されている
• 問題のある行だけにフィルタでき、素早く確認できる
• 作成 vs 更新 vs スキップの件数（およびエラー件数）を示すサマリがある

AppMasterで構築する場合、これらを「最後の安全画面」として扱ってください。ここで悪いインポートを止めるほうが、後で何千件ものレコードをクリーンアップするより安上がりです。

例：スプレッドシートから顧客をインポートする場合

サポートリードがスプレッドシートから顧客リストをエクスポートし、シンプルなCRMに読み込みたいとします。CSVの列は Name、Email、Phone、Status、Signup Date です。

カラムマッピングUIで彼らは次のようにマップします：

• Name -> Customer name
• Email -> Email（必須）
• Phone -> Phone（任意）
• Status -> Status（ドロップダウン）
• Signup Date -> Signup date（日付）

すぐにいくつかの問題が見つかります。Emailがない行がいくつかある。Statusの値が不一致（Active, ACTIVE, actv）。Signup Dateは混在：ある行は 2025-01-03、別の行は 01/03/2025、さらに別の行は 3 Jan 2025 のように。

マッピング段階でユーザーにファイル全体を直させる代わりに、安全なデフォルトとルールを設定させましょう。Statusに対しては列が空のときのみ "Active" をデフォルトにし、Signup Dateでは期待するフォーマット（例：YYYY-MM-DD）を選び、その他の形式はエラーにする、という設定ができます。

プレビューは判断の場になります。こう表示されるかもしれません：

• 12行がブロック：Emailが欠落
• 7行がフラグ付け：未知のStatus値 "actv"
• 5行がフラグ付け：無効な日付形式

プレビューからユーザーは素早く問題を修正できます。"actv" を一括で "Active" にマップし、5つの悪い日付をその場で直します。Emailがない行については、それらをスキップするか、インポートを停止してチームに入力させるか選べます。

AppMasterのようなツールは、マッピング画面と明確な検証、書き込まれる内容を反映するプレビューを組み合わせることで、この体験を自然にします。ユーザーは何も保存される前にインポートを信頼できます。

次のステップ：インポートUIを出して安全性を保つ

最初のリリースは制御された実験として扱ってください。小さなテストファイル（10〜50行）でフルフローをエンドツーエンドで実行します：マッピング、デフォルト、プレビュー、最終書き込み。結果が正しければ、ユーザーが次のインポートで再利用できるようにマッピングを保存できるようにします。保存されたマッピングは一度限りの「創造的な」マッチを減らし、安全のネットにもなります。

CSVインポートのカラムマッピングUIは、データを管理する場所、つまり管理パネルやデータを持つ内部ツールに配置してください。たとえばサポートリードが顧客を追加するために別のシステムや特別な権限を必要とするべきではありません。一覧画面に近い場所に置けば、彼らは結果をすぐに確認できます。

インポートが終わったら短い平易なレポートを表示し、それを後で参照できるようにしておきます。ユーザーが何が起きたかを推測する必要があってはいけません。

記録すべきことと表示すべきこと

デバッグに十分な詳細をキャプチャしつつ、ユーザーを圧倒しないようにします。良いポストインポートサマリには次が含まれます：

• 処理された行数、作成、更新、スキップされた件数
• エラー件数とダウンロード可能またはコピー可能なエラーレポート（行番号、列、メッセージ）
• 使用された保存済みマッピングとデフォルトのメモ
• 実行時間（開始時刻、終了時刻）と実行者
• 変更されたレコードに戻るための簡単なリンク（アプリがサポートしていれば）

AppMasterで構築するなら、Data Designerでデータをモデル化し、ビジュアルUIビルダーでマッピングとプレビュー画面を作り、Business Processで検証を強制してからPostgreSQLに書き込みます。プレビューを安全にし、インポートを厳格にするための分離が容易になります。

最後に、ローンチ前のもう一つのガードレール：各環境でテストインポート（まずはステージング、その後プロダクション）を必須にし、インポート機能を役割や権限の後ろに置いてください。これにより機能は便利なまま、リスクを抑えられます。