phrase
On this page
Definition
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.
Syntax
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 }
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. 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:
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. NoteThe 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 |
Examples
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.
Single Phrase Example
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 excepttitle
and add a field namedscore
.
Example
1 db.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 ])
Multiple Phrases Example
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 excepttitle
and add a field namedscore
.
1 db.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 ])
Slop Example
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
1 db.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 ])
Synonyms Example
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
, orvehicle
, which are defined asequivalent
synonyms in thesynonymous_terms
collection,race
,contest
, orrally
, which are defined asexplicit
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.