$merge（集計ステージ）

into

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

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

  into: "myOutput"
  

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

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

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

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

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

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

on

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

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

  on: "_id"
  

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

  on: [ "date", "customerId" ]

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

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

• 集計結果ドキュメントには、on フィールドが _id フィールドである場合を除き、on で指定されたフィールドが含まれている必要があります。結果ドキュメントに _id フィールドがない場合、MongoDB はそれを自動的に追加します。

• MongoDB 8.0 以前を実行している配置では、on の指定されたフィールドが欠落しているか、null 値が含まれていることはできません。MongoDB 8.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":

  集計操作を停止して失敗させます。すでに出力コレクションに書き込まれた変更は、元には戻されません。

トランザクション

集約パイプラインでは、トランザクション内で $merge を使用できません。

時系列コレクション

集計パイプラインでは、$merge を使用して時系列コレクションに出力することはできません。

ビュー定義
マテリアライズドビューとは別

ビュー定義に $merge ステージを含めることはできません。ビュー定義に入れ子パイプラインが含まれている場合（たとえば、ビュー定義に $facet ステージが含まれている場合）、この $merge ステージの制限は入れ子パイプラインにも適用されます。

$lookup ステージ

$lookup ステージのネストされたパイプラインに $merge ステージを含めることはできません。

$facet ステージ

$facet ステージのネストされたパイプラインに $merge ステージを含めることはできません。

$unionWith ステージ

$unionWith ステージのネストされたパイプラインに $merge ステージを含めることはできません。

"linearizable" 読み取り保証 (read concern)

$mergeステージは読み取り保証 （read concern）"linearizable"と組み合わせて使用することはできません。つまり、 "linearizable"読み取り保証（read concern） をdb.collection.aggregate()に対して指定した場合、$mergeステージをパイプラインに含めることはできません。