phrase (MongoDB Search Operator)

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

phrase (MongoDB Search Operator)

Definition

The phrase operator performs search for documents containing an ordered sequence of terms using the [analyzer](https://www.mongodb.com/docs/search/indexes/analyzers/overview.md#std-label-analyzers-ref specified in the [index configuration](https://www.mongodb.com/docs/search/indexes/define-field-mappings.md#std-label-index-config-example. If no analyzer is specified, the default [standard](https://www.mongodb.com/docs/search/indexes/analyzers/standard.md#std-label-ref-standard-analyzer analyzer is used.

You can use the phrase operator to search for exact matches to multi-word phrases.

Syntax

phrase has the following syntax:

{
  $search: {
     "index": <index name>, // optional, defaults to "default"
     "phrase": {
       "query": "<search-string>",
       "path": "<field-to-search>",
       "score": <options>,
       "slop": <distance-number>,
       "synonyms": "<synonyms-mapping-name>"
     }
  }
}

Options

phrase uses the following terms to construct a query:

Scoring Behavior

By default, the [text](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref operator uses the bm25 similarity algorithm to score documents depending on their relevance to the query.

You can change which similarity algorithm is used by specifying a different similarity algorithm in the similarity.type property for the string fields in your MongoDB Search index definition. To learn how to configure a MongoDB Search index for the string type, see [How to Index String Fields](https://www.mongodb.com/docs/search/indexes/field-types/string-type.md#std-label-bson-data-types-string.

To learn more about the supported similarity algorithms, see [Score Details.](https://www.mongodb.com/docs/search/query/score/get-details.md#std-label-fts-similarity-algorithms

Examples

The examples in this page use the movies collection in the sample_mflix database. After loading the [sample dataset](https://www.mongodb.com/docs/manual/sample-data.md#std-label-available-sample-datasets into your cluster, create the MongoDB Search index with dynamic mappings and run the example queries on your cluster. To try the [synonyms](https://www.mongodb.com/docs/search/query/operators-collectors/text.md#std-label-text-ref-synonyms-eg examples, you must also add the [synonymous_terms collection](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-sample-synonyms-coll to the sample_mflix database and then [define the index](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-synonyms-index-definition-ex with the synonyms mapping collection.

Single Phrase Example

The following MongoDB Search example performs a basic search of the title field for the query string new york. There is no slop in the query and so the slop value defaults to 0, which means the title field must contain the exact query string with all the words in the the same position to be included in the results. The query also includes a:

• [$limit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit stage to limit the output to 10 results.

• [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project stage to exclude all fields except title and add a field named score.

Basic Example

The following query returns the documents that match the search criteria.

db.movies.aggregate([
  {
    "$search": {
      "phrase": {
        "path": "title",
        "query": "new york"
      }
    }
  },
  { $limit: 10 },
  {
    $project: {
      "_id": 0,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Output:

[
  { title: 'New York, New York', score: 6.786321640014648 }
  { title: 'New York', score: 6.258549213409424 }
  { title: 'New York Stories', score: 5.3813982009887695 }
  { title: 'New York Minute', score: 5.3813982009887695 }
  { title: 'Synecdoche, New York', score: 5.3813982009887695 }
  { title: 'New York Doll', score: 5.3813982009887695 }
  { title: 'Little New York', score: 5.3813982009887695 }
  { title: 'Escape from New York', score: 4.719893455505371 }
  { title: 'Naked in New York', score: 4.719893455505371 }
  { title: 'Autumn in New York', score: 4.719893455505371 }
]

Metadata Example

The following query returns the metadata results for the search criteria. It uses the [$searchMeta](https://www.mongodb.com/docs/search/query/aggregation-stages/searchmeta.md#mongodb-pipeline-pipe.-searchMeta stage to get the number of movies in the following buckets (years) that match the search criteria:

• 2000, inclusive lower bound for this bucket

• 2005, exclusive upper bound for the 2000 bucket and inclusive lower bound for this bucket

• 2010, exclusive upper bound for the 2005 bucket and inclusive lower bound for this bucket

• 2010, exclusive upper bound for the 2010 bucket

Example:

db.movies.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "phrase": {
            "path": "title",
            "query": "new york"
          }
        },
        "facets": {
          "yearFacet": {
            "type": "number",
            "path": "year",
            "boundaries": [2000, 2005, 2010, 2015 ]
          }
        }
      }
    }
  }
])

Output:

[
  {
    count: { lowerBound: Long('27') },
    facet: {
      yearFacet: {
        buckets: [
          { _id: 2000, count: Long('3') },
          { _id: 2005, count: Long('8') },
          { _id: 2010, count: Long('4') }
        ]
      }
    }
  }
]

The results show that there are 3 movies between 2000 and 2005, 8 movies between 2005 and 2010, and 4 movies between 2010 and 2015 that contain the term new york in the title.

Multiple Phrases Example

The following MongoDB Search example performs a search of the title field for the query strings the man and the moon. There is no slop in the query and so the slop value defaults to 0, which means the title must contain the exact query string with all the words in the same position to be included in the results. The query also includes a:

• [$limit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit.md#mongodb-pipeline-pipe.-limit stage to limit the output to 10.

• [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project stage to exclude all fields except title and add a field named score.

db.movies.aggregate([
  {
    "$search": {
      "phrase": {
        "path": "title",
        "query": ["the man", "the moon"]
      }
    }
  },
  { $limit: 10 },
  {
    $project: {
      "_id": 0,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Output:

[
  { title: 'The Man in the Moon', score: 4.4830474853515625 },
  { title: 'Shoot the Moon', score: 3.252699851989746 },
  { title: 'Kick the Moon', score: 3.252699851989746 },
  { title: 'The Man', score: 2.8923356533050537 },
  { title: 'The Moon and Sixpence', score: 2.8528637886047363 },
  { title: 'The Moon Is Blue', score: 2.8528637886047363 },
  { title: 'Racing with the Moon', score: 2.8528637886047363 },
  { title: 'Mountains of the Moon', score: 2.8528637886047363 },
  { title: 'Man on the Moon', score: 2.8528637886047363 },
  { title: 'Castaway on the Moon', score: 2.8528637886047363 }
]

Slop Example

The following MongoDB Search example performs a search of the title field for the query string men women. The slop value of 5 in the query allows greater movement of the words and distance between the words men and women. The query includes a [$project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project stage to:

• Exclude all fields except title

• Add a field named score

db.movies.aggregate([
  {
    "$search": {
      "phrase": {
        "path": "title",
        "query": "men women",
        "slop": 5
      }
    }
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Output:

[
  { title: 'Men Without Women', score: 3.367523193359375 },
  { title: 'Men Vs Women', score: 3.367523193359375 },
  { title: 'Good Men, Good Women', score: 2.8529787063598633 },
  { title: 'The War Between Men and Women', score: 2.1851978302001953 },
  { title: 'Women Without Men', score: 1.9656763076782227 },
  { title: 'Women Vs Men', score: 1.9656763076782227 }
]

Synonyms Example

The following queries search the plot field in the movies collection for the terms in the given query string. MongoDB Search returns results based on the [type of mapping](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-synonyms-ref in the [synonym source collection](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-synonyms-coll-spec, synonymous_terms, specified in the synonym mapping definition of the index for the sample_mflix.movies collection.

The following query searches for the phrase automobile race anywhere in the plot field with a distance of up to 5 between the terms.

db.movies.aggregate([
  {
    $search: {
      "phrase": {
        "path": "plot",
        "query": "automobile race",
        "slop": 5,
        "synonyms": "my_synonyms"
      }
    }
  },
  {
    "$limit": 5
  },
  {
    $project: {
      "_id": 0,
      "plot": 1,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Output:

[
  {
    plot: 'When a popular daredevil proposes an automobile race across three continents, his arch rival vows to beat him, while an ambitious female reporter has her own plans for victory.',
    title: 'The Great Race',
    score: 29.569732666015625
  },
  {
    plot: 'A wide variety of eccentric competitors participate in a wild and illegal cross-country car race.',
    title: 'The Cannonball Run',
    score: 25.50379180908203
  },
  {
    plot: 'A mechanic takes his family to a car race and a series of events occur which brings problems, betrayals, violence and the unexpected death of an elderly person.',
    title: 'National Mechanics',
    score: 21.538257598876953
  },
  {
    plot: "It's time for the annual London to Brighton antique car rally, and Alan McKim and Ambrose Claverhouse are not going to let their friendship stop them from trying to humiliate each other. ...",
    title: 'Genevieve',
    score: 20.19266128540039
  },
  {
    plot: "A naive drifter runs away from his army father in hopes of making it on the car racing circuit. In Las Vegas, he meets a young scam artist, who develops a crush on him. He is then ...",
    title: 'Speedway Junky',
    score: 18.639965057373047
  }
]

The documents in the results contain the following terms in the plot field with up to a distance of 5 between the terms:

• automobile, car, or vehicle, which are defined as equivalent synonyms in the synonymous_terms collection,

• race, contest, or rally, which are defined as explicit synonyms in the sy``synonymous_terms`` collection,

MongoDB Search returns similar results for a search for car race or vehicle race because we configured automobile, car, and vehicle to be equivalent synonyms. However, the results for automobile contest wouldn't include documents with race or rally and the results for automobile rally wouldn't include documents with race or contest because we didn't configure contest or rally to be synonym of any terms.