/ /

$function（式）

定義

$function

重要

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

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

JavaScript でカスタム集計関数または式を定義します。

$function演算子を使用して、 MongoDB問い合わせ言語ではサポートされていない動作を実装するカスタム関数を定義できます。$accumulator も参照してください。

重要

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

構文

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

{
  $function: {
    body: <code>,
    args: <array expression>,
    lang: "js"
  }
}

フィールド	タイプ	説明
body	文字列またはコード	関数の定義。関数の定義は、 BSONタイプのコードまたは文字列として指定できます。 lang も参照してください。 `function(arg1, arg2, ...) { ... }` or `"function(arg1, arg2, ...) { ... }"`
args	配列	関数本体に渡される引数。 body 関数が引数を取らない場合は、空の配列`[ ]` を指定できます。配列要素は、コードを含む任意のBSONタイプにすることができます。例 2を参照:`$where` の代替手段。
lang	文字列	body 内で使用される言語。`lang: "js"` を指定する必要があります。

Considerations

スキーマ検証の制限

$functionスキーマ検証クエリ述語の一部としてを使用することはできません。

Javascript Enablement

$functionを使用するには、サーバー側スクリプトを有効にする必要があります（デフォルト）。

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

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

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

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

代替 `$where`

クエリ演算子 $where を使用して JavaScript 式を指定することもできます。ただし、

$expr 演算子を使用すると、クエリ言語内で集計式を使用できます。
$functionと$accumulator を使用すると、提供されているパイプライン演算子がアプリケーションのニーズを満たせない場合に、ユーザーはJavaScriptでカスタム集計式を定義できます。

使用可能な集計演算子を指定すると、次のようになります。

$exprJavaScriptを使用しない集計演算子（$function 以外と$accumulator 以外の演算子）とともにを使用すると、$where JavaScriptが実行されないためよりも高速であり、可能な場合はこの方法を優先する必要があります。
ただし、カスタム式を作成する必要がある場合は、よりも$function が優先されます$where 。

サポートされていない配列関数と文字列関数

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

例

例1：使用例

下記のドキュメントを含む、players という名前のサンプルコレクションを作成します。

db.players.insertMany([
   { _id: 1, name: "Miss Cheevous",  scores: [ 10, 5, 10 ] },
   { _id: 2, name: "Miss Ann Thrope", scores: [ 10, 10, 10 ] },
   { _id: 3, name: "Mrs. Eppie Delta ", scores: [ 9, 8, 8 ] }
])

下記の集計操作では、 $addFields を使用して各ドキュメントに新しいフィールドを追加します。

isFound この値は、名前の$function MD5 ハッシュが指定されたハッシュと等しいかどうかを確認するカスタム式によって決定されます。
message その値は、テンプレートを使用して string メッセージを形式カスタム$function 式によって決定されます。

db.players.aggregate( [
   { $addFields:
      {
        isFound:
            { $function:
               {
                  body: function(name) {
                     return hex_md5(name) == "15b0a220baa16331e8d80e15367677ad"
                  },
                  args: [ "$name" ],
                  lang: "js"
               }
            },
         message:
            { $function:
               {
                  body: function(name, scores) {
                     let total = Array.sum(scores);
                     return `Hello ${name}.  Your total score is ${total}.`
                  },
                  args: [ "$name", "$scores"],
                  lang: "js"
               }
            }
       }
    }
] )

この操作により、次のドキュメントが返されます。

{ "_id" : 1, "name" : "Miss Cheevous", "scores" : [ 10, 5, 10 ], "isFound" : false, "message" : "Hello Miss Cheevous.  Your total score is 25." }
{ "_id" : 2, "name" : "Miss Ann Thrope", "scores" : [ 10, 10, 10 ], "isFound" : true, "message" : "Hello Miss Ann Thrope.  Your total score is 30." }
{ "_id" : 3, "name" : "Mrs. Eppie Delta ", "scores" : [ 9, 8, 8 ], "isFound" : false, "message" : "Hello Mrs. Eppie Delta .  Your total score is 25." }

Tip

MongoDB 8.3 以降では、$hexHash のネイティブ集計として hex_md5 を使用できます。$hexHash はサーバーサイドJavaScript を必要とせず、MD5 に加えて、SHA-256 アルゴリズムとXXH64 アルゴリズムをサポートしています。$hexHash は大文字の 16進数文字列を返し、hex_md5 は小文字を返すことに注意してください。MD5 はレガシーアルゴリズムであり、 FIPSモードでは無効になっています。

例2：代替案 `$where`

注意

$where よりも優先される集計の代替手段

$expr演算子を使用すると、クエリ言語内で集計を使用できます。また、$function と$accumulator を使用すると、提供されているパイプライン演算子がアプリケーションのニーズを満たせない場合に、ユーザーはJavaScriptでカスタム集計式を定義できます。

使用可能な集計演算子を指定すると、次のようになります。

$exprJavaScriptを使用しない集計演算子（$function 以外と$accumulator 以外の演算子）とともにを使用すると、$where JavaScriptが実行されないためよりも高速であり、可能な場合はこの方法を優先する必要があります。
ただし、カスタム式を作成する必要がある場合は、よりも$function が優先されます$where 。

$where$expr演算子を使用するクエリの代わりに、と$function を使用できます。例については、次の$where の例について考えてみましょう。

db.players.find( { $where: function() {
   return (hex_md5(this.name) == "15b0a220baa16331e8d80e15367677ad")
} } );

db.collection.find() 操作は次のドキュメントを返します。

{ "_id" : 2, "name" : "Miss Ann Thrope", "scores" : [ 10, 10, 10 ] }

この例は$expr と$function を使用して表現できます。

db.players.find( {$expr: { $function: {
      body: function(name) { return hex_md5(name) == "15b0a220baa16331e8d80e15367677ad"; },
      args: [ "$name" ],
      lang: "js"
} } } )

戻る

$floor

$getField