`equals` (Atlas Search Operator)

Definition

equals

The equals operator checks whether a field matches a value you specify. equals supports querying the following data types:

boolean
objectId
number, including int32, int64, and double
date
string, indexed as MongoDB Search token type
uuid
null

You can use the equals operator to query booleans, objectIds, numbers, dates, and strings (indexed as token type) in arrays. If at least one element in the array matches the "value" field in the equals operator, MongoDB Search adds the document to the result set.

Note

The equals operator supports numbers up to 15 decimal digits. Additional decimal digits in documents or queries can cause precision issues or query inaccuracy.

Syntax

equals has the following syntax:

{
   $search: {
      "index": <index name>, // optional, defaults to "default"
      "equals": {
         "path": "<field-to-search>",
         "value": <boolean-value>|<objectId>|<number>|<date>|<string>,
         "score": <score-options>
      }
   }
}

Options

equals uses the following terms to construct a query:

Field	Type	Description	Required?
`path`	string	Indexed field to search.	yes
`value`	boolean, objectId, number, date, string, uuid, or null.	Value to query for.	yes
`score`	object	Score to assign to matching search term results. Use one of the following options to modify the score: `boost`: multiply the result score by the given number. `constant`: replace the result score with the given number. `function`: replace the result score with the given expression. For information on using `score` in your query, see Score the Documents in the Results.	no

Scoring Behavior

By default, equals uses constant scoring. Each matching document receives a score of 1.

When querying array values, MongoDB Search assigns the same score regardless of how many values in the array match the query.

See the Examples section for scoring examples.

Examples

The following examples use a sample users collection.

Sample Collection

The users collection contains the following three documents:

 db.users.insertMany([
  {
    "_id" : ObjectId("5ed698faa1199b471010d70c"),
    "name" : "Jim Hall",
    "verified_user" : true,
    "account" : {
      "new_user" : true,
      "active_user" : true
    },
    "teammates" : [
      ObjectId("5ed6990aa1199b471010d70d"),
      ObjectId("59b99dbdcfa9a34dcd7885c8")
    ],
    "region" : "East",
    "account_created" : ISODate("2021-12-12T10:18:27.000+00:00"),
    "employee_number" : 257,
    "uuid" : UUID("fac32260-b511-4c69-8485-a2be5b7dda9e"),
    "job_title": "engineer"
  },
  {
    "_id" : ObjectId("5ed6990aa1199b471010d70d"),
    "name" : "Ellen Smith",
    "verified_user" : true,
    "account" : {
      "new_user" : false,
      "active_user" : true
    },
    "teammates" : [
      ObjectId("5a9427648b0beebeb69537a5"),
      ObjectId("59b99dbdcfa9a34dcd7881d1")
    ],
    "region" : "Southwest",
    "account_created" : ISODate("2022-05-04T05:01:08.000+00:00"),
    "employee_number" : 258,
    "job_title": null
  },
  {
    "_id" : ObjectId("5ed6994fa1199b471010d70e"),
    "name" : "Fred Osgood",
    "verified_user" : false,
    "account" : {
      "new_user" : false,
      "active_user" : false
    },
    "teammates" : [
      ObjectId("5a9427648b0beebeb69589a1"),
      ObjectId("59b99dbdcfa9a34dcd7897d3")
    ],
    "region" : "Northwest",
    "account_created" : ISODate("2022-01-19T08:22:15.000+00:00"),
    "employee_number" : 259,
    "job_title": null
  }
])

{
   "_id" : ObjectId("5ed698faa1199b471010d70c"),
   "name" : "Jim Hall",
   "verified_user" : true,
   "account" : {
     "new_user" : true,
     "active_user" : true
   },
   "teammates" : [
     ObjectId("5ed6990aa1199b471010d70d"),
     ObjectId("59b99dbdcfa9a34dcd7885c8")
   ],
   "region" : "East",
   "account_created" : ISODate("2021-12-12T10:18:27.000+00:00"),
   "employee_number" : 257,
   "uuid" : UUID("fac32260-b511-4c69-8485-a2be5b7dda9e"),
   "job_title": "engineer"
}

{
   "_id" : ObjectId("5ed6990aa1199b471010d70d"),
   "name" : "Ellen Smith",
   "verified_user" : true,
   "account" : {
     "new_user" : false,
     "active_user" : true
   },
   "teammates" : [
     ObjectId("5a9427648b0beebeb69537a5"),
     ObjectId("59b99dbdcfa9a34dcd7881d1")
   ],
   "region" : "Southwest",
   "account_created" : ISODate("2022-05-04T05:01:08.000+00:00"),
   "employee_number" : 258,
   "job_title": null
}

{
   "_id" : ObjectId("5ed6994fa1199b471010d70e"),
   "name" : "Fred Osgood",
   "verified_user" : false,
   "account" : {
     "new_user" : false,
     "active_user" : false
   },
   "teammates" : [
     ObjectId("5a9427648b0beebeb69589a1"),
     ObjectId("59b99dbdcfa9a34dcd7897d3")
   ],
   "region" : "Northwest",
   "account_created" : ISODate("2022-01-19T08:22:15.000+00:00"),
   "employee_number" : 259,
   "job_title": null
}

Sample Index

The users collection is indexed with the following index definition:

{
  "mappings": {
    "dynamic": true,
    "fields": {
      "name": {
        "type": "token",
        "normalizer": "lowercase"
      },
      "region": [
       {
         "type": "string"
       },
       {
         "type": "token"
       }
      ]
    }
  }
}

The index definition specifies the following:

Automatically index all dynamically indexable fields.
Index the name field as type token to support string search using the equals operator.
Index the region field as types string to support string search and token to support facet search.

To learn how to create a MongoDB Search index, see Manage MongoDB Search Indexes.

Basic Example Queries

Boolean Examples

The following example uses the equals operator to search the users collection for documents in which the verified_user field is set to true.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "verified_user",
        "value": true
      }
    }
  },
  {
    "$project": {
      "name": 1,
      "_id": 0,
      "score": { "$meta": "searchScore" }
    }
  }
])

The above query returns the following results:

{ "name" : "Jim Hall", "score" : 1 }
{ "name" : "Ellen Smith", "score" : 1 }

The documents for "Jim Hall" and "Ellen Smith" each receive a score of 1 because those documents have the verified_user field set to true.

The following example uses the equals operator to search the users collection for documents in which the account.new_user field contains the boolean value true.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "account.new_user",
        "value": true
      }
    }
  }
])

The preceding query returns the document for "Jim Hall" because that document contains "new_user": true in the account object.

ObjectId Example

The following example uses the equals operator to search the users collection for documents in which the teammates field contains the value ObjectId("5a9427648b0beebeb69589a1").

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "teammates",
        "value": ObjectId("5a9427648b0beebeb69589a1")
      }
    }
  }
])

The preceding query returns the document for "Fred Osgood" because that document contains ObjectId("5a9427648b0beebeb69589a1") in the teammates array.

Date Example

The following example uses the equals operator to search the users collection for documents in which the account_created field contains the value that matches ISODate("2022-05-04T05:01:08.000+00:00").

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "account_created",
        "value": ISODate("2022-05-04T05:01:08.000+00:00")
      }
    }
  }
])

The preceding query returns the document for "Ellen Smith" because that document contains "account_created": 2022-05-04T05:01:08.000+00:00.

Number Example

The following example uses the equals operator to search the users collection for documents in which the employee_number field contains the value that matches 259.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "employee_number",
        "value": 259
      }
    }
  }
])

The preceding query returns the document for "Fred Osgood" because that document contains "employee_number": 259.

String Example

The following example uses the equals operator to search the users collection for documents in which the name field contains the value that matches Jim Hall.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "name",
        "value": "jim hall"
      }
    }
  }
])

The preceding query returns the document for "Jim Hall" because that document contains Jim Hall in the name field. MongoDB Search matches the lowercase query to the uppercase value in the document because it normalizes the term to lowercase as specified in the index definition for the name field.

UUID Example

The following example uses the equals operator to search the users collection for documents in which the uuid field contains the value that matches a specific UUID.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "uuid",
        "value": UUID("fac32260-b511-4c69-8485-a2be5b7dda9e")
      }
    }
  }
])

The preceding query returns the document for "Jim Hall" because that document contains the specified UUID in the uuid field.

Null Example

The following example uses the equals operator to search the users collection for documents in which the job_title field contains the null value.

db.users.aggregate([
  {
    $search: {
      "equals": {
        "path": "job_title",
        "value": null
      }
    }
  }
])

The preceding query returns the documents for "Ellen Smith" and Fred Osgood because that documents contain the null value in the job_title field.

Compound Example Queries

The following example uses the compound operator in conjunction with must, mustNot, and equals to search for documents in which the region field is Southwest and the verified_user field is not false.

db.users.aggregate([
  {
    "$search": {
      "compound": {
        "must": {
          "text": {
            "path": "region",
            "query": "Southwest"
          }
        },
        "mustNot": {
          "equals": {
            "path": "verified_user",
            "value": false
          }
        }
      }
    }
  }
])

The above query returns the document for "Ellen Smith", which is the only one in the collection which meets the search criteria.

The following example query has these search criteria:

The verified_user field must be set to true
One of the following must be true:
- The teammates array contains the value ObjectId("5ed6990aa1199b471010d70d")
- The region field is set to Northwest

db.users.aggregate([
  {
    "$search": {
      "compound": {
        "must": {
          "equals": {
            "path": "verified_user",
            "value": true
          }
        },
        "should": [
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("5ed6990aa1199b471010d70d")
            }
          },
          {
            "text": {
              "path": "region",
              "query": "Northwest"
            }
          }
        ],
        "minimumShouldMatch": 1
        }
      }
    },
    {
      "$project": {
        "name": 1,
        "_id": 0,
        "score": { "$meta": "searchScore" }
      }
    }
])

The above query returns the following results:

{ "name" : "Jim Hall", "score" : 2 }

The document for "Jim Hall" receives a score of 2 because it meets the requirements for the must clause and the first of the two should clauses.

You can search for multiple ObjectIDs with a compound query. The following example query uses the compound operator with a should clause to search for three different ObjectIDs, at least two of which must appear to satisfy the query.

db.users.aggregate([
  {
    "$search": {
      "compound": {
        "should": [
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("5a9427648b0beebeb69537a5")
            }
          },
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("59b99dbdcfa9a34dcd7881d1")
            }
          },
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("5a9427648b0beebeb69579d0")
            }
          }
        ],
        "minimumShouldMatch": 2
        }
      }
    },
    {
      "$project": {
        "name": 1,
        "_id": 0,
        "score": { "$meta": "searchScore" }
      }
    }
])

The above query returns the following results:

{ "name" : "Ellen Smith", "score" : 2 }

The document for "Ellen Smith" receives a score of 2 because it contains two of the specified ObjectIDs in its teammates array.

Metadata Examples

The following query uses the $searchMeta stage to retrieve the number of regions in which verified_users is true in the users collection.

db.users.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "equals": {
            "path": "verified_user",
            "value": true
          }
        },
        "facets": {
          "regionFacet": {
            "type": "string",
            "path": "region"
          }
        }
      }
    }
  }
])

[
  {
    count: { lowerBound: Long('2') },
    facet: {
      regionFacet: {
        buckets: [
          { _id: 'East', count: Long('1') },
          { _id: 'Southwest', count: Long('1') }
        ]
      }
    }
  }
]

The following query uses the $$SEARCH_META aggregation variable to return both the metadata and search results for a search to retrieve the number of regions in which verified_users is true in the users collection.

db.users.aggregate([
  {
    "$search": {
      "facet": {
        "operator": {
          "equals": {
            "path": "verified_user",
            "value": true
          }
        },
        "facets": {
          "regionFacet": {
            "type": "string",
            "path": "region"
          }
        }
      }
    }
  },
  { "$limit": 2 },
  {
    "$facet": {
      "docs": [
        { "$project":
          {
            "type": 1,
            "description": 1
          }
        }
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  },
  {
    "$set": {
      "meta": {
        "$arrayElemAt": ["$meta", 0]
      }
    }
  }
])

[
  {
    docs: [
      {
        _id: ObjectId('5ed698faa1199b471010d70c'),
        name: 'Jim Hall',
        region: 'East'
      },
      {
        _id: ObjectId('5ed6990aa1199b471010d70d'),
        name: 'Ellen Smith',
        region: 'Southwest'
      }
    ],
    meta: {
      count: { lowerBound: Long('2') },
      facet: {
        regionFacet: {
          buckets: [
            { _id: 'East', count: Long('1') },
            { _id: 'Southwest', count: Long('1') }
          ]
        }
      }
    }
  }
]

Back

embedded-document

exists