Documents - Autocomplete Post

  • Reference
Service:
Search Service
API Version:
2024-07-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=2024-07-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

ErrorResponse

Error response.

Examples

SearchIndexAutocompleteDocumentsPost

Sample request

POST https://myservice.search.windows.net/indexes('myindex')/docs/search.post.autocomplete?api-version=2024-07-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.
ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
ErrorResponse

Error response

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.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.
type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.
code

string

The error code.
details

ErrorDetail[]

The error details.
message

string

The error message.
target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.