Navigation

search (Operator)

On this page

Definition

search

The search operator performs a full-text search using the analyzer specified in the index configuration. If no search analyzer is specified, the default standard analyzer is used.

search has the following syntax:

{
  $searchBeta: {
    "index": <index name>, // optional, defaults to "default"
    "search": {
      "query": "<search-string>",
      "path": "<field-to-search>",
      "phrase": <options>
    }
  }
}
Field Type Description Required? Default
query string or array of strings The string or strings to search for. yes  
path string or array of strings The indexed field or fields to search. See path construction for more information. yes  
phrase object

Match documents containing an ordered sequence of terms. An empty object ({}) indicates that the default options should be used. Options are:

  • slop: the allowable distance within which words may be considered a phrase. The default is 0, meaning that words must be adjacent to be considered a phrase. See examples.
  • prefix: a boolean which indicates whether or not to treat the final word of the phrase as a prefix search. The default is false. See example.
no empty

Examples

The following examples use a collection called fruit that contains the following documents:

{
  "_id" : 1,
  "type" : "apple",
  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp."
},
{
  "_id" : 2,
  "type" : "banana",
  "description" : "Bananas are usually sold in bunches of five or six."
}

The fruit collection has a Full Text Search index on the description field that uses the standard analyzer. The standard analyzer lower-cases all words and disregards common stop words ("the", "a", "and", etc).

Basic Example

The following Full Text Search example performs a basic search of the description field for the query string several, using the $searchBeta aggregation pipeline stage and the search operator.

db.fruit.aggregate([
  {
    $searchBeta: {
      "search": {
        "query": "several",
        "path": "description"
      }
    }
  }
])

The above query returns the document with _id: 1, which has the word several in the description field.

Array Example

You can search for multiple strings with an array value for the query parameter. If any of the strings in the array match a document, that document is returned.

The following example searches for documents with the strings several, bunches, and/or oranges in the description field:

db.fruit.aggregate([
  {
    $searchBeta: {
      "search": {
        "query": ["several", "bunches", "oranges"],
        "path": "description"
      }
    }
  }
])

The above query returns both of the documents in the collection because the first document has the word several in the description field and the second document has the word bunches in the description field.

Phrase Examples

Phrase Example with Default Options

The following query performs a phrase search. Phrase searches match on ordered sequences of words, with a degree of precision specified by the slop option.

In following example, the phrase parameter has an empty object as its value, so MongoDB uses the default values { "slop": 0, "prefix": false }.

db.fruit.aggregate([
  {
    $searchBeta: {
      "search": {
        "query": "sold in bunches",
        "path": "description",
        "phrase": {}
      }
    }
  }
])

The above query returns the document with _id: 2.

Phrase Example with Higher Precision

You can set the slop option to a higher or lower integer to adjust the required precision of the phrase match. A higher value matches on documents in which the words in the phrase may be farther apart, while a value of 0 requires an exact match.

db.fruit.aggregate([
  {
    $searchBeta: {
      "search": {
        "query": "Bananas in bunches",
        "path": "description",
        "phrase": { "slop": 1 }
      }
    }
  }
])

The above phrase search returns no results. The document with _id: 2 contains all the words in the query parameter in its description field, but there are three words separating Bananas from in bunches and the slop parameter is set to 1.

Setting the prefix option to true performs a wildcard search based on the words in the query parameter.

db.fruit.aggregate([
  {
    $searchBeta: {
      "search": {
        "query": "several var",
        "path": "description",
        "phrase": { "prefix": true }
      }
    }
  }
])

The above query returns the document with _id: 1, because the description field contains the phrase several varieties and the prefix parameter is set to true.