Docs Menu
Docs Home
/
MongoDB Atlas
/ / / /

autocomplete

On this page

  • Definition
  • Sample Use Cases
  • Syntax
  • Options
  • Scoring Behavior
  • Examples
  • Index Definition
  • Basic Example
  • Fuzzy Example
  • Token Order Example
  • Starts With Example
  • Simple any Example
  • Simple sequential Example
  • Highlighting Example
  • Search Across Multiple Fields
  • Bucket Results through Facet Queries
autocomplete

The autocomplete operator performs a search for a word or phrase that contains a sequence of characters from an incomplete input string. The fields that you intend to query with the autocomplete operator must be indexed with the autocomplete data type in the collection's index definition.

Note

Atlas Search might return inaccurate results for queries with more than three words in a single string.

You can use the autocomplete operator with search-as-you-type applications to predict words with increasing accuracy as characters are entered in your application's search field. autocomplete returns results that contain predicted words based on the tokenization strategy specified in the index definition for autocompletion.

If you want to build suggestions or dropdowns using the Atlas Search autocomplete operator, we recommend that you query a collection of suggested search terms or use past search terms to populate the dropdown. If you create a separate collection of suggested search terms, you can define synonym mappings in your Atlas Search index to search your collection for the exact or alternative words. You can track search terms and view metrics for search terms to build your collection.

autocomplete has the following syntax:

1{
2 $search: {
3 "index": "<index name>", // optional, defaults to "default"
4 "autocomplete": {
5 "query": "<search-string>",
6 "path": "<field-to-search>",
7 "tokenOrder": "any|sequential",
8 "fuzzy": <options>,
9 "score": <options>
10 }
11 }
12}
Field
Type
Description
Necessity
Default
query
string or array of strings
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.
yes
path
string

Indexed autocomplete type of field to search.

Tip

See also:

Note

The autocomplete operator does not support multi in the field path. It also doesn't support an array of fields or wildcard (*) as value for path. To learn more, see path construction. For an example of an autocomplete operator query across multiple fields, see Search Across Multiple Fields or the Advanced Example in the tutorial.

yes
fuzzy
object
Enable fuzzy search. Find strings which are similar to the search term or terms.
no
fuzzy
.maxEdits
integer
Maximum number of single-character edits required to match the specified search term. Value can be 1 or 2.
no
2
fuzzy
.prefixLength
integer
Number of characters at the beginning of each term in the result that must exactly match.
no
0
fuzzy
.maxExpansions
integer
Maximum number of variations to generate and search for. This limit applies on a per-token basis.
no
50
score
object

Score to assign to the matching search term results. Use one of the following options to modify the default score:

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.

For information on using score in your query, see Score the Documents in the Results.

Note

autocomplete offers less fidelity in score in exchange for faster query execution.

To learn more, see Scoring Behavior.

no
tokenOrder
string

Order in which to search for tokens. Value can be one of the following:

any
Indicates tokens in the query can appear in any order in the documents. Results contain documents where the tokens appear sequentially and non-sequentially. However, results where the tokens appear sequentially score higher than other, non-sequential values.
sequential
Indicates tokens in the query must appear adjacent to each other or in the order specified in the query in the documents. Results contain only documents where the tokens appear sequentially.
no
any

The autocomplete operator query results that are exact matches receive a lower score than results that aren't exact matches. Atlas Search can't determine if a query string is an exact match for an indexed text if you specify just the autocomplete-indexed token substrings. To score exact matches higher, try the following workaround:

Note

The following workaround doesn't guarantee higher scores for exact matches in all cases.

  1. Index the field as both autocomplete and string types.

    Atlas Search autocomplete boosts exact matches when an autocomplete field is also indexed as a string, thereby increasing the score of exact matches.

  2. Query using the compound operator.

For a demonstration of this workaround, see Search Across Multiple Fields.

The following examples use the movies collection in the sample_mflix database. If you loaded the sample dataset on your cluster, you can create the static index for autocompletion and run the example queries on your cluster.

Tip

If you've already loaded the sample dataset, follow the Get Started with Atlas Search tutorial to create an index definition and run Atlas Search queries.

The following tabs contain sample index definitions for the edgeGram, rightEdgeGram, and nGram tokenization strategies. In addition to the autocomplete type, the sample index definitions include the string and stringFacet types on the title field.


Use the Select your language drop-down menu to set the language of the example on this page.


The following query searches for movies with the characters off in the title field.

Note

Your Results May Vary

Atlas Search returns different results depending on the tokenization strategy configured in the index definition for the autocomplete type. To learn more, see How to Index Fields for Autocompletion.

The following query searches for movies with the characters pre in the title field. The query uses:

Field
Description
maxEdits
Indicates that only one character variation is allowed in the query string pre to match the query to a word in the documents.
prefixLength
Indicates that the first character in the query string pre can't change when matching the query to a word in the documents.
maxExpansions
Indicates that up to two hundred and fifty six similar terms for pre can be considered when matching the query string to a word in the documents.

Note

Your Results May Vary

Atlas Search returns different results depending on the tokenization strategy configured in the index definition for the autocomplete type. To learn more, see How to Index Fields for Autocompletion.

The following queries search for movies with the characters men with in the title field. The queries also use the tokenOrder field, which specifies whether the query searches for tokens in any order or in sequential order.

You can search the title field for movie titles that start with a term or phrase by indexing the field using the keyword analyzer.

You must index the field using the keyword analyzer with the edgeGram tokenization strategy to retrieve results for the following sample query. If you index the field using any other built-in analyzers, Atlas Search doesn't return any results because it doesn't index your text field as a single term. The edgeGram tokenization strategy creates tokens starting at the left side of the words.

You must also set foldDiacritics to true to return case-agnostic results. If you set foldDiacritics to false, the letter case of the query term must exactly match the letter case in the document for Atlas Search to return any results.

{
"mappings": {
"dynamic": false,
"fields": {
"title": [
{
"type": "stringFacet"
},
{
"type": "string"
},
{
"foldDiacritics": true,
"maxGrams": 7,
"minGrams": 3,
"analyzer": "lucene.keyword",
"tokenization": "edgeGram",
"type": "autocomplete"
}]
}
}
}

The following query searches for movie titles that start with the term Fast &.

Note

Your Results May Vary

Atlas Search returns different results depending on the tokenization strategy configured in the index definition for the autocomplete type. To learn more, see How to Index Fields for Autocompletion.

Note

Your Results May Vary

Atlas Search returns different results depending on the tokenization strategy configured in the index definition for the autocomplete type. To learn more, see How to Index Fields for Autocompletion.

The following query searches for the characters ger in the title field of the movies collection, with the highlight option enabled for the title field.

Important

To highlight the autocomplete indexed version of a path, the autocomplete operator must be the only operator that uses that path in the query.

Note

Your Results May Vary

Atlas Search returns different results depending on the tokenization strategy configured in the index definition for the autocomplete type. To learn more, see How to Index Fields for Autocompletion.

The following query searches the title and plot fields of the movies collection for words that begin with the character string inter using the compound operator.

Note

Your Results May Vary

Atlas Search returns different results depending on the tokenization strategy configured in the index definition for the autocomplete type. To learn more, see How to Index Fields for Autocompletion.

← 2. Use Operators & Collectors