How to Perform $match Aggregation in MongoDB
Introduction
When you perform any type of aggregation functions in MongoDB, it’s important to understand what’s happening behind the scenes. Documents enter a multiple-stage aggregation pipeline and undergo some form of transformation at each stage of the pipeline before they’re passed to the next stage. The $match stage of the pipeline can be used to filter documents so that only ones meeting certain criteria move on to the next stage. In this article, we’ll discuss the $match stage in more detail and provide examples that illustrate how to perform match aggregation in MongoDB.
Prerequisites
Before moving forward with this tutorial, take a moment to confirm that MongoDB is installed on your system. Be sure the server is running in the background. In addition, it’s important to have a basic understanding of MongoDB in order to follow along with the examples in this article.
MongoDB $match aggregation
As we mentioned earlier, the MongoDB $match operator allows us to filter documents that match a defined set of conditions. Only matching documents proceed to the next stage of the pipeline.
Let’s take a look at the basic syntax used for the $match stage:
1 | {$match: {<the_qyery>}} |
There are two key components of this syntax:
- First, we call the $match operator.
- We then specify our query conditions. The ‘the_query’ represents the same type of query that can be used against MongoDB documents.
$match aggregation example
In this section, we’ll look at some examples of how to perform a $match aggregation in MongoDB, but we need to create a sample dataset to work with first.
Creating a MongoDB sample dataset
The following insertMany() command will insert documents into a collection named person:
1 2 3 4 5 6 7 8 | db.person.insertMany([ {"name" : "john", age : 5, "gender" : "male"}, {"name" : "yeshua", age : 8, "gender" : "male"}, {"name" : "abi", age : 3, "gender" : "female"}, {"name" : "andre", age : 12, "gender" : "male"}, {"name" : "raizel", age : 17, "gender" : "female"}, {"name" : "zeek", age : 7, "gender" : "male"}, ]); |
After our insert operation, the ‘person’ collection should look like this:
1 2 3 4 5 6 | { "_id" : ObjectId("5e4ca1562a72b6178e934fab"), "name" : "john", "age" : 5, "gender" : "male" } { "_id" : ObjectId("5e4ca1562a72b6178e934fac"), "name" : "yeshua", "age" : 8, "gender" : "male" } { "_id" : ObjectId("5e4ca1562a72b6178e934fad"), "name" : "abi", "age" : 3, "gender" : "female" } { "_id" : ObjectId("5e4ca1562a72b6178e934fae"), "name" : "andre", "age" : 12, "gender" : "male" } { "_id" : ObjectId("5e4ca1562a72b6178e934faf"), "name" : "raizel", "age" : 17, "gender" : "female" } { "_id" : ObjectId("5e4ca1562a72b6178e934fb0"), "name" : "zeek", "age" : 7, "gender" : "male" } |
$match with count
The example shown below will select documents to be processed by the $match operator. After the $match is performed, the $group operator counts the documents:
1 2 3 4 | db.person.aggregate( [ { $match: { age: { $gt: 5, $lt: 12} } }, { $group: { _id: null, count: { $sum: 1 } } } ] ); |
In this aggregation, the $match operator selects the documents in the ‘person’ collection where the value of age is greater than five and less than 12. The results are then piped to the $group operator where the count is performed.
The output should look like something like the following:
1 | { "_id" : null, "count" : 4 } |
$match with equality match
In this example, we’ll perform a basic equality match using the $match operator. The operator simply looks for documents in the person collection where the value of name is “abi”:
1 2 3 | db.person.aggregate( [ { $match : { name : "abi" } } ] ); |
The output should look like something like this:
1 | { "_id" : ObjectId("5e4ca1562a72b6178e934fad"), "name" : "abi", "age" : 3, "gender" : "female" } |
We can see that the $match operator did indeed find a matching document in the collection.
Conclusion
When an aggregation is performed in MongoDB, documents proceed through an aggregation pipeline made up of multiple stages. In this article, we provided an overview of one of those stages: the $match stage. We explained how match aggregation in MongoDB is used to identify documents that match a particular set of criteria and push them to the next stage of the pipeline, and we looked at some examples of the $match operator in action. With our explanations and examples to guide you, you’ll be prepared to perform $match aggregations on your own MongoDB collections.
Pilot the ObjectRocket Platform Free!
Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.
Get Started