Suggestions (Azure Search Service REST API)

A Suggestions request is a "search-as-you-type" query consisting of a partial string input (three character minimum). It returns matching text found in suggester-aware fields. Azure Search looks for matching values in fields that are predefined in a Suggester. For example, if you enable suggestions on a city field, typing "sea" produces documents containing "Seattle", "Sea Tac", and "Seaside" (all actual city names) for that field.

The results of this operation return a list of suggested text from matching documents, plus the document key. If matching text is identical across documents, the suggested text is repeated. To improve the structure of results, consider using the $select filter to return additional fields that provide more differentiation and context.

This request is different than a Search API request. In application code, you might bind a suggestions call to keyboard input, and a search call to a search button.

A Suggestions operation is issued as a GET or POST request.

GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]  
api-key: [admin key]  
POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
Content-Type: application/json  
api-key: [admin or query key]  

When to use POST instead of GET

When you use HTTP GET to call Suggestions, the length of the request URL cannot exceed 8 KB. This length is usually enough for most applications. However, some applications produce very large queries, specifically when OData filter expressions are used. For these applications, HTTP POST is a better choice because it allows larger filters than GET. With POST, the number of clauses in a filter is the limiting factor, not the size of the raw filter string since the request size limit for POST is approximately 16 MB.

Note

Even though the POST request size limit is very large, filter expressions cannot be arbitrarily complex. For more information about filter complexity limitations, see OData Expression Syntax for Azure Search.

Request

HTTPS is required for service requests. The Suggestions request can be constructed using the GET or POST methods.

The request URI specifies the name of the index to query. Parameters, such as the partially input search term, are specified on the query string in the case of GET requests, and in the request body in the case of POST requests.

As a best practice when creating GET requests, remember to URL-encode specific query parameters when calling the REST API directly. For Suggestions operations, this includes:

  • $filter

  • highlightPreTag

  • highlightPostTag

  • search

    URL encoding is only recommended on the above query parameters. If you inadvertently URL-encode the entire query string (everything after the ?), requests will break.

    Also, URL encoding is only necessary when calling the REST API directly using GET. No URL encoding is necessary when calling Suggestions using POST, or when using the Azure Search .NET client library handles URL encoding for you.

Query Parameters

Suggestions accepts several parameters that provide query criteria and also specify search behavior. You provide these parameters in the URL query string when calling Suggestions via GET, and as JSON properties in the request body when calling Suggestions via POST. The syntax for some parameters is slightly different between GET and POST. These differences are noted in the following table.

Parameter Description
search=[string] The search text to use to suggest queries. Must be at least 1 character, and no more than 100 characters.
highlightPreTag=[string] (optional, defaults to an empty string) A string tag that prepends to search hits. Must be set with highlightPostTag. Note: When calling Suggestions using GET, the reserved characters in the URL must be percent-encoded (for example, %23 instead of #).
highlightPostTag=[string] (optional, defaults to an empty string) A string tag that appends to search hits. Must be set with highlightPreTag. Note: When calling Suggestions using GET, the reserved characters in the URL must be percent-encoded (for example, %23 instead of #).
suggesterName=[string] The name of the suggester as specified in the suggesters collection that's part of the index definition. A suggester determines which fields are scanned for suggested query terms. See Suggesters for more information.
fuzzy=[boolean] (optional, default = false) When set to true, this API finds suggestions even if there is 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.
searchFields=[string] (optional) The list of comma-separated field names to search for the specified search text. Target fields must be enabled for suggestions.
$top=# (optional, default = 5) The number of suggestions to retrieve. The value must be a number between 1 and 100. Note: When calling Suggestions using POST, this parameter is named top instead of $top.
$filter=[string] (optional) An expression that filters the documents considered for suggestions. Note: When calling Suggestions using POST, this parameter is named filter instead of $filter.
$orderby=[string] (optional) A list of comma-separated expressions to sort the results by. Each expression can be either a field name or a call to the geo.distance() function. Each expression can be followed by asc to indicated ascending, and desc to indicate descending. The default is ascending order. There is a limit of 32 clauses for $orderby. Note: When calling Suggestions using POST, this parameter is named orderby instead of $orderby.
$select=[string] (optional) A list of comma-separated fields to retrieve. If unspecified, only the document key and suggestion text is returned. You can explicitly request all fields by setting this parameter to *. Note: When calling Suggestions using POST, this parameter is named select instead of $select.
minimumCoverage (optional, defaults to 80) A number between 0 and 100 indicating the percentage of the index that must be covered by a suggestions query in order for the query to be reported as a success. By default, at least 80% of the index must be available or the Suggest operation returns HTTP status code 503. If you set minimumCoverage and Suggest succeeds, it returns HTTP 200 and include a @search.coverage value in the response indicating the percentage of the index that was included in the query. Note: Setting this parameter to a value lower than 100 can be useful for ensuring search availability even for services with only one replica. However, not all matching suggestions are guaranteed to be present in the search results. If search recall is more important to your application than availability, then it's best not to lower minimumCoverage below its default value of 80.
api-version=[string] The api-version parameter is required. See API versions in Azure Search for details. For this operation, the api-version is specified as a query parameter in the URL regardless of whether you call Suggestions with GET or POST.

Request Headers

The following table describes the required and optional request headers

Request Header Description
api-key The api-key is used to authenticate the request to your Search service. It is a string value, unique to your service URL. The Suggestions request can specify either an admin-key or query-key as the api-key. The query-key is used for query-only operations.

You will also need the service name to construct the request URL. You can get the service name and api-key from your service dashboard in the Azure Preview Portal. See Create an Azure Search service in the portal for page navigation help.

Request Body

For GET: None.

For POST:

{  
      "filter": "odata_filter_expression",  
         "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
         "suggesterName": "suggester_name",  
      "top": # (default 5)  
    }  

Response

Status Code: "200 OK" is returned for a successful response.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}  

If the projection option is used to retrieve fields, they are included in each element of the array:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}  

Example

Retrieve 5 suggestions where the partial search input is 'lux':

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2016-09-01  
POST /indexes/hotels/docs/suggest?api-version=2016-09-01  
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }  

Notice that suggesterName is required in a Suggestions operation.

See also

Azure Search Service REST
HTTP status codes (Azure Search)
Suggesters
Azure Search .NET SDK