/ /

$merge（集計ステージ）

定義

注意

このページでは、集計パイプラインの結果をコレクションに出力する$merge ステージについて説明します。複数のドキュメントを 1 つのドキュメントに結合する$mergeObjects演算子については、$mergeObjectsを参照してください。

$merge

集計パイプラインの結果を、指定したコレクションに書き込みます。$merge 演算子はパイプラインの最後ののステージでなければなりません。

$merge ステージでは、次のことができます。

同じデータベースまたは異なるデータベース内のコレクションに出力できます。
集約されている同じコレクションに出力できます。詳細については、「集計されているのと同じコレクションへの出力」を参照してください。
$merge集計パイプラインで $out またはステージを使用する場合は、次の点を考慮してください。
- MongoDB 5.0 以降では、クラスター内のすべてのノードの featureCompatibilityVersion が 5.0 以上に設定されており、読み込み設定（read preference）でセカンダリ読み取りが許可されている場合、$merge ステージのパイプラインをレプリカセットのセカンダリノードで実行できます。
  - $merge $out ステージはセカンダリノードで実行されますが、書込み (write) 操作はプライマリノードに送信されます。
  - すべてのドライバーバージョンがセカンダリノードに送信される $merge 操作をサポートしているわけではありません。詳細については、ドライバーのドキュメントを参照してください。
- MongoDB の以前のバージョンでは、$out または $merge ステージを持つパイプラインは常にプライマリノードで実行され、読み込み設定 (read preference) は考慮されませんでした。
出力コレクションがまだ存在しない場合は、新しいコレクションを作成します。
結果（新しいドキュメントの挿入、ドキュメントのマージ、ドキュメントの置換、既存のドキュメントの保持、操作の失敗、カスタムアップデートパイプラインによるドキュメントの処理）を既存のコレクションに組み込むことができます。
シャーディングされたコレクションに出力できます。入力コレクションもシャーディング可能です。

集計結果をコレクションに出力する$out ステージとの比較については、「$merge と$out の比較」を参照してください。

注意

オンデマンドのマテリアライズドビュー

$merge は、コレクションの完全な置換を行うのではなく、パイプラインの結果を既存の出力コレクションに組み込むことができます。この機能により、ユーザーはオンデマンドのマテリアライズドビューを作成できます。ここでは、パイプラインの実行時に出力コレクションの内容が段階的に更新されます。

このユースケースの詳細については、このページの例だけでなく、オンデマンドマテリアライズドビューも参照してください。

マテリアライズドビューは読み取り専用のビューとは別物です。読み取り専用ビューの作成については、「読み取り専用ビュー」を参照してください。

互換性

次の環境でホストされる配置には $merge を使用できます。

MongoDB Atlas はクラウドでの MongoDB 配置のための完全管理サービスです

MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

構文

$merge の構文は次のとおりです。

{ $merge: {
     into: <collection> -or- { db: <db>, coll: <collection> },
     on: <identifier field> -or- [ <identifier field1>, ...],  // Optional
     let: <variables>,                                         // Optional
     whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
     whenNotMatched: <insert|discard|fail>                     // Optional
} }

以下に例を挙げます。

{ $merge: { into: "myOutput", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }

同じデータベース内のコレクションへの書き込みを含め、$merge のすべてのデフォルトオプションを使用する場合は、簡略化された形式を使用できます。

{ $merge: <collection> } // Output collection is in the same database

$mergeステージは、次のフィールドを持つドキュメントを取得します。

フィールド

説明

into

出力コレクション。次のいずれかを指定します。

集計が実行されるのと同じデータベース内のコレクションに出力する文字列としてのコレクション名。以下に例を示します。

into: "myOutput"
指定されたデータベース内のコレクションに出力するドキュメント内のデータベース名とコレクション名。以下に例を示します。

into: { db:"myDB", coll:"myOutput" }

出力コレクションが存在しない場合、$merge はコレクションを作成します。

レプリカセットまたはスタンドアロンでは、出力データベースが存在しない場合、$merge によってデータベースも作成されます。
シャーディングされたクラスターの場合、指定された出力データベースがすでに存在している必要があります。

出力コレクションはシャーディングされたコレクションにすることができます。

任意。ドキュメントのユニークな識別子として機能するフィールド。識別子は、結果ドキュメントが出力コレクション内の既存のドキュメントと一致するかどうかを判断します。次のいずれかを指定します。

文字列としての 1 つのフィールド名。以下に例を示します。

on: "_id"
配列内のフィールドの組み合わせ。以下に例を示します。

on: [ "date", "customerId" ]

配列内のフィールドの順序は重要ではなく、同じフィールドを複数回指定することはできません。

指定されたフィールドの場合、次のようになります。

集計結果ドキュメントには、on フィールドが _id フィールドである場合を除き、on で指定されたフィールドが含まれている必要があります。結果ドキュメントに _id フィールドがない場合、MongoDB はそれを自動的に追加します。
MongoDB8.0 以前を実行中配置では、on の指定されたフィールドが欠落しているか、null 値が含まれていることはできません。 MongoDB8.1 以降では、サポートインデックスがスパースでない場合、on の指定されたフィールドが欠落しているか、null 値が含まれている可能性があります。
指定されたフィールドに配列値を含めることはできません。

$merge 一意インデックスには、on 識別子フィールドに対応するキーが必要です。インデックスキーを指定する順序は重要ではありませんが、ユニークインデックスにはキーとして on フィールドのみを含める必要があります。

また、インデックスが保持する照合は、集計が保持する照合と同じであることが必要です。
一意なインデックスはスパースインデックスにできます。
一意なインデックスを部分インデックスにすることはできません。
既に存在する出力コレクションの場合、対応するインデックスが既に存在している必要があります。

オンのデフォルト値は出力コレクションによって異なります。

出力コレクションが存在しない場合、オン識別子はである必要があり、デフォルトは_id フィールドになります。対応する一意の_id インデックスが自動的に作成されます。
- 存在しないコレクションに対して異なるオン識別子フィールドを使用するには、まず目的のフィールドにユニークインデックスを作成してコレクションを作成します。例えについては「存在しない出力コレクションのセクション」を参照してください。
- MongoDB 8.3 以降では、サーバーは自動作成された _idインデックスがクエリの照合と一致することを確認します。照合が一致しない場合、_idインデックスはクエリの一意性を提供できず、クエリは実行されません。
既存の出力コレクションがシャーディングされていない場合、on 識別子はデフォルトで _id フィールドになります。
既存の出力コレクションがシャーディングされたコレクションの場合、オン識別子はデフォルトですべてのシャードキーフィールドと_id フィールドになります。別のon 識別子を指定する場合、on にはすべてのシャードキーフィールドが含まれている必要があります。

whenMatched

$merge任意。結果ドキュメントとコレクション内の既存のドキュメントが指定されたオンフィールドの値が同じ場合のの動作。

次のいずれかを指定できます。

以下の事前定義されたアクション文字列の中から 1 つ。

アクション	説明
"replace"	出力コレクション内の既存のドキュメントを、一致する結果ドキュメントに置き換えます。置換を実行する場合、置換ドキュメントによって `_id` 値やシャードキー値（出力コレクションがシャーディングされている場合）は変更されません。それ以外の場合、操作はエラーを生成します。このエラーを回避するには、オンフィールドに`_id` フィールドが含まれていない場合は、集計結果の`_id` フィールドを削除してエラーを回避します（たとえば、先行する`$unset` ステージなど）。
"keepExisting"	既存のドキュメントを出力コレクションに保持します。
"merge" （デフォルト）	一致するドキュメントをマージします（`$mergeObjects` 演算子と同様）。結果ドキュメントに既存のドキュメントにないフィールドが含まれている場合は、それらの新しいフィールドを既存のドキュメントに追加します。結果ドキュメントに既存のドキュメントのフィールドが含まれている場合は、既存のフィールド値を結果ドキュメントのフィールド値に置き換えます。たとえば、出力コレクションに以下のドキュメントがあるとします。 `{ _id: 1, a: 1, b: 1 }` また、集計結果には以下のドキュメントがあるとします。 `{ _id: 1, b: 5, z: 1 }` その場合、マージされたドキュメントは以下のようになります。 `{ _id: 1, a: 1, b: 5, z: 1 }` マージを実行する場合、マージされたドキュメントによって `_id` 値やシャードキー値（出力コレクションがシャーディングされている場合）は変更されません。それ以外の場合、操作はエラーを生成します。このエラーを回避するには、オンフィールドに`_id` フィールドが含まれていない場合は、集計結果の`_id` フィールドを削除してエラーを回避します（たとえば、先行する`$unset` ステージなど）。
"fail"	集計操作を停止して失敗させます。前ドキュメントからの出力コレクションへの変更は、元には戻されません。

コレクション内のドキュメントを更新するための集計パイプライン。

[ <stage1>, <stage2> ... ]

パイプラインは、次のステージのみで構成できます。
- $addFields およびそのエイリアス $set
- $project およびそのエイリアス $unset
- $replaceRoot およびそのエイリアス $replaceWith
パイプラインはオンフィールドの値を変更できません。例、フィールドmonth で照合している場合、パイプラインはmonth フィールドを変更できません。

whenMatched pipeline は、$<field> を使用して出力コレクション内の既存のドキュメントのフィールドに直接アクセスできます。

集計結果ドキュメントのフィールドにアクセスするには、次のいずれかを使用します。
- フィールドにアクセスするための組み込み変数$$new。具体的には、 $$new.<field> 。$$new変数は、 let指定が省略されている場合にのみ使用できます。
- let フィールド内のユーザー定義変数。
  
  二重ドル記号（$$）プレフィックスと変数名を $$<variable_name> 形式で指定します。たとえば、$$year のような形式です。変数がドキュメントに設定されている場合は、$$<variable_name>.<field> という形式でフィールドを含めることもできます。たとえば、$$year.month のような形式です。
  
  その他の例については、「変数を使用してマージをカスタマイズする」を参照してください。

let

任意。whenMatched パイプラインで使用する変数を指定します。

以下のように、変数名と値の式を使ってドキュメントを指定します。

{ <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n> }

指定されていない場合、デフォルトは{ new: "$$ROOT" } になります（ROOT を参照）。 whenMatchedパイプラインは $$new変数にアクセスできます。

whenMatched パイプライン内の変数にアクセスするには、次のようにします。

二重ドル記号（$$）プレフィックスと変数名を $$<variable_name> 形式で指定します。たとえば、$$year のような形式です。変数がドキュメントに設定されている場合は、$$<variable_name>.<field> という形式でフィールドを含めることもできます。たとえば、$$year.month のような形式です。

例については、「変数を使用してマージをカスタマイズする」を参照してください。

whenNotMatched

任意。結果ドキュメントがアウトコレクション内の既存のドキュメントと一致しない場合の $merge の動作。

以下の事前定義されたアクション文字列のいずれかを指定できます。

アクション	説明
"insert" (Default)	ドキュメントを出力コレクションに挿入します。
"discard"	ドキュメントを破棄します。具体的には、`$merge` はドキュメントを出力コレクションに挿入しません。
"fail"	集計操作を停止して失敗させます。すでに出力コレクションに書き込まれた変更は、元には戻されません。

Considerations

`_id` フィールド生成

集計パイプライン結果のドキュメントに _id フィールドが存在しない場合は、$merge ステージによって自動的にフィールドが生成されます。

たとえば、次の集計パイプラインでは、$project は$merge に渡されるドキュメントから_id フィールドを除外します。$merge がこれらのドキュメントを "newCollection" に書き込むと、$merge は新しい_id フィールドと値を生成します。

db.movies.aggregate( [
   { $project: { _id: 0 } },
   { $merge : { into : "newCollection" } }
] )

出力コレクションが存在しない場合の新しいコレクションの作成

指定された出力コレクションが存在しない場合は、$merge操作によって新しいコレクションが作成されます。

出力コレクションは、$merge が最初のドキュメントをコレクションに書込んだときに作成され、すぐに表示されます。
集計が失敗した場合、エラーの前に $merge によって完了した書き込みはロールバックされません。

注意

レプリカセットまたはスタンドアロンでは、出力データベースが存在しない場合、$merge によってデータベースも作成されます。

シャーディングされたクラスターの場合、指定された出力データベースがすでに存在している必要があります。

出力コレクションが存在しない場合、$merge ではオン識別子が_id フィールドである必要があります。存在しないコレクションに対して別のon フィールド値を使用するには、まずフィールドにユニークインデックスを作成してコレクションを作成します。例、出力コレクションnewDailyCommentCount commentDateが存在せず、オン識別子としてフィールドを指定する場合は次のようになります。

db.newDailyCommentCount.createIndex(
   { commentDate: 1 }, { unique: true } )
db.comments.aggregate( [
   { $match: { date: { $gte: new Date("2002-01-01"),
     $lt: new Date("2002-02-01") } } },
   { $group: { _id: { $dateToString: { format: "%Y-%m-%d",
     date: "$date" } }, count: { $sum: 1 } } },
   { $project: { _id: 0, commentDate: { $toDate: "$_id" },
     count: 1 } },
   { $merge : { into : "newDailyCommentCount",
     on: "commentDate" } }
] )

シャーディングされたコレクションへの出力

$merge ステージはシャーディングされたコレクションに出力できます。出力コレクションがシャーディングされた場合、$merge は_id フィールドとすべてのシャードキーフィールドをデフォルトのオン識別子として使用します。デフォルトを上書きする場合、オン識別子にすべてのシャードキーフィールドを含める必要があります。

{ $merge: {
   into: "<shardedColl>" or { db:"<sharding enabled db>", coll: "<shardedColl>" },
   on: [ "<shardkeyfield1>", "<shardkeyfield2>",... ], // Shard key fields and any additional fields
   let: <variables>,                                         // Optional
   whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
   whenNotMatched: <insert|discard|fail>                     // Optional
} }

たとえば、sh.shardCollection() メソッドを使用して、rated フィールドをシャードキーとして持つ新しいシャーディングされたコレクションmoviesByYearAndRating を作成します。

sh.shardCollection(
   "sample_mflix.moviesByYearAndRating",  // Namespace of the collection to shard
   { rated: 1 },                       // Shard key
);

moviesByYearAndRatingコレクションには、年別の映画統計（year フィールド）とコンテンツ評価（シャードキー）を持つドキュメントが含まれます。具体的には、 ["year", "rated"]$mergeオン識別子はです（フィールドの順序は重要ではありません）。には、オン識別子フィールドに対応するキーを持つユニークインデックスが必要なので、ユニークインデックスを作成します（フィールドの順序は関係ありません）。 []1

db.moviesByYearAndRating.createIndex(
   { rated: 1, year: 1 }, { unique: true } )

シャーディングされたコレクション moviesByYearAndRating と一意のインデックスを作成すると、$merge を使用して集計結果をこのコレクションに出力でき、この例のように [ "year", "rated" ] に一致します。

db.movies.aggregate( [
   { $match: { rated: { $ne: null }, year: { $ne: null } } },
   { $group: {
      _id: { year: "$year", rated: "$rated" },
      movieCount: { $sum: 1 } } },
   { $project: { _id: 0, year: "$_id.year", rated: "$_id.rated",
     movieCount: 1 } },
   { $merge: { into: "moviesByYearAndRating",
     "on": [ "year", "rated" ], whenMatched: "replace",
     whenNotMatched: "insert" } }
] )

[1]	`sh.shardCollection()` メソッドは、シャードキーが範囲ベースであり、コレクションが空であり、シャードキーにユニークインデックスがまだ存在しない場合に、`{ unique: true }` オプションを渡すとシャードキーにユニークインデックスを作成することもできます。前の例では、`on` 識別子がシャードキーであり、さらに別のフィールドでもあるため、対応するインデックスを作成する別の操作が必要です。

ドキュメントの置換（`$merge`）とコレクションの置換（`$out`）

$merge は、集計結果にオン仕様に基づいて一致するドキュメントが含まれている場合、出力コレクション内の既存のドキュメントを置き換えることができます。したがって、集計結果にコレクション内のすべての既存のドキュメントと一致するドキュメントが含まれ、"replace" が指定されている場合、$merge は既存のコレクション内のすべてのドキュメントを置き換えることができます。 whenMatched の。

ただし、集計結果に関係なく既存のコレクションを置き換えるには、代わりに $out を使用します。

既存のドキュメント、`_id`、およびシャードキー値

$mergeによって既存のドキュメントの _id 値が変更されると、$merge エラーが発生します。

Tip

このエラーを回避するには、オンフィールドに_id フィールドが含まれていない場合は、集計結果の_id フィールドを削除してエラーを回避します（たとえば、先行する$unset ステージなど）。

さらに、シャーディングされたコレクションの場合、既存のドキュメントのシャードキー値が変更されると、$merge はエラーも生成します。

エラーが発生する前に $merge によって完了した書き込みはロールバックされません。

ユニークインデックス制約

オンフィールドに$merge で使用されるユニークインデックスが集計の途中で削除された場合、集計が強制終了される保証はありません。集計が続行される場合、ドキュメントに重複するon フィールド値が存在しないという保証はありません。

$merge が出力コレクションの一意のインデックスに違反するドキュメントを書込もうとした場合、操作でエラーが生成されます。例:

オンフィールドのインデックス以外のユニークインデックスに違反する、一致しないドキュメントを挿入します。
コレクション内に一致するドキュメントがある場合は失敗します。具体的には、この操作は、オンフィールドの一意のインデックスに違反する一致するドキュメントを挿入しようとします。
既存のドキュメントを、オンフィールドのインデックス以外のユニークインデックスに違反する新しいドキュメントに置き換えます。
オンフィールドのインデックス以外の一意のインデックスに違反するドキュメントとなる一致するドキュメントをマージします。

スキーマ検証

コレクションでスキーマ検証が使用されており、 validationActionがerrorに設定されている場合、無効なドキュメントを挿入したり、 $mergeを使用して無効な値を持つドキュメントを更新したりすると、 MongoServerErrorがスローされ、ドキュメントはターゲットコレクションに書き込まれません。無効なドキュメントが複数ある場合、最初に見つかった無効なドキュメントのみがエラーをスローします。すべての有効なドキュメントはターゲットコレクションに書き込まれ、すべての無効なドキュメントは書込みに失敗します。

`whenMatched` パイプラインの動作

$merge 次のすべてが真である場合、ドキュメントを出力コレクションに直接挿入します。

whenMatched の値は集計パイプラインです。
whenNotMatched の値はinsert です。
出力コレクションに一致するドキュメントがありません。

`$merge` と `$out` の比較

$merge の導入により、MongoDB は集計パイプラインの結果をコレクションに書き込むための 2 つのステージ $merge と $out を提供します。

`$merge`	`$out`
同じデータベースまたは異なるデータベース内のコレクションに出力できます。	同じデータベースまたは異なるデータベース内のコレクションに出力できます。
出力コレクションがまだ存在しない場合は、新しいコレクションを作成します。	出力コレクションがまだ存在しない場合は、新しいコレクションを作成します。
結果（新しいドキュメントの挿入、ドキュメントのマージ、ドキュメントの置換、既存のドキュメントの保持、操作の失敗、カスタムアップデートパイプラインによるドキュメントの処理）を既存のコレクションに組み込むことができます。「ドキュメントの置換（`$merge` ）とコレクションの置換（`$out` ）」も参照してください。	出力コレクションが既に存在する場合は、完全に置き換えます。
シャーディングされたコレクションに出力できます。入力コレクションもシャーディング可能です。	シャーディングされたコレクションに出力できません。ただし、入力コレクションはシャーディングできます。
以下の SQL ステートメントに対応します。 `MERGE`. `INSERT INTO T2 SELECT FROM T1`. `SELECT INTO T2 FROM T1`. マテリアライズドビューの作成と更新。	以下の SQL ステートメントに対応します。 `INSERT INTO T2 SELECT FROM T1`. `SELECT INTO T2 FROM T1`.

集計されているのと同じコレクションへの出力

警告

$mergeの出力が集約されている同じコレクションに出力する場合、ドキュメントが複数回更新されたり、操作によって無限ループが発生したりする可能性があります。この動作は、$merge によって実行されるアップデートによって、ディスクに保存されているドキュメントの物理的な場所が変更された場合に発生します。ドキュメントの物理的な場所が変更されると、$merge はそのドキュメントを完全に新しいドキュメントとして表示し、追加のアップデートが行われる可能性があります。この動作の詳細については、「日付の問題」を参照してください。

$mergeは、集約されている同じコレクションに出力できます。また、などのパイプラインの他のステージに表示されるコレクションに出力することもできます。$lookup

制限事項

制限事項	説明
トランザクション	集約パイプラインでは、トランザクション内で `$merge` を使用できません。
時系列コレクション	集計パイプラインでは、`$merge` を使用して時系列コレクションに出力することはできません。
ビュー定義マテリアライズドビューとは別	ビュー定義に `$merge` ステージを含めることはできません。ビュー定義に入れ子パイプラインが含まれている場合（たとえば、ビュー定義に `$facet` ステージが含まれている場合）、この `$merge` ステージの制限は入れ子パイプラインにも適用されます。
`$lookup` ステージ	`$lookup` ステージのネストされたパイプラインに `$merge` ステージを含めることはできません。
`$facet` ステージ	`$facet` ステージのネストされたパイプラインに `$merge` ステージを含めることはできません。
`$unionWith` ステージ	`$unionWith` ステージのネストされたパイプラインに `$merge` ステージを含めることはできません。
`"linearizable"` 読み取り保証 (read concern)	`$merge`ステージは、読み取り保証 (read concern)`"linearizable"` と組み合わせて使用できません。つまり、`"linearizable"` に対して`db.collection.aggregate()` 読み取り保証`$merge` (read concern)を指定した場合、パイプラインにステージを含めることはできません。

例

言語

戻る

$match

$out