> This page location: /docs.md > /docs/development.md > /docs/search.md > /docs/search/about/searching.md > /docs/search/query/query-ref.md > /docs/search/query/operators-collectors/overview.md

> 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:

```json
{
  $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:

| Field | Type | Description | Necessity |
| --- | --- | --- | --- |
| `query` | string or array of strings | String or strings to search for. | yes |
| `path` | string or array of strings | Indexed field or fields to search. You can also specify a wildcard path to search. IMPORTANT: To use the `phrase` operator, you must index the query field as type `string` with the `indexOptions` property set to `positions` or the default value, `offsets`. To learn more, see [Configure String Field Properties.](https://www.mongodb.com/docs/search/indexes/field-types/string-type.md#std-label-fts-field-types-string-options) | yes |
| `slop` | integer | Allowable distance between words in the `query` phrase. Lower value allows less positional distance between the words and greater value allows more reorganization of the words and more distance between the words to satisfy the query. The default is `0`, meaning that words must be exactly in the same position as the query to be considered a match. Exact matches are scored higher. | no |
| `score` | object | Score to assign to matching search results. You can modify the default score using the following options: `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. When querying array values, MongoDB Search assigns higher scores if more values in the array match the query. For information on the options for modifying the default score, see [Score the Documents in the Results.](https://www.mongodb.com/docs/search/query/score/overview.md#std-label-scoring-ref) | no |
| `synonyms` | string | Required for running queries using [synonyms.](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-synonyms-ref) Name of the [synonym mapping definition](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-synonyms-ref) in the [index definition](https://www.mongodb.com/docs/search/indexes/index-definitions.md#std-label-ref-index-definitions). Value can't be an empty string. The amount of time that MongoDB Search takes to execute queries that use [synonym mappings](https://www.mongodb.com/docs/search/indexes/synonyms.md#std-label-synonyms-ref) depends on the number and size of documents in the synonym source collection. For example, a query that uses a synonym mapping that is based on very few synonym documents might be faster than a query that uses a synonym mapping that is based on many synonym documents. | Optional |

## 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.

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

**Output:**

```shell
[
  { 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:**

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

**Output:**

```shell
[
  {
    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`.

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

**Output:**

```shell
[
  { 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`

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

**Output:**

```shell
[
  { 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.

```json
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:**

```json
[
  {
    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.
