> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $where (query predicate operator)

## Definition

Use the [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) operator to pass either a string containing a JavaScript expression or a full JavaScript function to the query system. The [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) provides greater flexibility, but requires that the database processes the JavaScript expression or function for *each* document in the collection. Reference the document in the JavaScript expression or function using either `this` or `obj` .

## Compatibility

You can use `$where` for deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

* [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

* [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

The [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) operator has the following form:

```javascript
{ $where: <string|JavaScript Code> }
```

**Note:**

[`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) no longer supports the deprecated [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) JavaScript code with scope (BSON Type 15). The [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) operator only supports BSON type String (BSON Type 2) or BSON type JavaScript (BSON Type 13). The use of BSON type JavaScript with scope for [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) has been deprecated since MongoDB 4.2.1.

**Note: Aggregation Alternatives Preferred**

The [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) operator allows the use of [aggregation expressions](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) within the query language. The [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function) and [`$accumulator`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator.md#mongodb-group-grp.-accumulator) allows users to define custom aggregation expressions in JavaScript if the provided [pipeline operators](https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md#std-label-aggregation-pipeline-operator-reference) cannot fulfill your application's needs.

Given the available aggregation operators:

- The use of [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) with aggregation operators that do not use JavaScript (i.e. non-[`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function) and non-[`$accumulator`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator.md#mongodb-group-grp.-accumulator) operators) is faster than [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) because it does not execute JavaScript and should be preferred if possible.

- However, if you must create custom expressions, [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function) is preferred over [`$where`.](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where)

## Behavior

### Available JavaScript Properties and Functions

[`map-reduce operations`](https://www.mongodb.com/docs/manual/reference/command/mapreduce.md#mongodb-dbcommand-dbcmd.mapReduce) and [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) operator expressions **cannot** access certain global functions or properties, such as `db`, that are available in [`mongosh`.](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

The following JavaScript functions and properties **are available** to [`map-reduce operations`](https://www.mongodb.com/docs/manual/reference/command/mapreduce.md#mongodb-dbcommand-dbcmd.mapReduce) and [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) operator expressions:

| 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`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) query operator to top-level documents. The [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) query operator will not work inside a nested document, for instance, in an [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) query.

### Considerations

- Do not use global variables.

- [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) evaluates JavaScript and cannot take advantage of indexes. Therefore, query performance improves when you express your query using the standard MongoDB operators (e.g., [`$gt`](https://www.mongodb.com/docs/manual/reference/operator/query/gt.md#mongodb-query-op.-gt), [`$in`](https://www.mongodb.com/docs/manual/reference/operator/query/in.md#mongodb-query-op.-in)).

- In general, you should use [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) only when you cannot express your query using another operator. If you must use [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where), try to include at least one other standard query operator to filter the result set. Using [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) alone requires a collection scan.

Using normal non-[`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) query statements provides the following performance advantages:

- MongoDB will evaluate non-[`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) components of query before [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) statements. If the non-[`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) statements match no documents, MongoDB will not perform any query evaluation using [`$where`.](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where)

- The non-[`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) query statements may use an [index.](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-collflag-index)

### JavaScript Enablement

To use [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) (or [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function), [`$accumulator`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator.md#mongodb-group-grp.-accumulator), or [`mapReduce`](https://www.mongodb.com/docs/manual/reference/command/mapreduce.md#mongodb-dbcommand-dbcmd.mapReduce)), you must have server-side scripting enabled (default).

However, if you do not use these operations, disable server-side scripting:

- For a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance, see [`security.javascriptEnabled`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-security.javascriptEnabled) configuration option or [`--noscripting`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--noscripting) command-line option.

- For a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance, see [`security.javascriptEnabled`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-security.javascriptEnabled) configuration option or the [`--noscripting`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#std-option-mongos.--noscripting) command-line option.

See also [➤ Run MongoDB with Secure Configuration Options.](https://www.mongodb.com/docs/manual/administration/security-checklist.md#std-label-security-checklist-javascript)

### Unsupported Array and String Functions

MongoDB 6.0 upgrades the internal JavaScript engine used for [server-side JavaScript](https://www.mongodb.com/docs/manual/core/server-side-javascript.md#std-label-server-side-javascript), [`$accumulator`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator.md#mongodb-group-grp.-accumulator), [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function), and [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) expressions and from MozJS-60 to MozJS-91. Several deprecated, non-standard array and string functions that existed in MozJS-60 are removed in MozJS-91.

## Example

Consider the following documents in the `players` collection:

```javascript
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`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) and the `hex_md5()` JavaScript function to compare the value of the `name` field to an MD5 hash and returns any matching document.

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

The operation returns the following result:

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

As an alternative, the previous example can be rewritten using [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) and [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function). You can define custom aggregation expression in JavaScript with the aggregation operator [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function). To access [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function) and other aggregation operators in [`db.collection.find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find), use with [`$expr`:](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr)

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

If you must create custom expressions, [`$function`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/function.md#mongodb-expression-exp.-function) is preferred over [`$where`.](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where)