> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # $match (aggregation stage) ## Definition Filters documents based on a specified [query predicate](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-query-predicate). Matched documents are passed to the next pipeline stage. ## Compatibility You can use `$match` 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 ```javascript { $match: { } } ``` The syntax for the `$match` query predicate is identical to the syntax used in the [query](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#std-label-method-find-query) argument of a [`find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) command. ## Behavior ### Pipeline Optimization - Place the [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) as early in the aggregation [pipeline](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-pipeline) as possible. Because [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) limits the total number of documents in the aggregation pipeline, earlier [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) operations minimize the amount of processing down the pipe. - If you place a [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) at the very beginning of a pipeline, the query can take advantage of [indexes](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-collflag-index) like any other [`db.collection.find()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.find.md#mongodb-method-db.collection.find) or [`db.collection.findOne()`.](https://www.mongodb.com/docs/manual/reference/method/db.collection.findone.md#mongodb-method-db.collection.findOne) ### Expressions in Query Predicates To include [expressions](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) in a query predicate, use the [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) operator. ### 0, Null, False or Missing Values A `$match` stage filters out a document from pipeline results if one of the following conditions applies: - The `$match` query predicate returns a `0`, `null`, or `false` value on that document. - The `$match` query predicate uses a field that is missing from that document. ### Restrictions - You cannot use [`$where`](https://www.mongodb.com/docs/manual/reference/operator/query/where.md#mongodb-query-op.-where) in a `$match` stage. - You cannot use [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near) or [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) in a `$match` stage. As an alternative, you can either: - Use the [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) stage instead of the [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage. - Use the [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) query predicate operator with [`$center`](https://www.mongodb.com/docs/manual/reference/operator/query/center.md#mongodb-query-op.-center) or [`$centerSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/centersphere.md#mongodb-query-op.-centerSphere) in the [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage. - To use [`$text`](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#mongodb-query-op.-text) in a [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage, the [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage has to be the first stage of the pipeline. [Views](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) do not support `$text`. **Note:** `$text` provides text query capabilities for self-managed (non-Atlas) deployments. For data hosted on MongoDB, MongoDB also offers an improved full-text query solution, [MongoDB Search.](https://www.mongodb.com/docs/atlas/atlas-search/) ### Filter Data on Atlas by Using MongoDB Search For data stored in [MongoDB Atlas](https://www.mongodb.com/docs/atlas/), you can use the [MongoDB Search](https://www.mongodb.com/docs/atlas/atlas-search/) [compound Operator](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref) operator `filter` option to match or filter documents when running [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) queries. Running [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) after [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) is less performant than running [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search) with the [compound Operator](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref) operator `filter` option. To learn more about the `filter` option, see [compound Operator](https://www.mongodb.com/docs/search/query/operators-collectors/compound.md#std-label-compound-ref) in the Atlas documentation. ## Examples ### MongoDB Shell The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page. ### Equality Match The following operation uses [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) to perform an equality match on the `rated` field. The `runtime` filter limits the result to a small, representative set: ```javascript db.movies.aggregate( [ { $match : { rated : "TV-PG", runtime : { $gt: 1000 } } } ] ) ``` The [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) selects the documents where the `rated` field equals `"TV-PG"` and `runtime` is greater than `1000`. ### Perform a Count The following example selects documents to process using the [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) pipeline operator and then pipes the results to the [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) pipeline operator to compute a count of the documents: ```javascript db.movies.aggregate( [ { $match: { $or: [ { runtime: { $gt: 1000 } }, { year: { $lt: 1910 } } ] } }, { $group: { _id: null, count: { $sum: 1 } } } ] ) ``` **Output:** ```javascript [ { _id: null, count: 6 } ] ``` In the aggregation pipeline, [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) selects the documents where either the `runtime` is greater than `1000` or the `year` is earlier than `1910`. These documents are then sent to the [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) to perform a count. ### Match Array Elements To filter documents based on elements in an array field, use the [`$elemMatch`](https://www.mongodb.com/docs/manual/reference/operator/query/elemmatch.md#mongodb-query-op.-elemMatch) operator in the query predicate of the `$match` stage: ```javascript db.aggregate( [ { $documents: [ { student_id: 1, scores: [ 0.75, 0.65, 0.73 ] }, { student_id: 2, scores: [ 0.9, 0.88, 0.98 ] }, { student_id: 3, scores: [ 0.9, 0.84, 0.93 ] } ] }, { $match: { scores: { $elemMatch: { $gte: 0.9 } } } } ] ) ``` **Output:** ```javascript [ { student_id: 2, scores: [ 0.9, 0.88, 0.98 ] }, { student_id: 3, scores: [ 0.9, 0.84, 0.93 ] } ] ``` ## Learn More Refer to the [Complete Aggregation Pipeline Tutorials](https://www.mongodb.com/docs/manual/tutorial/aggregation-complete-examples.md#std-label-aggregation-complete-examples) for more information and use cases on aggregation.