Documents - Suggest Post

Service:: Search Service

API Version:: 2025-11-01-preview

Suggests documents in the index that match the given partial query text.

POST https:///indexes('{indexName}')/docs/search.post.suggest?api-version=2025-11-01-preview

URI Parameters

Name	In	Required	Type	Description
indexName	path	True	string	The name of the index.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Header

Name	Required	Type	Description
Accept	True	Accept	The Accept header.
x-ms-client-request-id		string (uuid)	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name	Required	Type	Description
search	True	string	The search text to use to suggest documents. Must be at least 1 character, and no more than 100 characters.
suggesterName	True	string	The name of the suggester as specified in the suggesters collection that's part of the index definition.
filter		string	An OData expression that filters the documents considered for suggestions.
fuzzy		boolean	A value indicating whether to use fuzzy matching for the suggestion query. Default is false. When set to true, the query will find suggestions 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 suggestion searches 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 of suggestions is disabled.
highlightPreTag		string	A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting of suggestions is disabled.
minimumCoverage		number (double)	A number between 0 and 100 indicating the percentage of the index that must be covered by a suggestion 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.
orderby		string	The comma-separated list of OData $orderby expressions by which to sort the results. Each expression can be either a field name or a call to either the geo.distance() or the search.score() functions. Each expression can be followed by asc to indicate ascending, or desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no $orderby is specified, the default sort order is descending by document match score. There can be at most 32 $orderby clauses.
searchFields		string	The comma-separated list of field names to search for the specified search text. Target fields must be included in the specified suggester.
select		string	The comma-separated list of fields to retrieve. If unspecified, only the key field will be included in the results.
top		integer (int32)	The number of suggestions to retrieve. This must be a value between 1 and 100. The default is 5.

Responses

Name	Type	Description
200 OK	SuggestDocumentsResult	The request has succeeded.
Other Status Codes	ErrorResponse	An unexpected error response.

Security

api-key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes

Name	Description
https://search.azure.com/.default

Examples

SearchIndexSuggestDocumentsPost

Sample request

HTTP

POST https:///indexes('preview-test')/docs/search.post.suggest?api-version=2025-11-01-preview


{
  "filter": "ownerId eq 'sam' and id lt '15'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "id desc",
  "search": "p",
  "searchFields": "category",
  "select": "id,name,category,ownerId",
  "suggesterName": "sg",
  "top": 10
}

Sample response

Status code:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "@search.text": "<em>pu</em>rple",
      "id": "14",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "13",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "11",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "1",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    }
  ]
}

Definitions

Name	Description
Accept	The Accept header.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
SuggestDocumentsResult	Response containing suggestion query results from an index.
SuggestRequest	Parameters for filtering, sorting, fuzzy matching, and other suggestions query behaviors.
SuggestResult	A result containing a document found by a suggestion query, plus associated metadata.

Accept

Enumeration

The Accept header.

Value	Description
application/json;odata.metadata=none

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info		The additional info.
type	string	The additional info type.

ErrorDetail

Object

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

Object

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).

Name	Type	Description
error	ErrorDetail	The error object.

SuggestDocumentsResult

Object

Response containing suggestion query results from an index.

Name	Type	Description
@search.coverage	number (double)	A value indicating the percentage of the index that was included in the query, or null if minimumCoverage was not set in the request.
value	SuggestResult[]	The sequence of results returned by the query.

SuggestRequest

Object

Parameters for filtering, sorting, fuzzy matching, and other suggestions query behaviors.

Name	Type	Description
filter	string	An OData expression that filters the documents considered for suggestions.
fuzzy	boolean	A value indicating whether to use fuzzy matching for the suggestion query. Default is false. When set to true, the query will find suggestions 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 suggestion searches 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 of suggestions is disabled.
highlightPreTag	string	A string tag that is prepended to hit highlights. Must be set with highlightPostTag. If omitted, hit highlighting of suggestions is disabled.
minimumCoverage	number (double)	A number between 0 and 100 indicating the percentage of the index that must be covered by a suggestion 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.
orderby	string	The comma-separated list of OData $orderby expressions by which to sort the results. Each expression can be either a field name or a call to either the geo.distance() or the search.score() functions. Each expression can be followed by asc to indicate ascending, or desc to indicate descending. The default is ascending order. Ties will be broken by the match scores of documents. If no $orderby is specified, the default sort order is descending by document match score. There can be at most 32 $orderby clauses.
search	string	The search text to use to suggest documents. Must be at least 1 character, and no more than 100 characters.
searchFields	string	The comma-separated list of field names to search for the specified search text. Target fields must be included in the specified suggester.
select	string	The comma-separated list of fields to retrieve. If unspecified, only the key field will be included in the results.
suggesterName	string	The name of the suggester as specified in the suggesters collection that's part of the index definition.
top	integer (int32)	The number of suggestions to retrieve. This must be a value between 1 and 100. The default is 5.

SuggestResult

Object

A result containing a document found by a suggestion query, plus associated metadata.

Name	Type	Description
@search.text	string	The text of the suggestion result.

Share via

Documents - Suggest Post

URI Parameters

Request Header

Request Body

Responses

Security

api-key

OAuth2Auth

Scopes

Examples

SearchIndexSuggestDocumentsPost

Sample request

Sample response

Definitions

Accept

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

SuggestDocumentsResult

SuggestRequest

SuggestResult