db.コレクション.aggregate()（mongoshメソッド）

パラメーター

aggregate() メソッドは次のパラメーターを取ります。

Error Handling

エラーが発生した場合、aggregate() ヘルパーは例外をスローします。

カーソルの動作

mongoshでは、 db.collection.aggregate()から返されたカーソルがvarキーワードを使用して変数に割り当てられていない場合、 mongoshは最大20回までカーソルを自動的に反復します。 mongoshでのカーソルの処理については、「 でのカーソルの反復mongosh 」を参照してください。

集計から返されるカーソルは、評価済みカーソル（最初のバッチが取得されたカーソル）で動作する次のようなカーソル メソッドのみをサポートします。

詳細については、以下を参照してください。

• Aggregation Pipeline

• 集計リファレンス

• 集計パイプラインの制限

• aggregate

セッション

セッション内で作成されたカーソルの場合、セッション外で getMore を呼び出すことはできません。

同様に、セッション外で作成されたカーソルの場合、セッション内で getMore を呼び出すことはできません。

トランザクション

db.collection.aggregate() は分散トランザクション内で使用できます。

ただし、トランザクション内では以下のステージは許可されません。

• $collStats

• $currentOp

• $indexStats

• $listLocalSessions

• $listSessions

• $out

• $merge

• $planCacheStats

また、explain オプションも指定できません。

• トランザクションの外部で作成されたカーソルの場合、トランザクション内で getMore を呼び出せません。

• トランザクション内で作成されたカーソルの場合、トランザクション外で getMore を呼び出せません。

クライアントの切断

$out ステージまたは $merge ステージを含まない db.collection.aggregate() 操作の場合。

操作が完了する前にdb.collection.aggregate()を発行したクライアントが切断された場合、MongoDB はdb.collection.aggregate()をkillOpを使用して終了対象としてマークします。

クエリ設定

クエリ設定を使用して、インデックスヒント、操作拒否フィルター、その他のフィールドを設定できます。設定はクラスター全体のクエリシェイプに適用されます。クラスターは、シャットダウン後も設定を保持します。

クエリオプティマイザは、クエリプランニング中の追加入力としてクエリ設定を使用します。これは、クエリを実行するために選択されたプランに影響します。クエリ設定を使用してクエリシェイプをブロックすることもできます。

クエリ設定を追加して例を調べるには、setQuerySettings を参照してください。

find、distinct、aggregate コマンドのクエリ設定を追加できます。

クエリ設定にはより多くの機能があり、廃止されたインデックスフィルターよりも優先されます。

クエリ設定を削除するには、 removeQuerySettingsを使用します。 クエリ設定を取得するには、集計パイプラインの$querySettingsステージを使用します。

グループ化と合計の計算

次の集計操作を行います。

• IMDB 評価が 8.5 を超える映画を選択します

• 一致する映画を yearフィールドでグループ化します

• imdb.ratingフィールドの平均から各 year の averageRating を計算します

• averageRatingフィールドで結果を降順にソートします

db.movies.aggregate(
    [
       { $match: { "imdb.rating": { $gt: 8.5 } } },
       { $group: { _id: "$year", averageRating: { $avg: "$imdb.rating" } } },
       { $sort: { averageRating: -1 } },
       { $limit: 3 }
    ] 
)

この操作は、次のドキュメントを持つカーソルを返します。

[
  { _id: 1972, averageRating: 9.2 },
  { _id: 1990, averageRating: 9.166666666666666 },
  { _id: 1974, averageRating: 9.1 }
]

mongosh は返されたカーソルを自動的に反復して結果を出力します。mongosh でカーソルを手動で取り扱うには、「mongosh でのカーソルの反復」を参照してください。

集計パイプライン操作に関する情報を返します。

次の例では、db.collection.explain() を使用して、集計パイプラインの実行プランに関する詳細情報を表示します。

db.movies.explain().aggregate( 
    [
       { $match: { "imdb.rating": { $gt: 8.5 } } },
       { $group: { _id: "$year", averageRating: { $avg: "$imdb.rating" } } },
       { $sort: { averageRating: -1 } }
    ] 
)

この操作は集計パイプラインの処理を詳述するドキュメントを返します。 たとえば、このドキュメントにはどのインデックスが操作に使用されたかなどの詳細が示されます。 [ 1 ] moviesコレクションがシャーディングされたコレクションの場合は、シャード間の作業分担やマージ操作、ターゲットクエリの場合にはターゲットシャードもドキュメントに表示されます。

executionStats または allPlansExecution 説明モードを db.collection.explain() メソッドに渡すと、より冗長な説明出力を表示できます。

相互作用: allowDiskUseByDefault

実行に 100 MB を超えるメモリを必要とするパイプライン ステージは、デフォルトで一時ファイルをディスクに書き込みます。これらの一時ファイルはパイプラインの実行中ずっと残り、インスタンスのストレージ容量に影響を与える可能性があります。

個々の find と aggregate コマンドは、次のいずれかの方法で allowDiskUseByDefault パラメーターを上書きできます。

• allowDiskUseByDefaultが false に設定されている場合に { allowDiskUse: true } を使用して一時ファイルをディスクに書き込むことを許可する

• allowDiskUseByDefault が true に設定されている場合に { allowDiskUse: false } を使用して一時ファイルがディスクに書き込むことを禁止する

プロファイラー ログ メッセージと診断ログ メッセージには、メモリ制限のために集計ステージで一時ファイルにデータが書込まれた場合、usedDisk インジケーターが含められます。

詳細については、「集計パイプラインの制限」を参照してください。

初期バッチ サイズの指定

カーソルの初期バッチ サイズを指定するには、cursor オプションに次の構文を使用します。

cursor: { batchSize: <int> }

たとえば、次の集計操作では、カーソルの初期バッチサイズとして 0 を指定します。

db.theaters.aggregate( 
    [
       { $match: { "location.address.state": "NY" } },
       { $group: { _id: "$location.address.city", theaterCount: { $sum: 1 } } },
       { $sort: { theaterCount: -1 } },
       { $limit: 2 }
    ],
    { cursor: { batchSize: 0 } }
)

初期バッチのサイズを指定する { cursor: { batchSize: 0 } } ドキュメントは、1 個めのバッチが空であることを示します。このバッチサイズは、サーバー側での目立った作業なしに、カーソルやエラーメッセージをすばやく返すのに便利です。

後続の getMore 操作（最初のバッチの後）のバッチ サイズを指定するには、getMore コマンドを実行する際に batchSize フィールドを使用します。

mongosh は返されたカーソルを自動的に反復して結果を出力します。mongosh でカーソルを手動で取り扱うには、「mongosh でのカーソルの反復」を参照してください。

照合の指定

照合を指定すると、大文字・小文字やアクセント記号など、文字列を比較するための言語独自のルールを指定できます。

次の集計操作では、sample_mflixデータベースの moviesコレクション内のすべてのフランス語映画のタイトルが返され、fr 照合を指定します。

db.movies.aggregate(
    [ 
       { $match: {"countries": "France", "languages": "French"} }, 
       { $project: { "title": 1, "_id": 0 } }
    ],
    { collation: { locale: "fr", strength: 1 } }
)

照合フィールドの説明については、照合ドキュメントを参照してください。

インデックスの hint

sample_mflixデータベースの moviesコレクションには、次と同様のドキュメントが含まれています。

{
   title: "The Shawshank Redemption",
   year: 1994, rated: "R",
   imdb: { rating: 9.3, votes: 1513145, id: 111161 }
},
{
   title: "The Godfather",
   year: 1972,
   rated: "R",
   imdb: { rating: 9.2, votes: 1038358, id: 68646 }
},
{
   title: "The Dark Knight",
   year: 2008, rated: "PG-13",
   imdb: { rating: 9, votes: 1495351, id: 468569 }
},
{
   title: "Forrest Gump",
   year: 1994,
   rated: "PG-13",
   imdb: { rating: 8.8, votes: 1087227, id: 109830 }
}

moviesコレクションに次のインデックスが存在するとします。

db.movies.createIndex( { "imdb.rating": 1, year: 1 } )

db.movies.createIndex( { "imdb.rating": 1, rated: 1 } )

下記の集計操作には、指定されたインデックスの使用を強制する hint オプションが含まれています。

db.movies.aggregate(
    [
        { $sort: { "imdb.rating": 1 } }, 
        { $match: { rated: "R", "imdb.rating": { $gte: 9.0 } } }, 
        { $sort: { year: -1 } } 
    ],
    { hint: { "imdb.rating": 1, rated: 1 } }
)

[readConcern] の上書き readConcern

デフォルトの読み取り保証 (read concern) レベルを上書きするには、readConcern オプションを使用します。getMore コマンドは、元の aggregate コマンドで指定された readConcern レベルを使用します。

moviessample_mflixデータベースから コレクションに対する次の操作では、過半数のノードに書き込まれたことが確認されたデータの最新のコピーを読み取るために、 "majority"の読み取り保証(read concern)を指定します。

db.movies.aggregate(
    [ 
       { $match: { "imdb.rating": { $gte: 8.0 } } },
       { $group: { _id: "$rated", avgRating: { $avg: "$imdb.rating" }, count: { $sum: 1 } } },
       { $sort: { avgRating: -1 } }
    ],
    { readConcern: { level: "majority" } }
)

単一のスレッドでそれ自体の書き込みの読み取りを可能にするには、レプリカセットのプライマリに対して "majority" 読み取り保証と "majority" 書込み保証を使用します。

コメントの指定

sample_mflixサンプルデータセットの moviesコレクションには、次のドキュメントと同様のドキュメントが含まれています。

{
   title: 'Forrest Gump',
   year: 1994,
   genres: [ 'Drama', 'Romance' ],
   runtime: 142,
   imdb: { rating: 8.8, votes: 1087227, id: 109830 },
   directors: [ 'Robert Zemeckis' ],
   cast: [ 'Tom Hanks', 'Rebecca Williams', 'Sally Field', 'Michael Conner Humphreys' ],
}

次の集計操作では、1994 で作成された映画が検索し、comment オプションを含めて、logs、db.system.profileコレクション、db.currentOp 内の追跡情報を提供します。

db.movies.aggregate( 
    [ 
        { $match: { year : 1994 } },
        { $limit: 3 }
    ], 
    { comment: "match_three_movies_from_1994" } 
)

プロファイリングが有効になっているシステムでは、以下で示すように、system.profile コレクションにクエリを実行して、すべての最新の類似した集計を確認できます。

db.system.profile.find( { "command.aggregate": "movies", "command.comment" : "match_three_movies_from_1994" } ).sort( { ts : -1 } ).pretty()

このクエリでは、プロファイラーの結果セットが次の形式で返されます。

{
  "op" : "command",
  "ns" : "video.movies",
  "command" : {
    "aggregate" : "movies",
    "pipeline" : [
      {
        "$match" : {
          "year" : 1994
        }
      },
      { "$limit": 3 }
    ],
    "comment" : "match_three_movies_from_1994",
    "cursor" : {
    },
    "$db" : "video"
  },
  ...
}

アプリケーションは、システム内の特定の操作をより簡単に追跡または識別できるように、コメントに任意の情報をエンコードできます。たとえば、プロセス ID、スレッド ID、クライアントのホスト名、コマンドを発行したユーザーを含む文字列コメントを添付できます。

変数の使用 let

コマンド内の他の場所からアクセスできる変数を定義するには、 letオプションを使用します。

次の例：

• 一致するドキュメントは、imdb.ratingフィールドが 8.5 より大きい sample_mflix.moviesコレクションのドキュメントで、結果は 3 つに限定されます

• let で minRating 変数を定義します。これは $gt で $$minRating として参照されます。

db.movies.aggregate(
    [
       { $match: {
          $expr: { $gt: [ "$imdb.rating", "$$minRating" ] }
       } },
       { $limit: 3 }
    ],
    { let: { minRating: 8.5 } }
)