基本・データ設計読了目安 12分公開 2026-10-31 ／ 更新 2026-10-31

【図解】データローダー（Data Loader）の使い方：インストール、Upsert、やってはいけない操作

このページには広告リンクを含みます。

データローダーとデータインポートウィザードの違い

データインポートウィザードは Salesforce の画面で使うブラウザの機能で、データローダーは PC に入れるアプリです。判断の基準は件数と操作の種類です。

削除や出力が必要か、5万件以上か、未対応のオブジェクトか、定期実行かを順に分岐し、データインポートウィザードとデータローダーのどちらかへ進む判断図
1つでも当てはまればデータローダーへ進む
比較 データインポートウィザード データローダー
形 ブラウザ（設定画面など） PC のアプリ（macOS、Windows）
件数の上限 一度に50,000件まで Bulk API 2.0 で1億5,000万件まで
操作 新規、更新、新規と更新 Insert、Update、Upsert、Delete、Hard Delete、Export
対象 取引先、取引先責任者、リード、ソリューション、キャンペーンメンバー、カスタムオブジェクトなど すべてのオブジェクト
重複の防止 取引先名とサイト、メールアドレスで照合 外部 ID などのキーを自分で設計する
定期実行 できない コマンドライン（Windows のみ）
エディション Database.com を除く全エディション（ヘルプの比較表は Personal も除く） Enterprise、Performance、Unlimited、Developer

Professional Edition はデータローダーの対象に書かれていません。公式の数字は資料によって違います。ヘルプの比較表は「5,000〜500万件」、Data Loader Guide は「1億5,000万件まで」です。ダウンロードページは、Bulk API で500万件、Bulk API 2.0 で1億5,000万件と分けて書いています。ヘルプの比較表は500万件の理由を書いていませんが、大きな件数を扱うときは、設定で Bulk API 2.0 を選んでいるかを確かめます。

冒頭の3,000件の更新は、件数ならどちらでも扱えます。ただ更新の照合にレコード ID を使い、結果の成功と失敗を行ごとに確かめたいなら、データローダーが向いています。

データローダーのインストール手順

2026年10月時点の公式の手順は次のとおりです。

  1. Java を入れる：JRE 17 以降を OS と CPU に合わせて入れます。公式は Azul Zulu や Eclipse Temurin を例に挙げています。Windows 版にも Java は含まれません。
  2. JAVA_HOME を設定する：JRE を入れたフォルダを指定します。
  3. ダウンロードする：公式のページから zip を取得します。古い版はサポートされません。
  4. 展開して実行する：Windows は install.bat、macOS は installer.command を実行します。macOS で止められたら、プライバシーとセキュリティの設定から開きます。

版の番号には注意が要ります。ダウンロードページの表示は v64.1.0（Summer ’25）ですが、公式の GitHub リポジトリには v67.0.0（2026年6月公開、Summer ’26 向け）があります（確認日 2026-10-31）。どちらも JRE 17 以降が必要です。入れる前に両方を見比べます。

使うユーザーには「API の有効化」の権限と、操作に応じたオブジェクト権限が必要です。

ログインは、外部クライアントアプリケーションと PKCE を使う OAuth 2.0 の Web サーバーフローの設定が公式の手順にあります（v64.0.2 以降）。v64.1.0 ではデバイスフローとユーザーエージェントフローの対応が外れました。パスワード認証は影響を受けないとリリースノートに書かれています。Sandbox に接続するときは、設定で Sandbox の URL を指定します。接続先の間違いは事故に直結するので、実行前に毎回確かめます。

Insert、Update、Upsert、Delete の違い

操作ごとに、照合のキーと失敗したときの被害が違います。

操作 何をするか 照合のキー 必要な権限 戻し方
Insert 新規作成 なし 作成 成功ファイルの ID で削除する
Update 既存を更新 レコード ID 編集 控えの CSV で再度 Update する
Upsert あれば更新、なければ作成 レコード ID か外部 ID 作成または編集 新規分の削除と更新分の書き戻しが要る
Delete ごみ箱へ移す レコード ID 削除 15日以内ならごみ箱から復元する
Hard Delete ごみ箱を通さず削除 レコード ID 削除、Bulk API Hard Delete 戻せない

実行後は success と error の2つの CSV が出ます。success には作成された ID が、error には失敗の理由が入ります。件数の確認だけで終えず、error を必ず開きます。

Insert、Update、Upsert、Delete、Hard Deleteを左から右へ並べ、右へ行くほど戻しにくくなることを示した図
右へ行くほど間違えたときに戻しにくい

外部 ID を使う Upsert

Upsert が向くのは、基幹システムなど Salesforce の外に主キーがあるデータを定期的に取り込む場面です。Salesforce のレコード ID を知らなくても、外部の番号で照合できます。

動きは3通りです。

  • 一致なし：新規作成
  • 1件に一致：更新
  • 複数に一致：エラーになり、そのレコードは変わらない

同じバッチの中に同じ外部 ID が2行あると、SOAP API の説明では、それらの行はエラーになります。Salesforce のレコード ID が重複している場合は、同じバッチならエラー、別のバッチに分かれると想定と違う値が残ることがあります。実行前に CSV の重複を調べます。

設計の注意点は3つです。

  • 外部 ID に「ユニーク」も付ける：外部 ID だけでは、同じ値のレコードを作れてしまいます。
  • 大文字と小文字の扱いを決める：キーの値が大文字と小文字だけ違うと、設定によって同じ値として照合されます。
  • 親の指定にも外部 ID を使える：取引先責任者を取り込むとき、取引先の外部 ID で親を指定できます。

キーの打ち間違いにも注意します。Update なら失敗で済みますが、Upsert では必須項目がそろっていれば別のレコードが新しく作られます。エラーにならないので、気付きにくい失敗です。

やってはいけない操作と失敗の防ぎ方

ここが一番大切です。公式の手順に、編集部のおすすめを加えて整理します。

元データを全項目で出力、控えを保存、Sandboxで試す、本番で少量、本番で全件、errorファイルの確認の順に進み、問題があれば控えのCSVで戻す流れ図
本番の全件更新は最後の工程にする

Hard Delete を気軽に使わない

Hard Delete は、Bulk API か Bulk API 2.0 を使う設定にしたときだけ使えます。ごみ箱に入らないので、ごみ箱からは戻せません。ストレージの削減などで必要なら、次を守ります。

  1. 対象を全項目で出力し、控えを別に保存する
  2. 同じ手順を Sandbox で通す
  3. 別の人に対象の件数と条件を確かめてもらう

迷うなら通常の Delete を使います。ごみ箱に15日間残るので、その間に間違いに気付けます。データローダーの画面に復元の操作はありません。大量の復元は、Export All で削除済みの ID を出し、Workbench などから Undelete する方法が公式の記事にあります。

Delete はオブジェクトではなく ID で決まる

公式の注意書きのとおり、削除の対象は選んだオブジェクトではなく CSV の ID で決まります。「取引先責任者を選んだから大丈夫」とはなりません。ID 列だけの CSV を作り、マッピングも ID だけにします。大量削除には「すべてのデータの編集」権限が必要です。

一括更新の前に必ずバックアップを取る

公式の Mass Updates の手順は、次の流れです。

  1. 更新対象を Export するか、レコード ID 入りのレポートで出す
  2. その CSV の控えを別に保存する
  3. 作業用のファイルを編集する
  4. Update を実行し、success と error を確かめる
  5. 間違えたら、控えの CSV で元の値へ Update する

Export の保存先に既存のファイルを選ぶと内容が置き換わるので、控えの名前には日時を入れます（編集部のおすすめ）。公式の手順にはない編集部の注意として、Excel で CSV を開くと先頭の 0 が落ちる番号があります。番号の項目は取り込む前に見直します。

Sandbox で試す

Bulk API の公式の指針は、データロードを必ず Sandbox で先に試すことです。処理時間は本番で変わることがあります。Sandbox の次は、本番で10件ほどの少量を流し、画面で結果を見てから全件へ進みます。少量の件数は編集部のおすすめです。

空欄と長すぎる値の扱い

設定 既定の API（SOAP） Bulk API と Bulk API 2.0
CSV の空欄 「Insert null values」を選ぶと項目を空にする 空欄は無視される。空にするなら #N/A と書く
長すぎる値 「Allow field truncation」が既定で有効で切り詰められる その行が失敗する

「空欄にしたのに値が消えない」「知らないうちに途中で切れた」という事故は、この差から起きます。

トリガや入力規則への影響

データローダーも API でレコードを保存するので、実行順序の処理が動きます。公式の説明でも、トリガはデータの取り込みや Bulk API の呼び出しで動き、入力規則は API の呼び出しにも効きます。データローダーの設定でトリガ、フロー、入力規則を止めることはできません。

  • 入力規則：古いデータが今の規則に合わないと、その行は error に出ます。
  • トリガとフロー：Bulk API では200件ずつのまとまりで処理され、ガバナ制限の問題が本番で初めて出ることがあります。公式は、複雑なトリガを持つオブジェクトへの大きな投入を勧めていません。
  • 割り当てルール：ケースとリードで設定に指定すると、CSV の所有者より優先されます。
  • ロックの競合：Bulk API は既定で並列に処理します。非公開の共有設定での所有者変更などは競合が起きやすく、公式はシリアルモードを案内しています。データローダーのシリアルモードは「Use Bulk API」を選んだときの設定です。

メールの送信や外部連携を行う自動化があるなら、事前に一覧にして関係者に伝えます。データインポートウィザードには、ワークフロールールとプロセスを動かすかどうかを選ぶ項目があります。

文字化けの直し方（UTF-8）

原因は、CSV の文字コードと設定の組み合わせです。公式の記事は、Excel で保存した CSV はその PC の ANSI の文字コードになり、UTF-8 にならないと説明しています。

症状 原因 対処
取り込んだ日本語が崩れる 「Read all CSVs with UTF-8 encoding」が有効で、CSV が UTF-8 ではない CSV を UTF-8 に変換する。または設定を外す
Invalid CSV file format のエラー UTF-8 に BOM が付いている テキストエディタで BOM なしの UTF-8 にして保存する
出力した CSV が崩れる 書き出し側の文字コードの設定 「Write all CSVs with UTF-8 encoding」を確かめる。公式は有効のままにするよう勧めている

公式の記事は、Data Loader 28以降は BOM 付きの UTF-8 に対応していないと書いています。対処はテキストエディタで BOM なしに保存し直すことです。

ここからは公式の記事にない、編集部の注意です。Excel の「CSV UTF-8」形式で保存すると BOM が付くことがあります。変換した後に Excel で上書き保存すると、文字コードが変わることがあります。変換の後は Excel で保存しないのが安全です。

関連記事

よくある質問

データローダーとデータインポートウィザードはどう使い分けますか？
5万件未満で、対応オブジェクトへの単純な取り込みならデータインポートウィザードを使います。5万件以上、削除やエクスポートが必要、未対応のオブジェクト、定期的な処理ならデータローダーを使います。
データローダーのインストールに Java は必要ですか？
必要です。データローダーのインストール前に Java Runtime Environment（JRE）17以降を入れ、JAVA_HOME を設定します。Windows 用のインストーラにも Java は含まれていません。
Upsert とは何ですか？
Upsert は、キーが一致すれば更新し、一致しなければ新規作成する操作です。キーには Salesforce のレコード ID か、外部 ID の項目を使います。キーが複数のレコードに一致するとエラーになります。
データローダーの Hard Delete は元に戻せますか？
戻せません。Hard Delete したレコードはごみ箱に入らず、すぐに削除の対象になります。通常の Delete ならごみ箱に15日間残り、その間は復元できます。
データローダーで日本語が文字化けするのはなぜですか？
CSV の文字コードとデータローダーの設定が合っていないためです。UTF-8 で読む設定のまま Excel で保存した CSV を読むと崩れます。CSV を UTF-8 に変換するか、設定を外して読み込みます。