$merge (マージ)
最終更新：2026-10-09
$merge (マージ)
$merge は、パイプラインの結果をターゲットコレクション（別データベースや別クラスターでも可）に書き込み、一致キーで既存ドキュメントを更新したり新しいドキュメントを挿入したりします。$out のスーパーセットで、最終ステージでなければなりません。主要オプション: into、on（一致フィールド）、whenMatched、whenNotMatched。ETL、マテリアライズドビュー、コレクション間同期に適します。
| カテゴリ | 高度と診断 |
|---|---|
| MongoDB バージョン | 4.2+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $merge: { into: "<collection>", on: "<matchField>", whenMatched: "merge", whenNotMatched: "insert" } }⚙️ パラメータ
| into | 対象コレクション。文字列または { db, coll } オブジェクト。 |
|---|---|
| on | 既存ドキュメントのマッチに使用するフィールド。既定は _id。 |
| whenMatched | マッチ時の動作: merge、replace、keepExisting、またはカスタムパイプライン。 |
| whenNotMatched | マッチしない場合の動作: insert または discard。 |
戻り値：ドキュメントは後続に流れません。結果は対象コレクションに書き込まれます
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $merge: 顧客ごとの合計を cust_stats に書き込む
db.orders.aggregate([
{ $group: { _id: '$cust_id', total: { $sum: '$amount' } } },
{ $merge: {
into: 'cust_stats',
on: '_id',
whenMatched: 'replace',
whenNotMatched: 'insert'
} }
])出力：
// cust_stats が更新または挿入される📌 注意事項
- パイプラインの最終ステージでなければならない
- into に文字列を指定するとターゲットコレクションが自動作成される
- デフォルト: whenMatched は merge、whenNotMatched は insert
🏷️ 関連タグ
💡 関連ケース
📚 関連チュートリアル
❓ よくある質問
Q$merge と $out の違いは？
A$out はコレクション全体を置き換えます。$merge はキーで更新し、増分を追加し、別データベースへの書き込みにも対応します。
Q別のデータベースに書き込めますか？
Aはい。'db.coll' 形式の文字列か { db, coll } オブジェクトで指定します。
Q重複キーはどう扱われますか？
AwhenMatched で決まります: merge はフィールドをマージ、replace はドキュメントを入れ替え、keepExisting は元を保持します。
