autocomplete¶

On this page

Definition

Syntax
Options
Examples
Basic Examples
Fuzzy Example
Token Order Example
Highlighting Example

Definition¶

autocomplete¶: The autocomplete operator performs a search for a word or phrase that contains a sequence of characters from an incomplete input 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. 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.

Syntax¶

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 }

Options¶

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

Examples¶

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.

Basic Examples¶

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

$limit stage to limit the output to 10 results.
$project stage to exclude all fields except title.

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

Atlas Search returns different results depending on the tokenization strategy configured in the autocompletion field of the index definition:

Fuzzy Example¶

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.

The query also includes a:

$limit stage to limit the output to 10 results.
$project stage to exclude all fields except title.

1 db.movies.aggregate([
2   {
3     $search: {
4       "autocomplete": {
5         "path": "title",
6         "query": "pre",
7         "fuzzy": {
8           "maxEdits": 1,
9           "prefixLength": 1,
10           "maxExpansions": 256
11         }
12       }
13     }
14   },
15   {
16     $limit: 10
17   },
18   {
19     $project: {
20       "_id": 0,
21       "title": 1
22     }
23   }
24 ])

Atlas Search returns different results depending on the tokenization strategy configured in the autocompletion field of the index definition:

Token Order Example¶

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.

Each query includes a:

$limit stage to limit the output to 4 results.
$project stage to exclude all fields except title.

Highlighting Example¶

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.

The query includes a:

$limit stage to limit the output to 5 results.
$project stage to:
- return the document's score.
- exclude all fields except title.
- add a new field called highlights, which contains highlighting information.

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.

db.movies.aggregate([
  {
    $search: {
      "autocomplete": {
        "path": "title",
        "query": ["ger"]
      },
      "highlight": {
        "path": "title"
      }
    }
  },
  {
    $limit: 5
  },
  {
    $project: {
      "score": { $meta: "searchScore" },
      "title": 1,
      "_id": 0,
      "highlights": { "$meta": "searchHighlights" }
    }
  }
])

The query returns the following results.

{
 "title": "Gertie the Dinosaur",
 "score": 6.0822906494140625,
 "highlights": [
   {
     "score": 0.9227690100669861,
     "path": "title",
     "texts": [ { "value": "Gertie the Dinosaur", "type": "hit" } ]
   }
 ]
},
{
 "title": "Germany Year Zero",
 "score": 6.0822906494140625,
 "highlights": [
   {
     "score": 0.9180012345314026,
     "path": "title",
     "texts": [ { "value": "Germany Year Zero", "type": "hit" } ]
   }
 ]
},
{
 "title": "Germany in Autumn",
 "score": 6.0822906494140625,
 "highlights": [
   {
     "score": 0.9180012345314026,
     "path": "title",
     "texts": [ { "value": "Germany in Autumn", "type": "hit" } ]
   }
 ]
},
{
 "title": "Germany Pale Mother",
 "score": 6.0822906494140625,
 "highlights": [
   {
     "score": 0.9227690100669861,
     "path": "title",
     "texts": [ { "value": "Germany Pale Mother", "type": "hit" } ]
   }
 ]
},
{
 "title": "Gerhard Richter - Painting",
 "score": 6.0822906494140625,
 "highlights": [
   {
     "score": 0.9386774897575378,
     "path": "title",
     "texts": [ { "value": "Gerhard Richter - Painting", "type": "hit" } ]
   }
 ]
}

Atlas Search returns these results because the title field in the movies collection contains the characters ger at the beginning of a word. Atlas Search matches a highlight hit more coarsely to your query terms when a highlighted path is referenced only in the autocomplete operators of the highlighted query.

← Operators compound →

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	}

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