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

Definition

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. To learn how to configure your index for autocompletion, see How to Index Fields for Autocompletion.

Note

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

Sample Use Cases

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.

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 field to search. This field must be indexed as the autocomplete data type. To learn more, see How to Index Fields for Autocompletion.

The autocomplete operator doesn't support the multi or wildcard (*) options in the path parameter. It also doesn't support an array of fields as the path value. To learn more, see Construct a Query Path.

For an example of an autocomplete operator query across multiple fields, see Search Across Multiple Fields or the Advanced Example in How to Use Autocomplete with Atlas Search.

yes

fuzzy

object

Enable fuzzy search. Find strings which are similar to the search term or terms.

fuzzy

.maxEdits

integer

Maximum number of single-character edits required to match the specified search term. Value can be 1 or 2.

2

fuzzy

.prefixLength

integer

Number of characters at the beginning of each term in the result that must exactly match.

0

fuzzy

.maxExpansions

integer

Maximum number of variations to generate and search for. This limit applies on a per-token basis.

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.

autocomplete offers less fidelity in score in exchange for faster query execution. To learn more, see Scoring Behavior.

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

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.

any

Scoring Behavior

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.

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.
Query using the compound operator.

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

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.

Index Definition

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.

1 {
2   "mappings": {
3     "dynamic": false,
4     "fields": {
5       "title": [
6         {
7           "type": "stringFacet"
8         },
9         {
10           "type": "string"
11         },
12         {
13           "foldDiacritics": false,
14           "maxGrams": 7,
15           "minGrams": 3,
16           "tokenization": "edgeGram",
17           "type": "autocomplete"
18         }
19       ]
20     }
21   }
22 }

1 {
2   "mappings": {
3     "dynamic": false,
4     "fields": {
5       "title": [
6         {
7           "type": "stringFacet"
8         },
9         {
10           "type": "string"
11         },
12         {
13           "type": "autocomplete",
14           "tokenization": "rightEdgeGram",
15           "minGrams": 3,
16           "maxGrams": 7,
17           "foldDiacritics": false
18         }
19       ]
20     }
21   }
22 }

1 {
2   "mappings": {
3     "dynamic": false,
4     "fields": {
5       "title": [
6         {
7           "type": "stringFacet"
8         },
9         {
10           "type": "string"
11         },
12         {
13           "type": "autocomplete",
14           "tokenization": "nGram",
15           "minGrams": 3,
16           "maxGrams": 7,
17           "foldDiacritics": false
18         }
19       ]
20     }
21   }
22 }

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

To view and edit query syntax in the Search Tester:

In Atlas, go to the Clusters page for your project.

If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If the Clusters page is not already displayed, click Database in the sidebar.
The Clusters page displays.

Go to the Atlas Search page for your cluster.

You can go the Atlas Search page from the sidebar, the Data Explorer, or your cluster details page.

In the sidebar, click Atlas Search under the Services heading.
From the Select data source dropdown, select your cluster and click Go to Atlas Search.
The Atlas Search page displays.

Click the Browse Collections button for your cluster.
Expand the database and select the collection.
Click the Search Indexes tab for the collection.
The Atlas Search page displays.

Click the cluster's name.
Click the Atlas Search tab.
The Atlas Search page displays.

View and edit the query syntax.

Click the Query button to the right of the index to query.
Click Edit Query to view a default query syntax sample in JSON format.

Run the following command at the mongosh prompt to use the sample_mflix database:

use sample_mflix

Basic Example

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

Copy and paste the following query into the Query Editor, and then click the Search button in the Query Editor.

[
  {
    $search: {
      autocomplete: {
        path: "title",
        query: "off"
      }
    }
  }
]

The query includes a:

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

db.movies.aggregate([
  {
    $search: {
      "autocomplete": {
        "path": "title",
        "query": "off"
      }
    }
  },
  {
    $limit: 10
  },
  {
    $project: {
      "_id": 0,
      "title": 1
    }
  }
])

The query includes a:

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

In the Aggregations tab of the movies collection, configure each of the following pipeline stages by selecting the stage from the dropdown and adding the query for that stage. Click Add Stage to add additional stages.

Pipeline Stage

Query

$search

{
  "autocomplete": {
    "query": "off",
    "path": "title"
  }
}

$limit

$project

{
  "_id": 0,
  "title": 1,
}

The query includes a:

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

using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Bson.Serialization.Conventions;
using MongoDB.Driver;
using MongoDB.Driver.Search;
public class AutocompleteBasicExample
{
    private const string MongoConnectionString = "<connection-string>";
    public static void Main(string[] args)
    {
        // allow automapping of the camelCase database fields to our MovieDocument
        var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
        ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);
        // connect to your Atlas cluster
        var mongoClient = new MongoClient(MongoConnectionString);
        var mflixDatabase = mongoClient.GetDatabase("sample_mflix");
        var moviesCollection = mflixDatabase.GetCollection<MovieDocument>("movies");
        // define and run pipeline
        var results = moviesCollection.Aggregate()
            .Search(Builders<MovieDocument>.Search.Autocomplete(movie => movie.Title, "off"))
            .Project<MovieDocument>(Builders<MovieDocument>.Projection
                .Include(movie => movie.Title)
                .Exclude(movie => movie.Id))
            .Limit(10)
            .ToList();
        // print results
        foreach (var movie in results)
        {
            Console.WriteLine(movie.ToJson());
        }
    }
}
[BsonIgnoreExtraElements]
public class MovieDocument
{
    [BsonIgnoreIfDefault]
    public ObjectId Id { get; set; }
    public string Title { get; set; }
}

The query includes a:

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

package main
import (
	"context"
	"fmt"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/mongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)
func main() {
	// connect to your Atlas cluster
	client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI("<connection-string>"))
	if err != nil {
		panic(err)
	}
	defer client.Disconnect(context.TODO())
	// set namespace
	collection := client.Database("sample_mflix").Collection("movies")
	// define pipeline stages
	searchStage := bson.D{{"$search", bson.D{{"autocomplete", bson.D{{"query", "off"}, {"path", "title"}}}}}}
	limitStage := bson.D{{"$limit", 10}}
	projectStage := bson.D{{"$project", bson.D{{"title", 1}, {"_id", 0}}}}
	// run pipeline
	cursor, err := collection.Aggregate(context.TODO(), mongo.Pipeline{searchStage, limitStage, projectStage})
	if err != nil {
		panic(err)
	}
	// print results
	var results []bson.D
	if err = cursor.All(context.TODO(), &results); err != nil {
		panic(err)
	}
	for _, result := range results {
		fmt.Println(result)
	}
}

The query includes a:

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

import static com.mongodb.client.model.Aggregates.limit;
import static com.mongodb.client.model.Aggregates.project;
import static com.mongodb.client.model.Projections.excludeId;
import static com.mongodb.client.model.Projections.fields;
import static com.mongodb.client.model.Projections.include;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import org.bson.Document;
import java.util.Arrays;
public class AutocompleteBasicExample {
    public static void main(String[] args) {
        // connect to your Atlas cluster
        String uri = "<connection-string>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            // set namespace
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
            MongoCollection<Document> collection = database.getCollection("movies");
            
            // define pipeline
            Document agg = new Document("$search", new Document("autocomplete", new Document("query", "off").append("path", "title")));
            // run pipeline and print results
            collection.aggregate(Arrays.asList(agg,
                limit(10),
                project(fields(excludeId(), include("title"))))).forEach(doc -> System.out.println(doc.toJson()));
        }
    }
}

The query includes a:

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

import com.mongodb.client.model.Aggregates.limit
import com.mongodb.client.model.Aggregates.project
import com.mongodb.client.model.Projections.*
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.runBlocking
import org.bson.Document
fun main() {
    val uri = "<connection-string>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Document>("movies")
    runBlocking {
        val agg = Document(
            "\$search",
            Document("autocomplete", Document("query", "off")
                .append("path", "title"))
        )
        val resultsFlow = collection.aggregate<Document>(
            listOf(
                agg,
                limit(10),
                project(fields(excludeId(), include("title")))
            )
        )
        resultsFlow.collect { println(it) }
    }
    mongoClient.close()
}

The query includes a:

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

const { MongoClient } = require("mongodb");
// connect to your Atlas cluster
const uri =
    "<connection-string>";
const client = new MongoClient(uri);
async function run() {
    try {
        await client.connect();
        // set namespace
        const database = client.db("sample_mflix");
        const coll = database.collection("movies");
        // define pipeline
        const agg = [
            {$search: {autocomplete: {query: "off", path: "title"}}},
            {$limit: 10},
            {$project: {_id: 0,title: 1}}
        ];
        // run pipeline
        const result = await coll.aggregate(agg);
        // print results
        await result.forEach((doc) => console.log(doc));
    } finally {
        await client.close();
    }
}
run().catch(console.dir);

The query includes a:

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

import pymongo
# connect to your Atlas cluster
client = pymongo.MongoClient('<connection-string>')
# define pipeline
pipeline = [
    {"$search": {"autocomplete": {"query": "off", "path": "title"}}},
    {"$limit": 10},
    {"$project": {"_id": 0, "title": 1}},
]
# run pipeline
result = client["sample_mflix"]["movies"].aggregate(pipeline)
# print results
for i in result:
    print(i)

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.

SCORE: 9.361787796020508  _id:  "573a13b0f29313caabd355c8"
  countries: Array
  genres: Array
  runtime: 100
  ...
  title: "Off Beat"
SCORE: 9.068204879760742  _id:  "573a13aaf29313caabd22a8c"
  fullplot: "An 11-year-old girl watches her father come down with a crippling depr…"
  imdb: Object
  year: 2003
  ...
  title: "Off the Map"
SCORE: 9.068204879760742  _id:  "573a13bef29313caabd5d208"
  plot: "With white Jewish lesbians for parents and two adopted brothers - one …"
  genres: Array
  runtime: 76
  ...
  title: "Off and Running"
SCORE: 8.742463111877441  _id:  "573a13bbf29313caabd5567"
  countries: Array
  genres: Array
  runtime: 98
  ...
  title: "Hands off Mississippi"
SCORE: 8.61273193359375  _id:  "5573a1396f29313caabce4791"
  plot: "Unable to deal with her parents, Jeannie Tyne runs away from home. Lar…"
  genres: Array
  runtime: 93
  ...
  title: "Taking Off"
SCORE: 8.61273193359375  _id:  "573a1399f29313caabced3c1"
  plot: "A travelling theater group find so much action going on behind-the-sce…"
  genres: Array
  runtime: 101
  ...
  title: "Noises Off..."
SCORE: 8.61273193359375  _id:  "573a139af29313caabcefc73"
  fullplot: "In existence for a hundred years, Grimley Colliery Brass band is as ol…"
  imdb: Object
  year: 1996
  ...
  title: "Brassed Off"
SCORE: 8.61273193359375  _id:  "573a139af29313caabcf08f5"
  fullplot: "Sean Archer, a very tough, rugged FBI Agent. Who is still grieving for…"
  imdb: Object
  year: 1997
  ...
  title: "Face/Off"
SCORE: 8.603004455566406  _id:  "573a13a9f29313caabd1ea36"
  fullplot: "Three unlikely, unsuspecting souls who come face-to-face with that mom…"
  imdb: Object
  year: 2004
  ...
  title: "Benji: Off the Leash!"
SCORE: 7.953945159912109  _id:  "573a139af29313caabcf037c"
  plot: "Desperation drives four inner-city women (Queen Latifah, Jada Pinkett …"
  genres: Array
  runtime: 123
  ...
  title: "Set it Off"

SCORE: 9.81808090209961  _id:  "5573a1396f29313caabce4791"
  plot: "Unable to deal with her parents, Jeannie Tyne runs away from home. Lar…"
  genres: Array
  runtime: 93
  ...
  title: "Taking Off"
SCORE: 9.81808090209961  _id:  "573a1399f29313caabced3c1"
  plot: "A travelling theater group find so much action going on behind-the-sce…"
  genres: Array
  runtime: 101
  ...
  title: "Noises Off..."
SCORE: 9.81808090209961  _id:  "573a139af29313caabcefc73"
  fullplot: "In existence for a hundred years, Grimley Colliery Brass band is as ol…"
  imdb: Object
  year: 1996
  ...
  title: "Brassed Off"
SCORE: 9.81808090209961  _id:  "573a139af29313caabcf08f5"
  fullplot: "Sean Archer, a very tough, rugged FBI Agent. Who is still grieving for…"
  imdb: Object
  year: 1997
  ...
  title: "Face/Off"
SCORE: 9.544584274291992  _id:  "573a139af29313caabcf037c"
  plot: "Desperation drives four inner-city women (Queen Latifah, Jada Pinkett …"
  genres: Array
  runtime: 123
  ...
  title: "Set it Off"
SCORE: 9.191947937011719  _id:  "573a13bbf29313caabd5567"
  countries: Array
  genres: Array
  runtime: 98
  ...
  title: "Hands off Mississippi"
SCORE: 9.074413299560547  _id:  "573a1398f29313caabce9f28"
  plot: "A high school wise guy is determined to have a day off from school, de…"
  genres: Array
  runtime: 103
  ...
  title: "Ferris Bueller's Day Off"
SCORE: 9.007184982299805  _id:  "573a13b0f29313caabd355c8"
  countries: Array
  genres: Array
  runtime: 100
  ...
  title: "Off Beat"
SCORE: 8.700296401977539  _id:  "573a13a9f29313caabd1ea36"
  fullplot: "Three unlikely, unsuspecting souls who come face-to-face with that mom…"
  imdb: Object
  year: 2004
  ...
  title: "Benji: Off the Leash!"
SCORE: 8.33833122253418  _id:  "573a13aaf29313caabd22a8c"
  fullplot: "An 11-year-old girl watches her father come down with a crippling depr…"
  imdb: Object
  year: 2003
  ...
  title: "Off the Map"

SCORE: 5.802560806274414  _id:  “573a1396f29313caabce47f4”
  countries: Array
  genres: Array
  runtime: 98
  ...
  title: "Come Have Coffee with Us"
SCORE: 5.790548801422119  _id:  "573a13d1f29313caabd90811"
  plot: "From pagan re-enactors to failed communes, black metal festivals to Ar…"
  genres: Array
  runtime: 98
  ...
  title: "A Spell to Ward Off the Darkness"
SCORE: 5.7726240158081055  _id:  "573a13f3f29313caabddeb07"
  plot: "Turkey in the 1960s and 70s was one of the biggest producers of film i…"
  genres: Array
  runtime: 96
  ...
  title: "Remake, Remix, Rip-Off: About Copy Culture & Turkish Pop Cinema"
SCORE: 5.749281883239746  _id:  "573a13a9f29313caabd1ea36"
  fullplot: "Three unlikely, unsuspecting souls who come face-to-face with that mom…"
  imdb: Object
  year: 2004
  ...
  title: "Benji: Off the Leash!"
SCORE: 5.749281883239746  _id:  "573a13d4f29313caabd98488"
  fullplot: "This tragicomedy is a self-ironic portrait of a young man who drops ou…"
  imdb: Object
  year: 2012
  ...
  title: "A Coffee in Berlin"
SCORE: 5.74220085144043  _id:  “573a1397f29313caabce863f”
  fullplot: "Zack Mayo is a young man who has signed up for Navy Aviation Officer C…"
  imdb: Object
  year: 1982
  ...
  title: "An Officer and a Gentleman"
SCORE: 5.671174049377441  _id:  “573a1398f29313caabce987c”
  plot: "After the end of the Dirty War, a high school teacher sets out to find…"
  genres: Array
  runtime: 112
  ...
  title: "The Official Story"
SCORE: 5.671174049377441  _id:   “573a13a5f29313caabd14c36”
  plot: "The first days of WWI. Adrien, a young and handsome lieutenant, is wou…"
  genres: Array
  runtime: 135
  ...
  title: "The Officer's Ward"
SCORE: 5.671174049377441  _id:  "573a13bbf29313caabd5567"
  countries: Array
  genres: Array
  runtime: 98
  ...
  title: "Hands off Mississippi"
SCORE: 5.534632682800293  _id:  "573a1395f29313caabce18c9"
  plot: "In this "Romeo and Juliet" inspired Cold War satire starring, written …"
  genres: Array
  runtime: 103
  ...
  title: "Romanoff and Juliet"

The Search Tester might not display all the fields in the documents it returns. To view all the fields, including the field that you specify in the query path, expand the document in the results.

1 { title: 'Off Beat' },
2 { title: 'Off the Map' },
3 { title: 'Off and Running' },
4 { title: 'Hands off Mississippi' },
5 { title: 'Taking Off' },
6 { title: 'Noises Off...' },
7 { title: 'Brassed Off' },
8 { title: 'Face/Off' },
9 { title: 'Benji: Off the Leash!' },
10 { title: 'Set It Off' }