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>,
      "score": <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. May be used in conjuncion with the maxExpansions option. See example.

  • maxExpansions: a number which indicates the maximum number of expansions a phrase may expand to. Defaults to 50, with a maximum value of 1000. Must be used in conjunction with the prefix option.

    If the number of terms in a phrase: { prefix: true } } match exceeds maxExpansions, your query may not return all matching results. This may be avoided by setting maxExpansions to a higher value, up to 1000. If there are more than 1000 matching terms, your query is not guaranteed to match all results.

    Note

    Increasing the value of maxExpansions may cause your query to consume more memory and performance may decrease.

no empty
score object

Modify the score assigned to matching search term results. Options are:

  • boost: multiply the result score by the given number.
  • constant: replace the result score with the given number.
no  

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.