Documents - Autocomplete Post

Reference

Service:: Search Service

API Version:: 2023-11-01

Autocompletes incomplete query terms based on input text and matching terms in the index.

POST {endpoint}/indexes('{indexName}')/docs/search.post.autocomplete?api-version=2023-11-01

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The endpoint URL of the search service.
indexName	path	True	string	The name of the index.
api-version	query	True	string	Client Api Version.

Request Header

Name	Required	Type	Description
x-ms-client-request-id		string uuid	The tracking ID sent with the request to help with debugging.

Request Body

Name	Required	Type	Description
search	True	string	The search text on which to base autocomplete results.
suggesterName	True	string	The name of the suggester as specified in the suggesters collection that's part of the index definition.
autocompleteMode		AutocompleteMode	Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context while producing auto-completed terms.
filter		string	An OData expression that filters the documents used to produce completed terms for the Autocomplete result.
fuzzy		boolean	A value indicating whether to use fuzzy matching for the autocomplete query. Default is false. When set to true, the query will autocomplete terms even if there's a substituted or missing character in the search text. While this provides a better experience in some scenarios, it comes at a performance cost as fuzzy autocomplete queries are slower and consume more resources.
highlightPostTag		string	A string tag that is appended to hit highlights. Must be set with highlightPreTag. If omitted, hit highlighting is disabled.
highlightPreTag		string	A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting is disabled.
minimumCoverage		number	A number between 0 and 100 indicating the percentage of the index that must be covered by an autocomplete query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 80.
searchFields		string	The comma-separated list of field names to consider when querying for auto-completed terms. Target fields must be included in the specified suggester.
top		integer	The number of auto-completed terms to retrieve. This must be a value between 1 and 100. The default is 5.

Responses

Name	Type	Description
200 OK	AutocompleteResult	Response containing suggested query terms that complete the partial input.
Other Status Codes	SearchError	Error response.

Examples

SearchIndexAutocompleteDocumentsPost

Sample Request

HTTP

POST https://myservice.search.windows.net/indexes('myindex')/docs/search.post.autocomplete?api-version=2023-11-01

{
  "autocompleteMode": "oneTerm",
  "search": "washington medic",
  "suggesterName": "sg",
  "filter": "search.in(docId,'101,102,105')",
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "searchFields": "title,description",
  "top": 10
}

Sample Response

Status code:: 200

[
  {
    "text": "medicaid",
    "queryPlusText": "washington medicaid"
  },
  {
    "text": "medicare",
    "queryPlusText": "washington medicare"
  },
  {
    "text": "medicine",
    "queryPlusText": "washington medicine"
  }
]

Definitions

Name	Description
AutocompleteItem	The result of Autocomplete requests.
AutocompleteMode	Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context in producing autocomplete terms.
AutocompleteRequest	Parameters for fuzzy matching, and other autocomplete query behaviors.
AutocompleteResult	The result of Autocomplete query.
SearchError	Describes an error condition for the API.

AutocompleteItem

The result of Autocomplete requests.

Name	Type	Description
queryPlusText	string	The query along with the completed term.
text	string	The completed term.

AutocompleteMode

Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context in producing autocomplete terms.

Name	Type	Description
oneTerm	string	Only one term is suggested. If the query has two terms, only the last term is completed. For example, if the input is 'washington medic', the suggested terms could include 'medicaid', 'medicare', and 'medicine'.
oneTermWithContext	string	Completes the last term in a query with two or more terms, where the last two terms are a phrase that exists in the index. For example, if the input is 'washington medic', the suggested terms could include 'washington medicaid' and 'washington medical'.
twoTerms	string	Matching two-term phrases in the index will be suggested. For example, if the input is 'medic', the suggested terms could include 'medicare coverage' and 'medical assistant'.

AutocompleteRequest

Parameters for fuzzy matching, and other autocomplete query behaviors.

Name	Type	Description
autocompleteMode	AutocompleteMode	Specifies the mode for Autocomplete. The default is 'oneTerm'. Use 'twoTerms' to get shingles and 'oneTermWithContext' to use the current context while producing auto-completed terms.
filter	string	An OData expression that filters the documents used to produce completed terms for the Autocomplete result.
fuzzy	boolean	A value indicating whether to use fuzzy matching for the autocomplete query. Default is false. When set to true, the query will autocomplete terms even if there's a substituted or missing character in the search text. While this provides a better experience in some scenarios, it comes at a performance cost as fuzzy autocomplete queries are slower and consume more resources.
highlightPostTag	string	A string tag that is appended to hit highlights. Must be set with highlightPreTag. If omitted, hit highlighting is disabled.
highlightPreTag	string	A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting is disabled.
minimumCoverage	number	A number between 0 and 100 indicating the percentage of the index that must be covered by an autocomplete query in order for the query to be reported as a success. This parameter can be useful for ensuring search availability even for services with only one replica. The default is 80.
search	string	The search text on which to base autocomplete results.
searchFields	string	The comma-separated list of field names to consider when querying for auto-completed terms. Target fields must be included in the specified suggester.
suggesterName	string	The name of the suggester as specified in the suggesters collection that's part of the index definition.
top	integer	The number of auto-completed terms to retrieve. This must be a value between 1 and 100. The default is 5.

AutocompleteResult

The result of Autocomplete query.

Name	Type	Description
@search.coverage	number	A value indicating the percentage of the index that was considered by the autocomplete request, or null if minimumCoverage was not specified in the request.
value	AutocompleteItem[]	The list of returned Autocompleted items.

SearchError

Describes an error condition for the API.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	SearchError[]	An array of details about specific errors that led to this reported error.
message	string	A human-readable representation of the error.

Share via