text

On this page

Definition

Syntax
Fields
Examples
Basic Example
Fuzzy Examples
Match all
Synonyms Examples
Match any Using equivalent Mapping
Match any Using explicit Mapping
Match all Using Synonyms

Definition

The text operator performs a full-text search using the analyzer that you specify in the index configuration. If you omit an analyzer, the text operator uses the default standard analyzer.

Syntax

text has the following syntax:

{
  $search: {
    "index": <index name>, // optional, defaults to "default"
    "text": {
      "query": "<search-string>",
      "path": "<field-to-search>",
      "fuzzy": <options>,
      "matchCriteria": "any" | "all"
      "score": <options>,
      "synonyms": "<synonyms-mapping-name>"
    }
  }
}

Fields

Field	Type	Description	Necessity
`query`	string or array of strings	The string or strings to search for. If there are multiple terms in a string, Atlas Search also looks for a match for each term in the string separately.	Required
`path`	string or array of strings	The indexed field or fields to search. You can also specify a wildcard path to search. See path construction for more information.	Required
`fuzzy`	document	Enable fuzzy search. Find strings which are similar to the search term or terms. You can't use `fuzzy` with `synonyms`.	Optional
`fuzzy.maxEdits`	integer	Maximum number of single-character edits required to match the specified search term. Value can be `1` or `2`. The default value is `2`. Uses Damerau-Levenshtein distance.	Optional
`fuzzy.prefixLength`	integer	Number of characters at the beginning of each term in the result that must exactly match. The default value is `0`.	Optional
`fuzzy.maxExpansions`	integer	Maximum number of variations to generate and search for. This limit applies on a per-token basis. The default value is `50`.	Optional
`matchCriteria`	string	Criteria to use to match the terms in the query. Value can be one of the following: `any` - to return documents that contain any of the terms from the `query` field. `all` - to only return documents that contain all of the terms from the `query` field. If omitted, defaults to `any`.	Optional, Recommended
`score`	document	Score assigned to matching search term results. Use one of the following options to modify the score: `boost`: multiply the result score by the given number. `constant`: replace the result score with the given number. `function`: replace the result score using 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.	Optional
`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. You can't use `fuzzy` with `synonyms`. Always use `matchCriteria` when using `synonyms`. For `text` queries that use `synonyms` without `matchCriteria`, Atlas Search only matches documents where all the terms are exactly in the same position as the query. This behavior might change in the future and your query results might also change. 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

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. You must also define a synonyms mapping collection in the index as shown in the Index Definition Examples to try the synonyms examples below.

Basic Example

The following Atlas Search example uses the text operator to search the title field in the movies collection for the term surfer.

Example

The following query searches the title field for the term surfer. It includes a $project stage to:

Exclude all fields except title
Add a field named score

db.movies.aggregate([
  {
    $search: {
      "text": {
        "path": "title",
        "query": "surfer"
      }
    }
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Fuzzy Examples

The following queries use the text operator to search the title field in the movies collection for terms that are within one character variation of each term in the query phrase naw yark. Atlas Search returns different results depending on whether you use the default fuzzy options or define the maxExpansions, prefixLength, or maxEdits fields.

Click the following tabs for example queries that use default and specified options:

Example

The following query searches the title field for the phrase naw yark. It uses the fuzzy default options where:

maxEdits allows up to two character variation of each term in the given phrase to match the query to a document.
maxExpansions considers up to fifty similar terms for each term in naw yark to find matches.
prefixLength is disabled.

The query also includes a $limit stage to limit the output to 10 results and a $project stage to:

Exclude all fields except title
Add a field named score

db.movies.aggregate([
  {
    $search: {
      "text": {
        "path": "title",
        "query": "naw yark",
        "fuzzy": {}
      }
    }
  },
  {
    $limit: 10
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Example

The following query searches the title field for terms that are within one character of each term in the string naw yark. It uses:

The maxEdits field to indicate that only one character variation is allowed for each term to match the query to a document.
The maxExpansions field to indicate that up to one hundred similar terms for naw and one hundred similar terms to yark must be considered when matching the query to a document.

The query also includes a $limit stage to limit the output to 10 results and a $project stage to:

Exclude all fields except title
Add a field named score

db.movies.aggregate([
  {
    $search: {
      "text": {
        "path": "title",
        "query": "naw yark",
        "fuzzy": {
          "maxEdits": 1,
          "maxExpansions": 100,
        }
      }
    }
  },
  {
    $limit: 10
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Example

The following query searches the title field for terms that are within one character of each term in the string naw yark. It uses:

The maxEdits field to indicate that only one character variation is allowed to match the query to a document.
The prefixLength field to indicate that the first two characters of each term in the string naw yark may not be changed to match the query to a document.

The query also includes a $limit stage to limit the output to 8 results and a $project stage to:

Exclude all fields except _id and title
Add a field named score

db.movies.aggregate([
  {
    $search: {
      "text": {
        "path": "title",
        "query": "naw yark",
        "fuzzy": {
          "maxEdits": 1,
          "prefixLength": 2,
        }
      }
    }
  },
  {
    $limit: 8
  },
  {
    $project: {
      "_id": 1,
      "title": 1,
      score: { $meta: "searchScore" }
    }
  }
])

Match `all`

The following query uses the text operator to search the plot field in the movies collection for all the terms in the query string automobile race.

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "path": "plot",
        "query": "automobile race",
        "matchCriteria": "all"
      }
    }
  },
  {
    "$limit": 20
  },
  {
    "$project": {
      "_id": 0,
      "plot": 1,
      "title": 1,
      "score": { "$meta": "searchScore" }
    }
  }
])

[
  {
    plot: 'A young driver, Speed Racer, aspires to be champion of the racing world with the help of his family and his high-tech Mach 5 automobile.',
    title: 'Speed Racer',
    score: 6.122188568115234
  },
  {
    plot: 'A gorgeous young automobile fanatic--and front to the hottest unsigned band on the West coast--finds herself caught up in illegal drag-racing competitions organized by exotic car fanatics.',
    title: 'Redline',
    score: 5.497724533081055
  },
  {
    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: 5.282209396362305
  }
]

Atlas Search returns documents that contain the terms automobile and race anywhere in the plot field.

Synonyms Examples

The following examples use the text operator to search the plot field in the sample_mflix.movies namespace. 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.

Match `any` Using `equivalent` Mapping

The following query searches the plot field for the phrase attire. It uses the synonym mapping named mySynonyms in the index for the collection to also search for words that are configured to be synonyms of the word dress.

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "path": "plot",
        "query": "attire",
        "synonyms": "my_synonyms",
        "matchCriteria": "any"
      }
    }
  },
  {
    "$limit": 5
  },
  {
    "$project": {
      "_id": 0,
      "plot": 1,
      "title": 1,
      "score": { "$meta": "searchScore" }
    }
  }
])

Atlas Search returns the documents that contain the terms attire, apparel, and dress because we configured all these terms to be equivalent synonym in the synonyms source collection, synonymous_terms, which mean all these terms are synonyms of one another. Therefore, Atlas Search returns similar documents for searches on dress and attire.

Match `any` Using `explicit` Mapping

The following query searches the plot field for the phrase boat race. It uses the synonym mapping named my_synonyms in the index for the collection to also search for words that are configured to be synonyms of the word boat and race.

db.movies.aggregate([
  {
    "$search": {
      "text": {
        "path": "plot",
        "query": "boat race",
        "synonyms": "my_synonyms",
        "matchCriteria": "any"
      }
    }
  },
  {
    "$limit": 10
  },
  {
    "$project": {
      "_id": 0,
      "plot": 1,
      "title": 1,
      "score": { "$meta": "searchScore" }
    }
  }
])

Atlas Search returns documents that contain the term boat, vessel, or sail, or race, rally, or contest because we configured boat to be an explicit synonym or vessel and sail and we configured race to be an explicit synonym of rally and contest. Atlas Search doesn't return any results for a query on vessel and sail or rally and contest because we didn't configure these words to consider any of the other words as synonyms.

Match `all` Using Synonyms

The following query uses the text operator to search the plot field in the movies collection for all terms in the query string automobile race.

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.

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

Atlas Search returns documents that contain the query terms automobile, car, or vehicle and race, context, or rally because we configured automobile, vehicle, and car to be equivalent synonyms and we configured rally and contest to be explicit synonyms of race in the synonymous_terms collection.

Back

span (Deprecated)

wildcard

text.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Definition

Syntax

Fields

Examples

Basic Example

Example

Fuzzy Examples

Example

Example

Example

Match all

Synonyms Examples

Match any Using equivalent Mapping

Match any Using explicit Mapping

Match all Using Synonyms

text

Match `all`

Match `any` Using `equivalent` Mapping

Match `any` Using `explicit` Mapping

Match `all` Using Synonyms