How to Use Autocomplete with Atlas Search¶

On this page

Define an Index with Autocomplete

Run an Autocomplete Query

This tutorial describes how to create an Atlas Search index that enables autocomplete queries. We will create an Atlas Search index for indexing values of the title field in the sample_mflix.movies collection. The index enables autocomplete operators to query the title field. Then we will run a search for a sequence of characters against the title field for movie title suggestions that match the incomplete input string. It takes you through the following steps:

Set up an Atlas Search index with autocomplete data type for the sample_mflix.movies collection.
Run Atlas Search queries against the title field in the sample_mflix.movies collection for a sequence of characters that appear in the movie titles.

Before you begin, ensure that your Atlas cluster meets the requirements described in the Prerequisites.

Define an Index with Autocomplete¶

You can use the autocomplete data type to index text values for autocompletion. You can configure an autocomplete field to satisfy a variety of use cases. To learn more about the configuration options available in the autocomplete data type, such as tokenization strategy and diacritic folding, see autocomplete. You can use the autocomplete operator to query only fields indexed using autocomplete.

Note

You can't use the autocomplete type to index fields whose value is an array of strings.

In this section, you will create an Atlas Search index that indexes the title field for autocompletion using the edgeGram tokenization strategy.

Navigate to the Atlas Search page for your project.¶

If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
Click your cluster's name.
Click the Search tab.

Click Create Index.¶

Select a Configuration Method and click Next.¶

For a guided experience, select Visual Editor.
To edit the raw index definition, select JSON Editor.

Enter the Index Name, and set the Database and Collection.¶

In the Index Name field, enter default.
The index name defaults to default. You can leave the default name in place or choose one of your own.
Note
If you name your index default, you don't need to specify an index parameter when using the $search pipeline stage. Otherwise, you must specify the index name using the index parameter.
Index names must be unique within their namespace.
In the Database and Collection section, find the sample_mflix database, and select the movies collection.

Specify an index definition with the `autocomplete` field type.¶

You can use the Visual Editor or the JSON Editor in the Atlas user interface to create the index.

Visual Editor¶

Click Next.
Click Refine Your Index.
Click Add Field.

Configure the following field for autocompletion:

UI Field Name	Configuration
Field Name	Enter `title`.
Enable Dynamic Mapping	Toggle to Off.

Click Add Data Type, and select Autocomplete.
Review the following default settings:
UI Field Name
Configuration
Max Grams
15
Min Grams
2
Tokenization
edgeGram
Fold Diacritics
true
Click Save Changes.
Click Create Search Index.
Note
The You're All Set! modal window appears to let you know your index is building.
Click the Close button.

UI Field Name	Configuration
Max Grams	`15`
Min Grams	`2`
Tokenization	edgeGram
Fold Diacritics	true

JSON Editor¶

Replace the default definition with the following and click Next.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "title": [
        {
          "type": "autocomplete",
          "tokenization": "edgeGram",
          "minGrams": 2,
          "maxGrams": 15,
          "foldDiacritics": true
        }
      ]
    }
  }
}

Click Create Search Index.

Wait for the index to finish building.¶

The index should take about one minute to build. While it is building, the Status column reads Build in Progress. When it is finished building, the Status column reads Active.

Run an Autocomplete Query¶

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.

In this section, you will connect to your Atlas cluster and the run the sample queries against the title field in the sample_mflix.movies collection using the autocomplete operator. The sample queries use a sequence of characters to find movie titles that begin with the input character string. Atlas Search returns results that begin with the specified query string because the title field is indexed using the edgeGram tokenization strategy.

Connect to your cluster in `mongosh`.¶

Open mongosh in a terminal window and connect to your cluster. For detailed instructions on connecting, see Connect via mongosh.

Use the `sample_mflix` database.¶

Run the following command at mongosh prompt:

use sample_mflix

Run an Atlas Search query with the `autocomplete` operator on the `movies` collection.¶

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

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

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

This query returns the following results:

1 { title: "Gertie the Dinosaur" },
2 { title: "Germany Year Zero" },
3 { title: "Germany in Autumn" },
4 { title: "Germany Pale Mother" },
5 { title: "Gerhard Richter - Painting" },
6 { title: "Geronimo: An American Legend" },
7 { title: "How to Live in the German Federal Republic" },
8 { title: "Geri's Game" },
9 { title: "The Gerson Miracle" },
10 { title: "The German Doctor" },
11 { title: "From Caligari to Hitler: German Cinema in the Age of the Masse"},
12 { title: "From Caligari to Hitler: German Cinema in the Age of the Masses"},
13 { title: "Gervaise" },
14 { title: "Gertrud" },
15 { title: "Germinal" },
16 { title: "Gerry" },
17 { title: "Gèraldine" },
18 { title: "Gerontophilia" },
19 { title: "Pionery-geroi" },
20 { title: "Rece do gèry" }

In these results, the characters ger appear at the beginning of a word in all the titles. Atlas Search returns Gèraldine and Rece do gèry in the results because we set foldDiacritics to true.

← Tutorials How to run Compound Queries with Weighted Fields →

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

1	{ title: "Gertie the Dinosaur" },
2	{ title: "Germany Year Zero" },
3	{ title: "Germany in Autumn" },
4	{ title: "Germany Pale Mother" },
5	{ title: "Gerhard Richter - Painting" },
6	{ title: "Geronimo: An American Legend" },
7	{ title: "How to Live in the German Federal Republic" },
8	{ title: "Geri's Game" },
9	{ title: "The Gerson Miracle" },
10	{ title: "The German Doctor" },
11	{ title: "From Caligari to Hitler: German Cinema in the Age of the Masse"},
12	{ title: "From Caligari to Hitler: German Cinema in the Age of the Masses"},
13	{ title: "Gervaise" },
14	{ title: "Gertrud" },
15	{ title: "Germinal" },
16	{ title: "Gerry" },
17	{ title: "Gèraldine" },
18	{ title: "Gerontophilia" },
19	{ title: "Pionery-geroi" },
20	{ title: "Rece do gèry" }