Documents - Suggest Post

Reference

Service:: Search Service

API Version:: 2024-07-01

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

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?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 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	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	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	Response containing suggested documents that match the partial input.
Other Status Codes	ErrorResponse	Error response.

Examples

SearchIndexSuggestDocumentsPost

Sample request

HTTP

POST https://myservice.search.windows.net/indexes('myindex')/docs/search.post.suggest?api-version=2024-07-01

{
  "filter": "rating gt 4.0",
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "rating desc",
  "search": "hote",
  "searchFields": "title",
  "select": "docId,title,description",
  "suggesterName": "sg",
  "top": 10
}

Sample response

Status code:: 200

{
  "value": [
    {
      "@search.text": "Nice <em>Hotel</em>",
      "description": "Cheapest hotel in town",
      "docId": "1",
      "title": "Nice Hotel"
    },
    {
      "@search.text": "Fancy <em>Hotel</em>",
      "description": "Best hotel in town",
      "docId": "2",
      "title": "Fancy Hotel"
    }
  ]
}

Definitions

Name	Description
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
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.

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.

SuggestDocumentsResult

Response containing suggestion query results from an index.

Name	Type	Description
@search.coverage	number	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

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	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	The number of suggestions to retrieve. This must be a value between 1 and 100. The default is 5.

SuggestResult

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