【保存版】elasticsearch-dumpで実現する、Elasticsearch の超柔軟なデータ移行・バックアップ手法

Tech Blog banner featuring a city skyline and circuit graphics with 'Tech Blog' and Japanese text about Elasticsearch in bold white letters. BLOG

Elasticsearchのデータ移行やバックアップを、スナップショット機能を使わずに「もっと手軽に、インデックス単位でサクッと行いたい」と思ったことはありませんか？

そんなエンジニアの強い味方になるのが、オープンソースのCLIツール elasticsearch-dump （通称：elasticdump）です。

今回は、このツールの基本的な使い方から、実務で役立つ一歩進んだテクニックまでを解説します。

Elasticsearch を運用していると、以下のようなシーンに直面することがよくあります。

  • 開発環境（Develop）の特定のインデックスだけを、ステージング環境（Staging）にサクッとコピーしたい
  • インデックスの「マッピング」や「アナライザー」の設定だけを抽出して使い回したい
  • ローカルファイル（JSON/CSV）にデータを退避させたい

これらをGUIや面倒なAPIリクエストなしに、使い慣れたCLIコマンド一発で解決してくれるのが、今回紹介する elasticsearch-dump です。

1. elasticsearch-dumpとは？

elasticsearch-dump は、Elasticsearchのインデックスデータをインポート/エクスポートするためのNode.js製ツールです。[^1]1

最大の特徴は、「--input（入力元）から、--output（出力先）へデータをストリーミングして送る」という極めてシンプルな設計にあります。

入力元と出力先には、ESのURLだけでなく、ローカルのJSON/CSVファイルや、標準入出力（stdin/stdout）、さらにはAWS S3なども直接指定できます。

2. クイックスタート：インストール方法

今回検証した環境は以下の通りです。

  • OS: Windows 11 (PowerShell)
  • Node.js: v24.18.0
  • jq: 1.8.2

2.1. Node.js環境の用意

Node.js 公式サイト よりインストーラーをダウンロードし、インストールします。

※ホスト環境にNode.jsをインストールしたくない場合は、公式のDockerイメージを利用する方法もありますが、ここでは説明を割愛します。

2.2. npmによるインストール

npmを使ってグローバル（またはローカル）にインストールします。

# グローバルインストール
npm install elasticdump -g

💡 Windowsでのインストール先について Windows環境でグローバルインストール（-g）した場合、一般的には下記のパス配下に配置されます。[^2]2

C:\Users\<ユーザー名>\AppData\Roaming\npm

3. 基本的な使い方とユースケース

elasticdump は主に「Analyzer（アナライザー）」「Mapping（マッピング）」「Data（ドキュメントデータ）」の3つのフェーズ（--type）に分けて処理を行います。

（ここでは Analyzer フェーズは省略します。また、–type には settings や policy, alias, template なども指定可能です。詳細は、公式ページを参照してください。）

3.1. ユースケース①：開発環境からデータをダンプ

データを JSON 形式でダンプします。通常は「mapping ➔ data」の順にダンプします。

3.1.1. マッピング（構造定義）をダンプ

# PowerShellでの実行例（改行は「`」を使用）
elasticdump `
  --input=http://elasticuser:elasticpassword@develop.es.com:9200/my_index `
  --output=my_index_mapping.json `
  --type=mapping

⚠️ HTTPS環境（自己署名証明書など）でTLSエラーが出る場合 ElasticsearchがHTTPSでリクエストを受け付けており、証明書エラーが発生する場合は、一時的にTLS検証を無視する環境変数を設定してからコマンドを実行してください。[^3]3

# PowerShellでの実行例
$env:NODE_TLS_REJECT_UNAUTHORIZED="0"
elasticdump `
  --input=https://elasticuser:elasticpassword@develop.es.com:9200/my_index `
  --output=my_index_mapping.json `
  --type=mapping

3.1.2. ドキュメントデータ（実データ）をダンプ

elasticdump `
  --input=http://elasticuser:elasticpassword@develop.es.com:9200/my_index `
  --output=my_index_data.json `
  --type=data

💡 Note: 出力ファイルフォーマットは「行区切りのJSON（Line-delimited JSON / NDJSON）」です。ファイル全体が1つの巨大なJSON配列ではないため、ストリーム処理に適しており、メモリ消費を最小限に抑えられます。

3.2. ユースケース②：特定のデータだけを絞り込んでダンプする（searchBody）

「管理者のログだけを抽出したい」「特定の期間のデータだけをバックアップしたい」という場合は、--searchBody オプションにElasticsearchのクエリ（DSL）を指定できます。

elasticdump `
  --input=http://elasticuser:elasticpassword@develop.es.com:9200/my_index `
  --output=my_index_filtered_data.json `
  --type=data `
  --searchBody='{\"query\":{\"term\":{\"username\":\"admin\"}}}'

※クエリが複雑な場合は、別ファイル（例：search_body.json）に切り出して、@ 接頭辞を用いて読み込ませることも可能です。

./search_condition/search_body.json

{
  "query": {
    "term": {
      "username": "admin"
    }
  }
}

elasticdump `
  --input=http://elasticuser:elasticpassword@develop.es.com:9200/my_index `
  --output=my_index_filtered_data.json `
  --type=data `
  --searchBody=@./search_condition/search_body.json

4. 知っておくと便利な一歩進んだ応用テクニック

4.1. データの移行中にオンザフライで変換をかける（–transform）

移行のタイミングで「特定の個人情報フィールドをマスクする」「新しいフィールドを追加する」といった簡易的なETL（Extract/Transform/Load）処理が可能です。

JavaScriptでドキュメントの操作関数を定義しておき、それを呼び出します。

./transforms/anonymize.js

module.exports = function (doc, options) {
  if (doc._source.email) {
    // メールアドレスのドメイン部分だけ残してマスクする例
    doc._source.email = "anonymized@" + doc._source.email.split('@')[1];
  }
};

# トランスフォーム用スクリプトを指定して実行
elasticdump `
  --input=http://elasticuser:elasticpassword@develop.es.com:9200/my_index `
  --output=my_index_transformed_data.json `
  --type=data `
  --transform=@./transforms/anonymize.js

5. ダンプしたデータのリストア

リストア先の環境で elasticdump や curl を利用できる場合は、それらを利用してリストアするのが簡単ですが、それらを利用できない場合には、ダンプした JSON ファイルを加工して、Dev Tools の Console からデータを投入します。

既存データを壊さないように、必ず mapping ➔ data の順でリストアします。

5.1. マッピングの作成

5.1.1. ローカルで my_index_mapping.json を開く

エクスポートされたマッピングファイルは、一般的に以下のように「インデックス名」をルートキーに持つ構造になっています。

{
  "my_index": {
    "mappings": {
      "properties": {
        "title": { "type": "text" },
        "price": { "type": "float" }
      }
    }
  }
}

5.1.2. インデックス名（ “my_index” ）の階層を除外してコピーする

Kibana Console でインデックスを新規作成する際、宛先インデックス名は URL パス（PUT /<インデックス名>）で指定するため、JSON 内の "my_index": { ... } という外枠（ラッパー）は不要です。

内側の { "mappings": { ... } } のブロックだけをコピーします。

5.1.3. Kibana Dev Tools (Console) で実行する

Kibana の Dev Tools Console を開き、以下のようにリクエストを記述して実行（再生マークのボタンをクリック）します。

PUT /my_index
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "price": { "type": "float" }
    }
  }
}

5.2. データの登録

5.2.1. _bulk 用の ndjson への変換

jq コマンドをjqのダウンロードサイトからダウンロードします。

jq コマンドをダウンロード後、my_index_data.json を _bulk 用の ndjson に加工します。

PowerShell と jq の文字コードの相性が悪いので、コマンドプロンプトを経由して jq を実行します。

（jqの実行ファイル名が jq-windows-amd64 の場合）

cmd /c 'jqのインストールディレクトリ\jq-windows-amd64 -c "{\"index\":{\"_index\":\"my_index\",\"_id\":._id}}, ._source" my_index_data.json > bulk_formatted.ndjson'

5.2.2. Kibana Dev Tools (Console) で実行する

Kibana Dev Toolsで以下のように POST _bulk を記述し、その後に続けて bulk_formatted.ndjson の内容を貼り付けて実行します。

POST _bulk
{ "index" : { "_index" : "my_index", "_id" : "1" } }
{ "title" : "...", "price" : ... }
...

6. まとめ：どんな時に使うべきか？

Elasticsearch公式のスナップショット機能（Snapshot/Restore）は非常に強力ですが、S3などの共有リポジトリの登録が必要だったり、クラスタ全体の移行になりがちで、少々「重厚」です。

それに対して、 elasticsearch-dump は以下のようなシチュエーションで抜群の機動力を発揮します。

  • 開発環境と検証環境間で、数万〜数百万件程度の特定データをパパッと持ち運びたい
  • スキーマ定義（マッピング）だけを手元でバージョン管理したい
  • スナップショットの設定権限がない（AWS OpenSearch Serverless など制限のある環境を含む）

手元の開発環境に一つ入れておくだけで、データ運用の生産性が劇的に向上するおすすめのツールです。ぜひ皆さんのプロダクト運用や開発プロセスにも組み込んでみてください！

7. 参考リンク

  1. 実行には事前に Node.js（npm）の実行環境が必要になります。
    ↩︎
  2. Windowsのユーザー環境によって、”AppData” フォルダは隠しフォルダになっている場合があるため、エクスプローラーの「表示」設定で「隠しファイル」にチェックを入れてアクセスしてください。
    ↩︎
  3. この設定はSSL/TLSの証明書検証を無効化するため、本番環境の公開ネットワーク等で実行する際はセキュリティリスクを考慮し、一時的な利用に留めてください。
    ↩︎