AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

集計(データベースコマンド)

aggregate

集計パイプラインを使用して集計操作を実行します。パイプラインを使用すると、コレクションまたはその他のソースからのデータをステージのシーケンスで処理できます。

Tip

mongoshでは、このコマンドはdb.aggregate()およびdb.collection.aggregate()ヘルパー メソッドまたはwatch()ヘルパー メソッドを使用して実行することもできます。

ヘルパー メソッドはmongoshユーザーには便利ですが、データベースコマンドと同じレベルの情報は返されない可能性があります。 便宜上必要ない場合、または追加の戻りフィールドが必要な場合は、 データベースコマンドを使用します。

このコマンドは、次の環境でホストされている配置で使用できます。

  • MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージド サービスです

重要

このコマンドは、M0 およびフレックス クラスターで限定的にサポートされています。詳細については、「サポートされていないコマンド」を参照してください。

  • MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン

  • MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

バージョン5.0で変更。

このコマンドの構文は、次のとおりです。

db.runCommand( { aggregate: "<collection>" || 1, pipeline: [ <stage>, <...> ], explain: <boolean>, allowDiskUse: <boolean>, allowPartialResults: <boolean>, cursor: <document>, maxTimeMS: <int>, bypassDocumentValidation: <boolean>, readConcern: <document>, collation: <document>, hint: <string or document>, comment: <any>, writeConcern: <document>, let: <document>, // Added in MongoDB 5.0 querySettings: <document> // Added in MongoDB 9.0 })

aggregate コマンドは、次のフィールドを引数として受け取ります。

フィールド
タイプ
説明

aggregate

string

集約パイプラインへの入力となるコレクションまたはビューの名前。コレクションに依存しないコマンドには 1 を使用します。

pipeline

配列

集計パイプラインの一部としてドキュメントストリームを処理および変換する集計パイプライン ステージの配列。

explain

ブール値

任意。パイプラインの処理に関する情報を返すように指定します。

マルチドキュメントトランザクションでは使用できません。

allowDiskUse

ブール値

任意。

このオプションを使用して、特定のクエリの allowDiskUseByDefault をオーバーライドできます。このオプションは下記のいずれかに使用できます。

  • デフォルトでディスクの使用が許可されているシステムで、ディスクの使用を禁止する。

  • デフォルトでディスクの使用が禁止されているシステムで、ディスクの使用を許可する。

MongoDB 6.0 以降では、 allowDiskUseByDefault が true に設定されており、かつパイプライン実行ステージのために 100 MB を超えるメモリがサーバーに必要な場合、クエリで { allowDiskUse: false } が指定されていない限り、MongoDB では一時ファイルが自動的にディスクに書き込まれます。

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

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

allowPartialResults

ブール値

任意。シャーディングされたコレクションに対して mongos を実行する集計の場合、クエリされたシャードが 1 つ以上使用できないときに、コマンドがエラーではなく部分的な結果を返すことがあります。後続の getMore コマンドも部分的な結果を返すことがあります。デフォルトは false で、クエリされたシャードが使用できない場合はエラーを返します。

allowPartialResults は、最初の aggregate コマンドでのみ設定してください。getMore で設定することはできませんが、各 getMore はカーソルから設定を継承します。

シャードはいつの点でも使用できなくなる可能性があるため、部分的な結果は初期の aggregate 応答、後の getMore 応答、またはその両方で表示される可能性があります。バッチするが利用できないシャードからの結果を省略する場合、そのバッチするの応答には partialResultsReturned: true フィールドが含まれます。クエリされたすべてのシャードがバッチするに利用可能になった場合、応答では partialResultsReturned が省略されます。partialResultsReturned は、利用可能なシャードからのドキュメントのみを含めることができます。partialResultsReturned が true の場合、結果セットが完全であるとは想定しないでください。

パイプラインが以下の場合、このコマンドは InvalidOptions エラーを返します。

  • $out や $merge などの書き込み (write) ステージで終了します。

  • 変更ストリーム集計です。

  • $search、$vectorSearch、$rankFusion、$scoreFusionなどのAtlas Searchステージが含まれます。

cursor

ドキュメント

カーソルオブジェクト作成を制御するオプションを含めたドキュメントを指定。

コマンドに explain オプションが含まれていない限り、cursor オプションとともに aggregate コマンドを使用する必要があります。

  • デフォルトのバッチ サイズのカーソルを示すには、cursor: {} を指定します。

  • デフォルト以外のバッチ サイズのカーソルを示すには、cursor: { batchSize: <num> } を使用します。

maxTimeMS

non-negative integer

任意。

時間制限をミリ秒単位で指定します。maxTimeMS の値を指定しない場合、操作はタイムアウトしません。値を 0 にすると、デフォルトの無制限動作を明示的に指定します。

MongoDB は、db.killOp() と同じメカニズムを使用して、割り当てられた時間制限を超えた操作を終了します。MongoDB は、指定された割り込みポイントのいずれかでのみ操作を終了します。

bypassDocumentValidation

ブール値

任意。$outまたは $merge 集計ステージを指定した場合にのみ該当します。

aggregate を有効にすると、操作中にスキーマ検証をバイパスできます。これにより、検証要件を満たさないドキュメントを挿入できるようになります。

readConcern

ドキュメント

任意。読み取り保証 (read concern) を指定します。

readConcern オプションの構文は、次のとおりです。readConcern: { level: <value> }

次の読み取り保証レベルが利用できます。

  • "local"。これは、プライマリとセカンダリに対する読み取り操作での、デフォルトの読み取り保証レベルです。

  • "available" 。プライマリおよびセカンダリに対する読み取り操作に使用できます。"available" は、プライマリおよびシャーディングされていないセカンダリに対して "local" と同じように動作します。クエリは、インスタンスの最新データを返します。

  • "majority" 。WiredTiger ストレージ エンジンを使用するレプリカセットで使用できます。

  • "linearizable" 。primary の読み取り操作にのみ使用できます。

  • "snapshot"。マルチドキュメントトランザクションおよびマルチドキュメントトランザクション以外の特定の読み取り操作で利用可能です。

読み取り保証 (read concern) のレベルについて詳しくは、「読み取り保証 (read concern) レベル」を参照してください。

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

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

collation

ドキュメント

任意。

任意。操作に使用する照合を指定します。

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

照合オプションの構文は次のとおりです。

collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> }

照合を指定する場合、locale フィールドは必須ですが、その他の照合フィールドはすべて任意です。フィールドの説明については、照合ドキュメントを参照してください。

照合が指定されていなくても、コレクションにデフォルトの照合が設定されている場合(db.createCollection() を参照)には、コレクションの照合が使用されます。

コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって文字列が比較されます。

1 つの操作に複数の照合は指定できません。たとえば、フィールドごとに異なる照合を指定できません。また、ソートと検索を一度に実行する場合、検索とソートで別の照合を使用できません。

hint

文字列またはドキュメント

任意.集計に使用するインデックス。インデックスは、集計が実行される初期コレクションまたはビューにあります。

インデックス名、またはインデックス仕様ドキュメントのいずれかによってインデックスを指定します。

hint は $lookup および$graphLookup ステージには適用されません。

comment

any

任意。このコマンドに添付するユーザー指定のコメント。設定すると、このコメントは以下の場所にこのコマンドの記録と合わせて表示されます。

コメントには、有効な BSON 型(string, integer, object, array など)を使用できます。

aggregate コマンドに設定されたコメントは、aggregate カーソルで実行される後続の getMore コマンドに継承されます。

writeConcern

ドキュメント

任意。または $out$mergeステージで使用する 書き込みの考慮事項 を表すドキュメント。

$out または $merge ステージでデフォルトの書き込み保証を使用しません。

let

ドキュメント

任意。

変数のリストを含むドキュメントを指定します。これにより、変数をクエリテキストから分離することで、コマンドの読みやすさを向上させることができます。

ドキュメントの構文は次のとおりです。

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

変数は式によって返された値に設定され、その後は変更できません。

コマンド内の変数の値にアクセスするには、二重ドル記号の接頭辞($$)を $$<variable_name> 形式にした変数名とともに使用します。たとえば次のとおりです。$$targetTotal

パイプライン $match ステージで変数を使用して結果をフィルター処理するには、$exprオペレーター内で変数にアクセスする必要があります。

let と変数を使用した完全な例については、「let における変数の使用」を参照してください。

バージョン 5.0 の新機能。

querySettings

ドキュメント

任意。このコマンドの実行にのみ適用されるクエリ設定。querySettingsドキュメントは、次のフィールドを受け入れます。

  • indexHints

  • queryFramework

  • reject

  • comment

  • queryKnobs

  • maxTimeMS

これらのフィールドの説明については、コマンドフィールドを参照してください。

MongoDB は、これらの設定をクラスター上に保存しません。また、同じクエリシェイプを持つ他のクエリには適用されません。クエリシェイプに対して持続するクエリ設定を設定するには、setQuerySettings. を使用します。

MongoDBは、コマンドで渡された設定と、同じクエリシェイプに対してクラスターに保存されているクエリ設定を組み合わせます。両方の設定で同じフィールドが指定されている場合、保存されているクラスター設定が優先されます。

バージョン9.0の新機能。

コマンドに explain オプションが含まれていない限り、cursor オプションとともに aggregate コマンドを使用する必要があります。

  • デフォルトのバッチ サイズのカーソルを示すには、cursor: {} を指定します。

  • デフォルト以外のバッチ サイズのカーソルを示すには、cursor: { batchSize: <num> } を使用します。

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

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

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

MongoDB ドライバーとmongosh では、確認されていない書込み操作を除くすべての操作がサーバー セッションに関連付けられます。セッションに明示的に関連付けられていない操作(つまり Mongo.startSession()を使用するもの)の場合、MongoDB ドライバーとmongoshによって暗黙的なセッションが作成され、それが操作に関連付けられます。

セッションが30分以上アイドル状態になると、MongoDBサーバーはそのセッションを期限切れとしてマークし、いつでも閉じる可能性があります。MongoDB サーバーでセッションが閉じると、そのセッションで進行中の操作や開いているカーソルもすべて終了します。これには、noCursorTimeout() や 30 分を超える maxTimeMS() で構成されたカーソルも含まれます。

カーソルが 30 分以上アイドル状態になる可能性がある場合は、Mongo.startSession() を使用して明示的なセッション内で操作を発行します。refreshSessions コマンドを使用してセッションを定期的に更新します。詳細については、「セッションアイドルタイムアウト」を参照してください。

aggregate は分散トランザクション内で使用できます。

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

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

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

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

重要

ほとんどの場合、分散トランザクションでは 1 つのドキュメントの書き込み (write) よりもパフォーマンス コストが高くなります。分散トランザクションの可用性は、効果的なスキーマ設計の代わりにはなりません。多くのシナリオにおいて、非正規化されたデータモデル(埋め込みドキュメントと配列)が引き続きデータやユースケースに最適です。つまり、多くのシナリオにおいて、データを適切にモデリングすることで、分散トランザクションの必要性を最小限に抑えることができます。

トランザクションの使用に関するその他の考慮事項(ランタイム制限や oplog サイズ制限など)については、「本番環境での考慮事項」も参照してください。

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

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

バージョン8.0の新機能。

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

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

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

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

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

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

Stable API V1 を使用する場合、aggregate コマンドはサポートされていますが、次の例外があります。

コマンドに explain オプションが含まれていない限り、cursor オプションとともに aggregate コマンドを使用する必要があります。

  • デフォルトのバッチ サイズのカーソルを示すには、cursor: {} を指定します。

  • デフォルト以外のバッチ サイズのカーソルを示すには、cursor: { batchSize: <num> } を使用します。

aggregateコマンドを直接実行する代わりに、 のdb.collection.aggregate() mongoshヘルパーまたはドライバーの同等のヘルパーを使用します。

コマンド構文を示す最初の 2 つの例を除き、このページの例では db.collection.aggregate() ヘルパーを使用します。

このページの例では、sample_mflix データセット のデータを使用しています。自己管理型 MongoDB 配置にこのデータセットをロードする方法の詳細については、「サンプル データセットのロード」を参照してください。サンプル データベースに何らかの変更を加えた場合は、今ページの例を実行するには、データベースを削除して再作成する必要がある可能性があります。

sample_mflixデータベースの moviesコレクションには次のdocumentが含まれています。

注意

moviesコレクション内のdocumentには、ここに表示されていない追加フィールドが含まれています。

{ title: 'The Shawshank Redemption', year: 1994, genres: [ 'Crime', 'Drama' ], runtime: 142, imdb: { rating: 9.3, votes: 1521105, id: 111161 }, directors: [ 'Frank Darabont' ], cast: [ 'Tim Robbins', 'Morgan Freeman', 'Bob Gunton', 'William Sadler' ],},{ title: 'The Godfather', year: 1972, genres: [ 'Crime', 'Drama' ], runtime: 175, imdb: { rating: 9.2, votes: 1038358, id: 68646 }, directors: [ 'Francis Ford Coppola' ], cast: [ 'Marlon Brando', 'Al Pacino', 'James Caan', 'Richard S. Castellano' ]},{ title: 'Pulp Fiction', year: 1994, genres: [ 'Crime', 'Drama' ], runtime: 154, imdb: { rating: 8.9, votes: 1179033, id: 110912 }, directors: [ 'Quentin Tarantino' ], cast: [ 'Tim Roth', 'Amanda Plummer', 'Laura Lovelace', 'John Travolta' ]},{ 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' ],},{ title: 'Inception', year: 2010, genres: [ 'Action', 'Sci-Fi', 'Thriller' ], runtime: 148, imdb: { rating: 8.8, votes: 1294646, id: 1375666 }, directors: [ 'Christopher Nolan' ], cast: [ 'Leonardo DiCaprio', 'Joseph Gordon-Levitt', 'Ellen Page', 'Tom Hardy' ],}

次の例では、movies コレクションを集計して、各個の個別のジャンルの数を計算します。

db.runCommand( { aggregate: "movies", pipeline: [ { $project: { genres: 1 } }, { $unwind: "$genres" }, { $group: { _id: "$genres", count: { $sum : 1 } } } ], cursor: { }} )

mongosh で、db.collection.aggregate() ヘルパーを使用して同じ集計を実行します。

db.movies.aggregate( [ { $project: { genres: 1 } }, { $unwind: "$genres" }, { $group: { _id: "$genres", count: { $sum: 1 } } } ])

次の例では、管理データベースで 2 段階のパイプラインを実行します。最初のステージでは $currentOp 操作を実行し、2 番目のステージでは結果をフィルターします。

db.adminCommand( { aggregate : 1, pipeline : [ { $currentOp : { allUsers : true, idleConnections : true } }, { $match : { shard : "shard01" } } ], cursor : { } })

注意

aggregate コマンドはコレクションを指定せず、代わりに {aggregate: 1} の形式を取ります。最初の $currentOp ステージでは、コレクションから入力が取得されません。ステージは、パイプラインの残りの部分が使用する独自のデータを生成します。

db.aggregate() ヘルパーは、このようなコレクションレス集計をサポートします。上の集計は、この例のように実行します。

次の例では、explain を true に設定して集計に関する情報を返します。

db.comments.aggregate( [ { $match: { date: { $gte: ISODate("2015-01-01") } } }, { $group: { _id: "$movie_id", commentCount: { $sum: 1 } } }, { $sort: { commentCount: -1 } } ], { explain: true })

注意

explain の出力は、リリース間で変更される可能性があります。

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

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

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

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

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

初期バッチサイズを設定するには、cursor フィールドに batchSize を含めます。

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 操作のバッチする サイズを指定するには、mongosh で batchSize() を使用するか、getMore コマンドで batchSize フィールドを使用します。

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

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

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

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

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

{ 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 } })

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

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

重要

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

  • 読み取り保証のレベルを問わず、ノード上の最新データにシステム内のデータの最新バージョンが反映されていない場合があります。

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" 書込み保証を使用します。

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

注意

パイプライン $match ステージで変数を使用して結果をフィルター処理するには $expr 演算子内で変数にアクセスする必要があります。

sample_mflixデータベースの moviesコレクションには次のようなdocumentが含まれています。

{ title: "The Shawshank Redemption", year: 1994, rated: "R", imdb: { rating: 9.3, votes: 1513145, id: 111161 }, runtime: 142}

次の例では、let オプションを使用してパイプラインの変数を定義します。この例では、評価が高く上映時間が長い映画を検索します。

db.runCommand( { aggregate: "movies", pipeline: [ { $match: { $expr: { $and: [ { $gte: [ "$imdb.rating", "$$minRating" ] }, { $gte: [ "$runtime", "$$minRuntime" ] } ] } } }, { $project: { title: 1, year: 1, "imdb.rating": 1, runtime: 1 } }, { $sort: { "imdb.rating": -1 } }, { $limit: 3 } ], cursor: {}, let: { minRating: 8.5, minRuntime: 120 }} )