Docs Menu
Docs Home
/
MongoDB Atlas
/ / / /

phrase

On this page

  • Definition
  • Syntax
  • Options
  • Examples
  • Single Phrase Example
  • Multiple Phrases Example
  • Slop Example
  • Synonyms Example
phrase

The phrase operator performs search for documents containing an ordered sequence of terms using the analyzer specified in the index configuration. If no analyzer is specified, the default standard analyzer is used.

phrase has the following syntax:

1{
2 $search: {
3 "index": <index name>, // optional, defaults to "default"
4 "phrase": {
5 "query": "<search-string>",
6 "path": "<field-to-search>",
7 "score": <options>,
8 "slop": <distance-number>,
9 "synonyms": "<synonyms-mapping-name>"
10 }
11 }
12}

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. See Construct a Query Path.
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 in order 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 you query values in arrays, Atlas Search doesn't alter the score of the matching results based on the number of values inside the array that matched the query. The score would be the same as a single match regardless of the number of matches inside an array.

For information on the options for modifying the default score, see Score the Documents in the Results.

no
synonyms
string

Required for running queries using synonyms.

Name of the synonym mapping definition in the index definition. Value can't be an empty string.

Note

The amount of time that Atlas Search takes to execute queries that use synonym mappings depends on the number and size of documents in the synonym source collection. 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

The examples in this page use the movies collection in the sample_mflix database. After loading the sample dataset into your cluster, create the Atlas Search index with dynamic mappings and run the example queries on your cluster. To try the synonyms examples, you must also add the synonymous_terms collection to the sample_mflix database and then define the index with the synonyms mapping collection.

The following Atlas 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 position of the words must exactly match the query string to be included in the results. The query also includes a:

  • $limit stage to limit the output to 10 results.

  • $project stage to exclude all fields except title and add a field named score.

Example

1db.movies.aggregate([
2 {
3 "$search": {
4 "phrase": {
5 "path": "title",
6 "query": "new york"
7 }
8 }
9 },
10 { $limit: 10 },
11 {
12 $project: {
13 "_id": 0,
14 "title": 1,
15 score: { $meta: "searchScore" }
16 }
17 }
18])

The following Atlas Search example performs a basic 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 position of the words must exactly match the query string to be included in the results. The query also includes a:

Example

  • $limit stage to limit the output to 10.

  • $project stage to exclude all fields except title and add a field named score.

1db.movies.aggregate([
2 {
3 "$search": {
4 "phrase": {
5 "path": "title",
6 "query": ["the man", "the moon"]
7 }
8 }
9 },
10 { $limit: 10 },
11 {
12 $project: {
13 "_id": 0,
14 "title": 1,
15 score: { $meta: "searchScore" }
16 }
17 }
18])

The following Atlas 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 stage to:

  • Exclude all fields except title

  • Add a field named score

1db.movies.aggregate([
2 {
3 "$search": {
4 "phrase": {
5 "path": "title",
6 "query": "men women",
7 "slop": 5
8 }
9 }
10 },
11 {
12 $project: {
13 "_id": 0,
14 "title": 1,
15 score: { $meta: "searchScore" }
16 }
17 }
18])

The following queries search the plot field in the movies collection for the terms in the given query string. Atlas Search returns results based on the type of mapping in the synonym source collection, 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" }
}
}
])

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,

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

Back

near