Search Protocol Reference

Query Suggestion Service /suggest Protocol

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:

  1. The search appliance sets the XSLT stylesheet element show_suggest element:
    <xsl:variable name="show_suggest">1</xsl:variable>
  2. The search appliance provides access to the http:// Search_Appliance /ss.js JavaScript file. The ss.js file is for version 6.2 and later only, the version 6.0 uses the suggest_js.js file.
  3. 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.

Back to top

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

.ss_gac_a

Suggestion box table row <tr> when an entry is not selected.

1

.ss_gac_b

Suggestion box table row <tr> when an entry is selected.

2

.ss_gac_c

Suggestion box table cell <td>. This class affects all suggestion entries.

3

.ss_gac_d

Suggestion box table cell <td>. This class is defined by the ss_g_more_names_to_display and ss_g_one_name_to_display XSLT variables.

4

.ss_gac_e

Suggestion box last table row <tr>.

Back to top

Query Suggestion Requests and Responses

The output format controls the query suggestion request and response:

Back to top

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

callback

Provides a JSONP compatible response from suggest. If you set callback=test, it will return:


/* GSA Suggest Service JSONP Response. */test(<WHAT WAS SUPPOSED TO BE RETURNED>);

The prefix /* GSA Suggest Service JSONP Response. */ is hard-coded in the response to safeguard against cross-site scripting attacks on the JSONP callback name. You must remove the prefix before the response can be parsed by JavaScript.

  

client

Front end name.

default_frontend

format

The output format in which the client wants the results.

legacy

max_matches

The maximum number of results that the suggest server should return. The minimum is 0, which indicates that the server should return an empty set, however this result would not be meaningful.

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.

10

site

Collection name.

default_collection

token

The partial query string that a user enters in the search box. The minimum size is one character. If set to 0, that is, if the search box is empty, then the suggest client side JavaScript doesn’t send a request to query suggestion. Even if an administrator implements a custom interface, sending an empty token returns an empty set as the result. The maximum size of the token parameter is not defined.

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

callback

Provides a JSONP compatible response from suggest. If you set callback=test, it will return:


/* GSA Suggest Service JSONP Response. */test(<WHAT WAS SUPPOSED TO BE RETURNED>);

The prefix /* GSA Suggest Service JSONP Response. */ is hard-coded in the response to safeguard against cross-site scripting attacks on the JSONP callback name. You must remove the prefix before the response can be parsed by JavaScript.

  

client

Front end name.

default_frontend

format

The output format in which the client wants the results.

os

max

The maximum number of results that the suggest server should return. The minimum is 0, which indicates that the server should return an empty set, however this result would not be meaningful.

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.

10 (matches)

q

The partial query string that a user enters in the search box. The minimum size is one character. If set to 0, that is, if the search box is empty, then the suggest client side JavaScript doesn’t send a request to query suggestion. Even if an administrator implements a custom interface, sending an empty token returns an empty set as the result. The maximum size of the token parameter is not defined.

None

site

Collection name.

default_collection

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

callback

Provides a JSONP compatible response from suggest. If you set callback=test, it will return:

/* GSA Suggest Service JSONP Response. */test(<WHAT WAS SUPPOSED TO BE RETURNED>);

The prefix /* GSA Suggest Service JSONP Response. */ is hard-coded in the response to safeguard against cross-site scripting attacks on the JSONP callback name. You must remove the prefix before the response can be parsed by JavaScript.

  

client

Front end name.

default_frontend

format

The output format in which the client wants the results.

rich

max

The maximum number of results that the suggest server should return. The minimum is 0, which indicates that the server should return an empty set, however this result would not be meaningful.

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.

10 (matches)

q

The partial query string that a user enters in the search box. The minimum size is one character. If set to 0, that is, if the search box is empty, then the suggest client side JavaScript doesn’t send a request to query suggestion. Even if an administrator implements a custom interface, sending an empty token returns an empty set as the result. The maximum size of the token parameter is not defined.

None

site

Collection name.

default_collection

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": [] }

Back to top

Was this helpful?
How can we improve it?