Docs Home → MongoDB Manual

$where

On this page

Definition定义

$where

Use the $where operator to pass either a string containing a JavaScript expression or a full JavaScript function to the query system. 使用$where运算符将包含JavaScript表达式的字符串或完整的JavaScript函数传递给查询系统。The $where provides greater flexibility, but requires that the database processes the JavaScript expression or function for each document in the collection. $where提供了更大的灵活性，但要求数据库处理集合中每个文档的JavaScript表达式或函数。Reference the document in the JavaScript expression or function using either this or obj .使用this或obj引用JavaScript表达式或函数中的文档。

{ $where: <string|JavaScript Code> }
Note

Starting in MongoDB 4.4, $where no longer supports the deprecated BSON type JavaScript code with scope (BSON Type 15). 从MongoDB 4.4开始，$where不再支持已弃用的带有作用域的BSON类型JavaScript代码（BSON type 15）。The $where operator only supports BSON type String (BSON Type 2) or BSON type JavaScript (BSON Type 13). $where运算符仅支持BSON类型的String(BSON type 2)或BSON类型JavaScript（BSON类型13）。The use of BSON type JavaScript with scope for $where has been deprecated since MongoDB 4.2.1.自MongoDB 4.2.1以来，范围为$where的BSON类型JavaScript的使用一直被弃用。

Note

Aggregation Alternatives Preferred首选聚合备选方案

The $expr operator allows the use of aggregation expressions within the query language. $expr运算符允许在查询语言中使用聚合表达式。And, starting in MongoDB 4.4, the $function and $accumulator allows users to define custom aggregation expressions in JavaScript if the provided pipeline operators cannot fulfill your application's needs.而且，从MongoDB 4.4开始，如果提供的管道运算符无法满足应用程序的需求，那么$function和$accumulator允许用户在JavaScript中定义自定义聚合表达式。

Given the available aggregation operators:给定可用的聚合运算符：

  • The use of $expr with aggregation operators that do not use JavaScript (i.e. non-$function and non-$accumulator operators) is faster than $where because it does not execute JavaScript and should be preferred if possible.$expr与不使用JavaScript的聚合运算符（即非$function和非$accumulator运算符）一起使用比$where更快，因为它不执行JavaScript，如果可能的话应该是首选。

  • However, if you must create custom expressions, $function is preferred over $where.但是，若必须创建自定义表达式，则首选$function而不是$where。

Behavior行为

Available JavaScript Properties and Functions可用的JavaScript属性和函数

map-reduce operations and $where operator expressions cannot access certain global functions or properties, such as db, that are available in mongosh.map-reduce操作和$where运算符表达式无法访问mongosh中可用的某些全局函数或属性，如db。

The following JavaScript functions and properties are available to map-reduce operations and $where operator expressions:以下JavaScript函数和属性可用于map-reduce操作和$where运算符表达式：

Available Properties可用属性Available Functions可用函数
args
MaxKey
MinKey		assert()
BinData()
DBPointer()
DBRef()
doassert()
emit()
gc()
HexData()
hex_md5()
isNumber()
isObject()
ISODate()
isString()		Map()
MD5()
NumberInt()
NumberLong()
ObjectId()
print()
printjson()
printjsononeline()
sleep()
Timestamp()
tojson()
tojsononeline()
tojsonObject()
UUID()
version()

elemMatch

Only apply the $where query operator to top-level documents. 仅将$where查询运算符应用于顶级文档。The $where query operator will not work inside a nested document, for instance, in an $elemMatch query.$where查询运算符在嵌套文档中不起作用，例如在$elemMatch查询中。

Considerations注意事项

  • Do not use global variables.不要使用全局变量。

  • $where evaluates JavaScript and cannot take advantage of indexes. 评估JavaScript，不能利用索引。Therefore, query performance improves when you express your query using the standard MongoDB operators (e.g., $gt, $in).因此，当您使用标准MongoDB运算符（例如$gt、$in）表达查询时，查询性能会得到提高。

  • In general, you should use $where only when you cannot express your query using another operator. 通常，只有在无法使用其他运算符表达查询时，才应使用$where。If you must use $where, try to include at least one other standard query operator to filter the result set. 如果必须使用$where，请尝试至少包含一个其他标准查询运算符来筛选结果集。Using $where alone requires a collection scan.单独使用$where需要进行集合扫描。

Using normal non-$where query statements provides the following performance advantages:使用普通的非$where查询语句可以提供以下性能优势：

  • MongoDB will evaluate non-$where components of query before $where statements. MongoDB将在$where语句之前评估查询的非$where组件。If the non-$where statements match no documents, MongoDB will not perform any query evaluation using $where.如果非$where语句不匹配任何文档，MongoDB将不会使用$where执行任何查询评估。

  • The non-$where query statements may use an index.非$where查询语句可以使用索引。

JavaScript EnablementJavaScript启用

To use $where (or $function, $accumulator, or mapReduce), you must have server-side scripting enabled (default).要使用$where（或$function、$accumulator或mapReduce），必须启用服务器端脚本（默认）。

However, if you do not use these operations, disable server-side scripting:但是，如果不使用这些操作，请禁用服务器端脚本：

See also ➤ Run MongoDB with Secure Configuration Options.参阅➤ 使用安全配置选项运行MongoDB。

Unsupported Array and String Functions不支持的数组和字符串函数

MongoDB 6.0 upgrades the internal JavaScript engine used for server-side JavaScript, $accumulator, $function, and $where expressions and from MozJS-60 to MozJS-91. MongoDB 6.0升级了用于服务器端JavaScript、$accumulator、$function和$where表达式的内部JavaScript引擎，并从MozJS-60升级到MozJS-91。Several deprecated, non-standard array and string functions that existed in MozJS-60 are removed in MozJS-91.MozJS-60中存在的一些不推荐使用的非标准数组和字符串函数在MozJS-91中被删除。

For the complete list of removed array and string functions, see the 6.0 compatibility notes.有关已删除的数组和字符串函数的完整列表，请参阅6.0兼容性说明。

Example实例

Consider the following documents in the players collection:请考虑players集合中的以下文档：

db.players.insertMany([
   { _id: 12378, name: "Steve", username: "steveisawesome", first_login: "2017-01-01" },
   { _id: 2, name: "Anya", username: "anya", first_login: "2001-02-02" }
])

The following example uses $where and the hex_md5() JavaScript function to compare the value of the name field to an MD5 hash and returns any matching document.以下示例使用$where和hex_md5()JavaScript函数将name字段的值与md5哈希进行比较，并返回任何匹配的文档。

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

The operation returns the following result:该操作返回以下结果：

{
   "_id" : 2,
   "name" : "Anya",
   "username" : "anya",
   "first_login" : "2001-02-02"
}

As an alternative, the previous example can be rewritten using $expr and $function. 作为替代方案，可以使用$expr和$function重写前面的示例。Starting in MongoDB 4.4, you can define custom aggregation expression in JavaScript with the aggregation operator $function. 从MongoDB 4.4开始，您可以使用聚合运算符$function在JavaScript中定义自定义聚合表达式。To access $function and other aggregation operators in db.collection.find(), use with $expr:要访问db.collection.find()中的$function和其他聚合运算符，请与$expr一起使用：

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

If you must create custom expressions, $function is preferred over $where.如果必须创建自定义表达式，则首选$function而不是$where。