$out（集計）

項目一覧

定義

構文
動作
例

定義

$out

集計パイプラインによって返されたドキュメントを受け取り、指定されたコレクションに書き込みます。出力データベースを指定できます。

$outステージはパイプラインの最後のステージである必要があります。 $out演算子を使用すると、集計フレームワークは任意のサイズの結果セットを返すことができます。

警告

$outは、指定されたコレクションが存在する場合は、それを置き換えます。詳細については、「既存のコレクションの置き換え」を参照してください。

構文

$outステージの構文は次のとおりです。

$out 出力データベースと出力コレクションを指定するためのドキュメントを受け取れます。

{ $out: { db: "<output-db>", coll: "<output-collection>" } }

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

$out 出力コレクションのみを指定する文字列を採用できます（つまり、同じデータベース内のコレクションに出力します）。
```
{ $out: "<output-collection>" } // Output collection is in the same database
```

重要

シャーディングされたコレクションを出力コレクションとして指定できません。パイプラインの入力コレクションはシャーディングできます。シャーディングされたコレクションに出力するには、 $mergeを参照してください（MongoDB 4.2 以降で利用可能）。
$out演算子は、上限付きコレクションには結果を書き込みできません。
Atlas Searchインデックスを使用してコレクションを変更する場合は、まず検索インデックスを削除して再作成する必要があります。代わりに、 $mergeの使用を検討してください。

との比較 `$merge`

バージョン4.2での$mergeの導入により、 MongoDB には、集計パイプラインの結果をコレクションに書き込むために、 $mergeと$outの 2 つのステージが用意されています。次に、2 つのステージの機能をまとめます。

$out

$merge

同じデータベースまたは異なるデータベース内のコレクションに出力できます。

同じデータベースまたは異なるデータベース内のコレクションに出力できます。

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

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

出力コレクションが既に存在する場合は、完全に置き換えます。

結果（新しいドキュメントの挿入、ドキュメントのマージ、ドキュメントの置換、既存のドキュメントの保持、操作の失敗、カスタムアップデートパイプラインによるドキュメントの処理）を既存のコレクションに組み込むことができます。
コレクションの内容を置換できます。ただし、集計結果にコレクション内に存在するすべてのドキュメントとの一致が含まれる場合に限ります。

シャーディングされたコレクションに出力できません。ただし、入力コレクションはシャーディングできます。

シャーディングされたコレクションに出力できます。入力コレクションもシャーディング可能です。

SQL ステートメントに対応します。
- INSERT INTO T2 SELECT * FROM T1
- SELECT * INTO T2 FROM T1

SQL ステートメントに対応します。

MERGE T2 AS TARGET
USING (SELECT * FROM T1) AS SOURCE
ON MATCH (T2.ID = SOURCE.ID)
WHEN MATCHED THEN
  UPDATE SET TARGET.FIELDX = SOURCE.FIELDY
WHEN NOT MATCHED THEN
  INSERT (FIELDX)
  VALUES (SOURCE.FIELDY)

マテリアライズドビューの作成と更新

動作

セカンダリレプリカセットのノードで実行される $out 読み取り操作

MongoDB5.0 以降では、クラスター内のすべてのノードの$out featureCompatibilityVersion が5.0 以上に設定され、かつ読み込み設定 (read preference) がセカンダリに設定されている場合に、レプリカセットのセカンダリノードでを実行できます。

$outステートメントの読み取り操作はセカンダリノードで実行され、書込み操作はプライマリノードでのみ実行されます。

すべてのドライバーバージョンが、レプリカセットのセカンダリノードへの$out操作のターゲットをサポートしているわけではありません。ドライバーのドキュメントをチェックして、ドライバーがセカンダリ上で実行中の$outのサポートをいつ追加したかを確認してください。

新しいコレクションの作成

$out操作では、コレクションがまだ存在しない場合に新しいコレクションが作成されます。

コレクションは、集計が完了するまで表示されません。集約が失敗した場合、MongoDB ではコレクションが作成されません。

既存のコレクションの置き換え

$out操作で指定されたコレクションがすでに存在する場合、集計の完了時に、 $outステージは既存のコレクションを新しい結果のコレクションにアトミックに置き換えます。具体的には、 $out操作は次のようになります。

一時コレクションを作成します。
既存のコレクションから一時コレクションにインデックスをコピーします。
ドキュメントを一時コレクションに挿入します。
dropTarget: true で renameCollection コマンドを呼び出し、一時コレクションの名前を宛先コレクションに変更します。

$out操作では、前のコレクションに存在していたインデックスは変更されません。集計が失敗した場合、 $out操作では既存のコレクションは変更されません。

スキーマ検証エラー

collコレクションでスキーマ検証が使用されており、 validationActionがerrorに設定されている場合、 $outを含む無効なドキュメントを挿入するとエラーがスローされます。 $out操作では既存のコレクションは変更されず、集計パイプラインによって返されたドキュメントはcollコレクションに追加されません。

インデックスの制約

パイプラインによって生成されたドキュメントが、元の出力コレクションの _id フィールドのインデックスを含め、一意のインデックスに違反する場合、パイプラインは完了しません。

$out操作によってAtlas Searchインデックスを含むコレクションが変更される場合は、検索インデックスを削除して再作成する必要があります。代わりに、 $mergeの使用を検討してください。

`majority` 読み取り保証（read concern）

$out ステージを含む集計に対して、読み取り保証 (read concern) レベル "majority" を指定できます。

相互作用: `mongodump`

mongodumpで開始されたは、ダンプ--oplog$out プロセス中にクライアントがを含む集計パイプラインを発行すると失敗します。詳しくは、 mongodump --oplogを参照してください。

制限事項

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

例

test データベースに、次のドキュメントを含むコレクション、books を作成します。

db.getSiblingDB("test").books.insertMany([
   { "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 },
   { "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 },
   { "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 },
   { "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 },
   { "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }
])

test データベースがまだ存在しない場合は、挿入操作によってデータベースと books コレクションが作成されます。

同じデータベースへの出力

次の集計操作では、test データベース内の books コレクションのデータをピボットして、著者ごとにタイトルをグループ化し、その結果を authors コレクション（同じ test データベース内）に書き込みます。

db.getSiblingDB("test").books.aggregate( [
    { $group : { _id : "$author", books: { $push: "$title" } } },
    { $out : "authors" }
] )

第 1 ステージ（$group）：

$group ステージでは authors でグループ化を行い、$push を使用して books 配列フィールドにタイトルを追加します。

{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }
{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }

第 2 ステージ（$out）：

$outステージはドキュメントをtestデータベースのauthorsコレクションに出力します。

出力コレクション内のドキュメントを表示するには、次の操作を実行します。

db.getSiblingDB("test").authors.find()

コレクションには、次のドキュメントが含まれます。

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }

別のデータベースへの出力

注意

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

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

$out 集計が実行される場所とは異なるデータベース内のコレクションに出力できます。

次の集計操作では、books コレクションのデータをピボットして、著者ごとにタイトルをグループ化し、その結果を reporting データベース内の authors コレクションに書き込みます。

db.getSiblingDB("test").books.aggregate( [
    { $group : { _id : "$author", books: { $push: "$title" } } },
    { $out : { db: "reporting", coll: "authors" } }
] )

第 1 ステージ（$group）：

$group ステージでは authors でグループ化を行い、$push を使用して books 配列フィールドにタイトルを追加します。

{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }
{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }

第 2 ステージ（$out）：

$outステージはドキュメントをreportingデータベースのauthorsコレクションに出力します。

出力コレクション内のドキュメントを表示するには、次の操作を実行します。

db.getSiblingDB("reporting").authors.find()

コレクションには、次のドキュメントが含まれます。

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }

戻る

$merge

$planCacheStats

定義

警告

構文

重要

との比較 $merge

動作

セカンダリ レプリカセットのノードで実行される $out 読み取り操作