Query Suggestion Service /suggest Protocol
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:
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.
|
For more information, see Providing Query Suggestions in Creating the Search Experience.
Query Suggestion JavaScript Variables
After enabling query suggestion, the show_suggest XSLT variable is set to 1 and the JavaScript variables become usable in the XSLT stylesheet.
<xsl:variable name="show_suggest">1</xsl:variable>
The query suggestion features supports the following JavaScript variables in the XSLT stylesheet.
ss_allow_non_query
A true or false flag used by the os (OpenSearch) and rich output formats to suppress user-added results. This variable eliminates user-added results from the suggestions, while retains those based on popularity among other users’ queries.
Default value: true
ss_form_element
The value of the attribute id of the <form> used for the search box. This variable must be overwritten with the correct value when using suggest in a custom form outside of the search appliance, but still using the existing JavaScript client. If this parameter is incorrect, AJAX calls aren’t sent.
The XSLT spreadsheet sets this variable as:
var ss_form_element = ’suggestion_form’;
The form request occurs under the following XSLT condition (wrapped for readability):
<xsl:when test="$show_suggest = ’1’ and (($type = ’home’)
or ($type = ’std_top’))">
<xsl:text disable-output-escaping="yes"><form id="suggestion_form"
name="gs" method="GET" action="search"
onsubmit="return (this.q.value == ’’) ? false : true;"</xsl:text>
</xsl:when>
Default value: suggestion_form
ss_g_max_to_display
ss_g_more_names_to_display
Default value: Suggestions
ss_g_one_name_to_display
Default value: Suggestion
ss_max_to_display
The total number of rows allowed in the suggestion box. The smaller of ss_max_to_display and ss_g_max_to_display takes effect in limiting the number of suggestions.
ss_non_query_empty_title
If a user-added results entry’s title is missing or is an empty string, this value is used. This is a token that you can internationalize in the XSLT stylesheet. Set this value to Unknown, Noname, --- , or anything that can be visually shown. Otherwise, the empty string becomes an element that introduces confusion, as the user may not know whether it is a suggestion or just a separation line. The default value listed in the next column is for the English language version. The value is internationalized and the actual value depends on the current language setting.
Default value: No Title
ss_popup_element
The value of the attribute id of the <table> as the placeholder for search suggestions. The <table> initially is empty, and is positioned beneath the search box, aligned to the left. If the <table> HTML code is incorrect, suggestion results do not display. The default value is:
var ss_popup_element = ’search_suggest’;
For an example of the search_suggest in a table, see Query Suggestion Table Class.
Default value: search_suggest
ss_protocol
|
Provides backward compatibility with the version 6.0 query suggestion feature for the token and max_matches variables. This setting excludes user-added results from the response. If an unknown format is set, legacy is assumed. |
|
Default value: rich
Query Suggestion CSS Classes in the XSLT Stylesheet
Programs can change the following areas of the suggestion display using CSS:
|
Suggestion box table row <tr> when an entry is not selected. |
||
|
Suggestion box table row <tr> when an entry is selected. |
||
|
Suggestion box table cell <td>. This class affects all suggestion entries. |
||
|
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. |
||
Query Suggestion Table Class
The .ss_gac_m CSS class provides the style for the <table> element whose id value is referenced by the JavaScript ss_popup_element variable:
<table cellpadding="0" cellspacing="0" class="ss-gac-m"
style="width: 365px; visibility: hidden;" id="search_suggest"></table>
Query Suggestion Requests and Responses
The output format controls the query suggestion request and response:
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.
|
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. |
||
|
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 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. |
/suggest?token=<query>&max_matches=<num>&use_similar=0
[ "<term 1>", "<term 2>", ..., "<term n>" ]
[]
OpenSearch Format
The os format uses the OpenSearch protocol.
|
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. |
||
|
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. |
10 (matches) |
|
|
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. |
||
/suggest?q=<query>&max=<num>&site=<collection>&client=<frontend>&
format=os
[
"<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:
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.
|
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. |
||
|
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. |
10 (matches) |
|
|
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. |
||
/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": [] }