Documents - Suggest Post
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. |
index
|
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 |
Response containing suggested documents that match the partial input. |
|
Other Status Codes |
Error response. |
Examples
SearchIndexSuggestDocumentsPost
Sample request
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
{
"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 |
---|---|
Error |
The resource management error additional info. |
Error |
The error detail. |
Error |
Error response |
Suggest |
Response containing suggestion query results from an index. |
Suggest |
Parameters for filtering, sorting, fuzzy matching, and other suggestions query behaviors. |
Suggest |
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 |
The error additional info. |
|
code |
string |
The error code. |
details |
The error details. |
|
message |
string |
The error message. |
target |
string |
The error target. |
ErrorResponse
Error response
Name | Type | Description |
---|---|---|
error |
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 |
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. |