Implement autocomplete

Cloud Search's autocomplete assists a user by suggesting words when the user is typing a search query. For example, suggestions might be words from document titles, search operators, search operator values, or names and email addresses from the Google Workspace organization.

Autocomplete extracts phrases from the titles of indexed documents and, using an n-gram model, determines suggestions to serve using the Suggest API. By default, phrases from the document titles are shown in autocomplete. You can also mark text and enum schema properties as is_suggestable to autocomplete the corresponding property name and values.

The Suggest API examines the search query for hints about the query's language, such as English or Spanish, and prioritizes results accordingly. The languageCode field of a request is also used to improve language-specific suggestions.

Example scenario

For example, let's say you have the following datasource containing data about movies:

  • The datasource contains 2 documents.
  • Each document has a title (ItemMetadata.title) and two properties: genre and characters.
  • The first document is titled "Avengers Infinity War” with genre=science fiction and characters=Iron Man, Hulk
  • The second document is titled "Harry Potter" with genre=Adventure, Fantasy andcharacters=Hermione, Harry Potter`

Figure 1 illustrates how the autocomplete suggestions are extracted from the document titles, properties, and the property values.

Two documents and resulting ngram
Figure 1. Two documents and resulting n-gram used for autocomplete

From document 1, we extract ngrams (up to trigrams) “Avengers”, “Infinity”, “War”, “Avengers Infinity”, “Infinity War”, “Avengers Infinity War.” Similarly from document 2, we generate “Harry”, “Potter”, “Harry Potter”.

When querying this datasource, let's say the user starts by typing "h." The suggestions shown to the user would be:

  • Harry
  • Hermione
  • Hulk
  • Harry Potter

Let's say the user selects the autocomplete suggestion “Hermione” and the next keystroke from the user is the character "a." The autocomplete suggestions shown to the user would be:

  • Hermione Adventure
  • Hermione Action
  • Hermione Avengers

Autocomplete tries to complete the last word (or ngram) being typed. In the previous example, it just expands "a" to "adventure", "action" and "avengers" since there is no text starting with "hermione a" together. This suggestion is called tail suggestion; autocompleting only the last word/n-gram being typed.

Cloud Search's autocomplete returns a maximum of 5 suggestions from document content and 2 people suggestions.

By default, phrases from the document titles are shown in autocomplete. Schema properties must be explicitly marked as is_suggestable for the suggest API to autocomplete the corresponding property name and values.

Integrate with the Autocomplete API

If you are using the default search application or the embeddable search widget, Cloud Search's autocomplete feature is natively supported without any additional work. Remember, by default, phrases from the document titles are shown in autocomplete. Schema properties must be explicitly marked as is_suggestable for the suggest API to autocomplete the corresponding property name and values.

If you are building a custom search application, autocomplete is available by querying the /query/suggest API endpoints.

Limitations

Autocomplete has the following limitations:

  • Restricting Cloud Search's autocomplete phrases using the FilterOptions defined in the schema is not supported except for the following built-in filters: objectype, mimetype, and type filters.

  • Query history-based suggestions (searches performed by the user previously in a search application) are not supported

  • A maximum of 20 properties can be marked as is_suggestable. This limit can be increased by contacting Cloud Search support.

  • Search operator autocomplete is not available for properties with exact_match_with_operator.

  • Cloud Search's autocomplete returns a maximum of 5 suggestions from document content and 2 people suggestions.

  • Cloud Search's autocomplete suggests phrases only from those documents a user has access to.