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

$ アキュムレータ (アキュムレータ演算子)

$accumulator

重要

サーバーサイド JavaScript の非推奨化

MongoDB 8.0 以降、サーバーサイド JavaScript 関数($accumulator、$function、$where)は非推奨です。MongoDB では、これらの関数を実行すると警告がログに記録されます。

カスタムアキュムレータ演算子を定義します。 アキュムレータは、状態を維持する演算子です(例: 合計、最大、最小、および関連データ)を維持する演算子です。 MongoDB の問い合わせ言語でサポートされていない動作を実装するには、 $accumulator演算子を使用して独自の JavaScript 関数を実行します。 $functionも参照してください。

$accumulator は、次のステージで使用できます。

重要

集計演算子内で JavaScript を実行すると、パフォーマンスが低下する可能性があります。 $accumulator提供された パイプライン演算子 が アプリケーションのニーズを満たせない場合にのみ、 演算子を使用してください。

$accumulator演算子の構文は次のとおりです。

{ $accumulator: { init: <code>, initArgs: <array expression>, // Optional accumulate: <code>, accumulateArgs: <array expression>, merge: <code>, finalize: <code>, // Optional lang: <string> }}
フィールド
タイプ
説明

文字列またはコード

状態を初期化するために使用される関数。 init関数は、 initArgs配列式から引数を受け取ります。 関数の定義は、 BSONタイプのコードまたはstringとして指定できます。

init関数の形式は次のとおりです。

function (<initArg1>, <initArg2>, ...) { ... return <initialState>}

ディスクにスピルしたり、シャーディングされたクラスターでクエリを実行したりすると、アキュムレータが複数のサブアキュムレーションのマージとして計算される場合があります。この場合の各サブアキュムレーションは init() の呼び出しから始まります。init()、accumulate()、およびmerge()関数がこの実行モデルと互換性があることを確認します。

配列

オプション。init関数に渡される引数。

initArgs の形式は次のとおりです。

[ <initArg1>, <initArg2>, ... ]

重要: $bucketAuto ステージで使用する場合、initArgs はグループ キーを参照できません(つまり、$<fieldName> 構文は使用できません)。代わりに、 $bucketAuto ステージでは、 initArgs に定数値のみを指定できます。

文字列またはコード

ドキュメントを累積するために使用される関数。 accumulate関数は、現在の状態とaccumulateArgs配列式から引数を受け取ります。 accumulate関数の結果が新しい状態になります。 関数の定義は、 BSONタイプのコードまたはstringとして指定できます。

accumulate関数の形式は次のとおりです。

function(state, <accumArg1>, <accumArg2>, ...) { ... return <newState>}

配列

accumulate関数に渡される引数。accumulateArgsを使用して、 accumulate関数に渡すフィールド値を指定できます。

accumulateArgs の形式は次のとおりです。

[ <accumArg1>, <accumArg2>, ... ]

文字列またはコード

2 つの内部状態をマージするために使用される関数。 mergeは、string またはコード BSON タイプのいずれかである必要があります。 mergeは、2 つの結合された状態を組み合わせた結果を返します。 マージ 関数が呼び出されるタイミングについては、 「 $mergeを使用して 2 つの状態をマージする」 を参照してください。

merge関数の形式は次のとおりです。

function (<state1>, <state2>) { <logic to merge state1 and state2> return <newState>}

文字列またはコード

オプション。アキュムレーションの結果を更新するために使用される関数。

finalize関数の形式は次のとおりです。

function (state) { ... return <finalState>}

文字列

$accumulatorコードで使用される言語。

重要: 現在、lang でサポートされている値は js のみです。

次の手順は、 $accumulator演算子がドキュメントを処理する方法の概要です。

  1. 演算子は、init 関数によって定義された初期状態から開始されます。

  2. 各ドキュメントについて、 演算子はaccumulate関数に基づいて状態をアップデートします。 accumulate関数の最初の引数は現在の状態で、追加の引数はaccumulateArgs配列で指定します。

  3. 演算子が複数の中間状態をマージする必要がある場合、マージ関数を実行します。 マージ関数が呼び出されるタイミングの詳細については、「 $mergeを使用して 2 つの状態をマージする 」を参照してください。

  4. finalize 関数が定義されている場合、すべてのドキュメントが処理され、それに応じて状態がアップデートされると、finalize は状態を最終出力に変換します。

$accumulator演算子は、内部操作の一部として、2 つの個別の中間状態をマージする必要がある場合があります。 merge関数は、演算子が 2 つの状態をマージする方法を指定します。

merge 関数は常に、2 つの状態を一度にマージします。2 つ以上の状態をマージする必要がある場合、2 つの状態がマージされたものが 1 つの状態にマージされます。すべての状態がマージされるまで、このプロセスが繰り返されます。

たとえば、次のシナリオでは$accumulatorは 2 つの状態を組み合わせる必要がある場合があります。

  • $accumulator はシャーディングされたクラスターで実行されます。演算子は、最終結果を得るために各シャードからの結果をマージする必要があります。

  • 単一の$accumulator操作が指定されたメモリ制限を超えています。 allowDiskUseオプションを指定すると、 演算子は進行中の操作をディスクに保存し、メモリ内で操作を終了します。 操作が完了すると、ディスクとメモリの結果が マージ関数を使用してまとめられます。

MongoDB がinit() 、 accumulate() 、 merge()関数のドキュメントを処理する順序はさまざまであり、それらのドキュメントが$accumulator関数に指定される順序と異なる場合があります。

たとえば、 _idフィールドがアルファベットの文字である一連のドキュメントを考えてみましょう。

{ _id: 'a' },{ _id: 'b' },{ _id: 'c' }...{ _id: 'z' }

次に、ドキュメントを_idフィールドでソートし、 $accumulator関数を使用して_idフィールド値を連結する集計パイプラインを考えてみましょう。

[ { $sort: { _id: 1 } }, { $group: { _id: null, alphabet: { $accumulator: { init: function() { return "" }, accumulate: function(state, letter) { return(state + letter) }, accumulateArgs: [ "$_id" ], merge: function(state1, state2) { return(state1 + state2) }, lang: "js" } } } }]

MongoDB では、ドキュメントがソート順で処理されることは保証されません。つまり、 alphabetフィールドは必ずしもabc...zに設定されるわけではありません。

この動作により、 $accumulator関数ではドキュメントを特定の順序で処理して返す必要がなくなりました。

$accumulatorを使用するには、サーバー側スクリプトを有効にする必要があります。

$accumulator(または $function、$where、mapReduce)を使用しない場合は、サーバー側スクリプトを無効にします。

  • mongodインスタンスについては、 security.javascriptEnabled構成オプションまたは--noscriptingコマンドライン オプションを参照してください。

  • mongosインスタンスについては、 security.javascriptEnabled構成オプションまたは--noscriptingコマンドライン オプションを参照してください。

    以前のバージョンでは、MongoDB はmongosインスタンスでの JavaScript の実行を許可しません。

➤ 安全な構成オプションを使用して MongoDB を実行するも参照してください。

MongoDB 6.0 では、サーバーサイド JavaScript 、 $accumulator 、 $function 、 $where式に使用される内部 JavaScript エンジンが MozJS- 60から MozJS- 91 にアップグレードされています。MozJS-60 に存在した非推奨、非標準の配列関数と文字列関数は、MozJS-91 で一部削除されました。

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

注意

この例では、 $accumulator演算子を使用して$avg演算子を実装する方法について説明します。この演算子は MongoDB ですでにサポートされています。 この例の目的は新しい機能を実装することではなく、 $accumulator演算子の動作と構文を既知のロジックで説明することです。

次の操作では、ドキュメントをratedごとにgroupsし、 $accumulatorを使用して各コンテンツ評価の平均imdb.ratingを計算します。$matchステージは、入力をG、PG、PG-13、およびRのコンテンツ評価に制限し、空のstringなど、imdb.ratingがdoubleではないドキュメントを除外します。

db.movies.aggregate( [ { $match: { rated: { $in: [ "G", "PG", "PG-13", "R" ] }, "imdb.rating": { $type: "double" } } }, { $group: { _id: "$rated", avgRating: { $accumulator: { init: function() { // Set the initial state return { count: 0, sum: 0 } }, accumulate: function(state, rating) { // Define how to update the state return { count: state.count + 1, sum: state.sum + rating } }, accumulateArgs: [ "$imdb.rating" ], // Argument required by the accumulate function merge: function(state1, state2) { // When the operator performs a merge, return { // add the fields from the two states count: state1.count + state2.count, sum: state1.sum + state2.sum } }, finalize: function(state) { // After collecting the results from all documents, return (state.sum / state.count) // calculate the average }, lang: "js" } } } }, { $sort: { _id: 1 } }] )
[ { _id: 'G', avgRating: 6.628092243186578 }, { _id: 'PG', avgRating: 6.43525917926564 }, { _id: 'PG-13', avgRating: 6.404911676001717 }, { _id: 'R', avgRating: 6.456657633242984 }]

$accumulatorは、 countとsumの両方が0に設定されている初期状態を定義します。 $accumulatorが処理するドキュメントごとに、状態を次の方法で更新します。

  • countを1増やし、

  • Adding the values of the document's imdb.rating field to the sum. accumulate関数はimdb.ratingフィールドにアクセスできます。これはaccumulateArgsフィールドで渡されるためです。

プロセスされるドキュメントごとに、accumulate 関数はアップデートした状態を返します。

すべてのドキュメントが処理されると、finalize関数は評価のsumをドキュメントのcountで割って平均を求めます。これにより、finalize関数がすべてのドキュメントの累積sumとcountを受け取るため、計算された平均を保持し続ける必要がなくなります。

この操作は、 $avg演算子を使用する次のパイプラインと同等です。

db.movies.aggregate( [ { $match: { rated: { $in: [ "G", "PG", "PG-13", "R" ] }, "imdb.rating": { $type: "double" } } }, { $group: { _id: "$rated", avgRating: { $avg: "$imdb.rating" } } }, { $sort: { _id: 1 } }] )
[ { _id: 'G', avgRating: 6.6280922431865825 }, { _id: 'PG', avgRating: 6.435259179265659 }, { _id: 'PG-13', avgRating: 6.404911676001723 }, { _id: 'R', avgRating: 6.456657633242999 }]

initArgsオプションを使用すると、$accumulatorの初期状態を変更できます。これは、例として次のような場合に役立ちます。

  • 自分の状態にないフィールドの値を使用して自分の状態に影響を与えるか、または

  • 現在処理中のグループに基づいて、初期状態を異なる値に設定します。

あるアプリケーションで、ユーザーがこのデータをクエリして映画を検索できるとします。ユーザーが好むコンテンツレーティングの結果をさらに表示すると便利な場合があります。この例では、ユーザーが好むコンテンツレーティングは PG-13 であり、これは userProfileRated として init 関数に渡されます。

次の集計パイプラインgroupsは、ドキュメントをratedで処理します。この操作では、$accumulatorを使用して、映画の評価がユーザープロファイルの評価と一致するかどうかに応じて、各コンテンツ評価から異なる数の映画を表示します。

注意

この例を別の推奨コンテンツレーティングで実行するには、initArgs 配列の "PG-13" を "R" などの別の値に置き換えます。

db.movies.aggregate( [ { $match: { rated: { $in: [ "G", "PG", "PG-13", "R" ] }, "imdb.rating": { $type: "double" } } }, { $sort: { "imdb.rating": -1, title: 1 } }, { $group: { _id: { rated: "$rated" }, movies: { $accumulator: { init: function(rated, userProfileRated) { // Set the initial state return { max: rated === userProfileRated ? 3 : 1, // If the group matches the user's rating, movies: [] // return 3 movies. Otherwise, return 1. } }, initArgs: [ "$rated", "PG-13" ], // Argument to pass to the init function accumulate: function(state, movieTitle) { // Define how to update the state if (state.movies.length < state.max) { state.movies.push(movieTitle); } return state; }, accumulateArgs: [ "$title" ], // Argument required by the accumulate function merge: function(state1, state2) { return { max: state1.max, movies: state1.movies.concat(state2.movies).slice(0, state1.max) } }, finalize: function(state) { // Adjust the state to only return the field we need return state.movies }, lang: "js" } } } }, { $sort: { "_id.rated": 1 } }] )
[ { _id: { rated: 'G' }, movies: [ 'Modern Times' ] }, { _id: { rated: 'PG' }, movies: [ 'Life' ] }, { _id: { rated: 'PG-13' }, movies: [ 'A Brave Heart: The Lizzie Velasquez Story', 'The Dark Knight', 'The Lord of the Rings: The Return of the King' ] }, { _id: { rated: 'R' }, movies: [ 'The Shawshank Redemption' ] }]

init 関数は、max フィールドと movies フィールドを含む初期状態を定義します。max フィールドは、その特定のグループの映画の最大数を設定します。ドキュメントの rated フィールドが userProfileRated と一致する場合、そのグループには最大 3 本の映画が含まれます。それ以外の場合、ドキュメントの rated フィールドが userProfileRated と一致しない場合、グループには最大で 1 本の映画が含まれます。init 関数は、initArgs 配列から rated 引数と userProfileRated 引数の両方を受け取ります。

$accumulator が処理するドキュメントごとに、映画のtitleをmovies配列にプッシュします。ただし、そのタイトルによって、 moviesの長さがmax値を超えない場合に限ります。プロセスされるドキュメントごとに、accumulate 関数は更新された状態を返します。

merge 関数は、2 つの状態をマージする方法を定義します。この関数は各州のmovies 配列をまとめて連結し、結果の配列の長さが slice() メソッドを使用して制限され、max 値を超えないようにします。

すべてのドキュメントが処理されると、finalize 関数は結果の状態を変更し、映画のタイトルのみを返します。この関数がないと、maxフィールドも出力に含まれてしまい、アプリケーションのニーズを満たせなくなります。

このページを評価