The query suggestion service provides suggestions that complete a user’s search query. As a user enters a query in the search box, a drop-down menu appears with suggestions to complete the query. The search appliance uses the most popular search queries of its users to determine the top suggestions that list for a query.
Only queries that returned results are used to build the database of query suggestions. Queries with special terms, such as inmeta:
, info:
, link:
, daterange:
, etc are excluded when building the database of query suggestions.
In addition, if activated, the search appliance adds user-added results to the list of suggestions.
For information on retrieving and updating the suggestion blacklist using Java and the Google Data API, see "Query Suggestion Blacklist" in the Administrative API Developer’s Guide: Java. For information on user-added results, see "Providing User Results" in Creating the Search Experience.
The following example shows query suggestions:

You can use the query suggestion feature to:
- Capture JSON response output from query suggestions and filter the information, before displaying suggestions to the user.
- Upload (and retrieve) a blacklist of bad words using the Google Data API, so that these words do not appear in the list of suggestions.
- Add information to a custom interface for search implementations that consume search results in XML form.
Enable the query suggestion client for a front end from Search > Search Features > Front Ends > Output Format > Search Box > Query suggestions.
The query suggestion service adds latest query data to its list of suggestions once every 24 hours. However you can force the service to pick up changes immediately by disabling and enabling the Query Suggestions checkbox. When you enable the checkbox, the suggest service is sent a HUP
signal so that it updates its data structure from the latest query logs.
Queries with Special Query Terms, such as inmeta, are excluded from the Query Suggestion database. So if this type of query is used extensively, then a possible solution is to use the equivalent Search Parameters, such as partialfields and requiredfields.
After enabling query suggestions:
- The search appliance sets the XSLT stylesheet element
show_suggest
element:<xsl:variable name="show_suggest">1</xsl:variable>
- The search appliance provides access to the
http://
Search_Appliance/ss.js
JavaScript file. Thess.js
file is for version 6.2 and later only, the version 6.0 uses thesuggest_js.js
file. - When a user starts a query, the JavaScript in the client makes calls to the query suggestion URI and fetches the results, responding with JSON output. The AJAX response handler in the JavaScript client populates the list of suggestions.
For more information, see "Providing Query Suggestions" in Creating the Search Experience.
Query Suggestion CSS Classes in the XSLT Stylesheet
Programs can change the following areas of the suggestion display using CSS:

Google Suggest provides the following CSS classes that correspond to the numbers in the illustration:
Area |
CSS Class |
Style Description |
---|---|---|
1 |
|
Suggestion box table row |
1 |
|
Suggestion box table row |
2 |
|
Suggestion box table cell |
3 |
|
Suggestion box table cell |
4 |
|
Suggestion box last table row |
Query Suggestion Requests and Responses
The output format controls the query suggestion request and response:
- Legacy Format--Backward compatibility with version 6.0 (see Legacy Format)
- OpenSearch Format--Supports the OpenSearch protocol (see OpenSearch Format)
- Rich Output Format--Version 6.2 and later default format (see Rich Output Format)
Legacy Format
The legacy
format is similar to the suggest feature in the version 6.0 search appliance. The token
and max_matches
were in version 6.0, and the client
, format
, and site
parameters were introduced in version 6.2.
Parameter |
Description |
Default Value |
---|---|---|
|
Provides a JSONP compatible response from suggest. If you set callback=test, it will return:
The prefix |
|
|
Front end name. |
|
|
The output format in which the client wants the results. |
|
|
The maximum number of results that the suggest server should return. The minimum is The maximum is not defined. If this parameter is not set, then the default value is 10 possible matches. If fewer suggestions are configured, then they are returned. |
|
|
Collection name. |
|
|
The partial query string that a user enters in the search box. The minimum size is one character. If set to |
None |
Request:
/suggest?token=<query>&max_matches=<num>&use_similar=0
Response:
[ "<term 1>", "<term 2>", ..., "<term n>" ]
Or, if no result:
[]
OpenSearch Format
The os
format uses the OpenSearch protocol.
Parameter |
Description |
Default Value |
---|---|---|
|
Provides a JSONP compatible response from suggest. If you set callback=test, it will return:
The prefix |
|
|
Front end name. |
|
|
The output format in which the client wants the results. |
|
|
The maximum number of results that the suggest server should return. The minimum is The maximum is not defined. If this parameter is not set, then the default value is 10 possible matches. If fewer suggestions are configured, then they are returned. |
|
|
The partial query string that a user enters in the search box. The minimum size is one character. If set to |
None |
|
Collection name. |
|
Request:
/suggest?q=<query>&max=<num>&site=<collection>&client=<frontend>& format=os
Response:
[ "<query>", [ "<term 1>", "<term 2>", ... "<term n>" ], [ "<content 1>", "<content 2>", ..., "<content n>" ], [ "<url 1>", "<url 2>", ..., "<url n>" ] ]
The client distinguishes between suggest and user-added results as follows:
- For suggest results, the term is non-empty while the content and the URL are empty.
- For user-added results, the term is empty, content is optional, and the URL is non-empty.
A client can choose to display both suggest and user-added results or just one of them. The default front end provided in the Admin Console’s XSLT stylesheet, displays both results. User-added results display after suggest results and appear in italics.
If no result occurs, the OpenSearch format provides the following response:
[ <query>, [] ]
Rich Output Format
The rich
format uses the rich protocol for search-as-you-type suggestions.
Parameter |
Description |
Default Value |
---|---|---|
|
Provides a JSONP compatible response from suggest. If you set callback=test, it will return:
The prefix |
|
|
Front end name. |
|
|
The output format in which the client wants the results. |
|
|
The maximum number of results that the suggest server should return. The minimum is The maximum is not defined. If this parameter is not set, then the default value is 10 possible matches. If fewer suggestions are configured, then they are returned. |
|
|
The partial query string that a user enters in the search box. The minimum size is one character. If set to |
None |
|
Collection name. |
|
Request:
/suggest?q=<query>&max=<num>&site=<collection>&client=<frontend>&format=rich
Response (wrapped for readability):
{ "query": "<query>", "results": [ { "name": "<term 1>", "type": "suggest"}, { "name": "<term 2>", "type": "suggest"}, { "name": "<term 3>", "type": "uar", "content": "Title of UAR", "moreDetailsUrl": "URL of UAR"} ..., ] }
Clients can distinguish between suggest and user-added results by looking at the type
. The type can be suggest
or uar
(user-added result) to identify the type of suggestion.
The style
value is reserved and not used in version 6.2. For suggest entries, a term must be present. For user-added results entries, moreDetailsUrl
must be present.
If no result occurs, the rich format provides the following response:
{ "query": <query>, "results": [] }