UI.modern.extra_searches

Configure extra searches to be aggregated with the main result data, when using the Modern UI.

Key: ui.modern.extra_searches
Type: List<String>
Can be set in: collection.cfg

Description

Funnelback has the ability to run a series of extra searches in parallel with the main search, with the extra results data added to the data model for use in the search results display.

The extra searches can be run against any collection that exists on the Funnelback server, and it is possible via the extra searches hook script to modify the query that is submitted to each extra search that is run.

For example: an extra search could be used on an all of university search to pull in additional results for staff members and videos and display these alongside the results from the main search. The formatting of the extra results can be controlled per extra search and is not limited to a list of search result links, so staff results might be presented in a box to the right of the results and any video results returned via a JavaScript plugin that is configured dynamically when the page is generated.

Standard extra searches

Standard extra searches in Funnelback run additional searches in parallel with the main query with the set of extra searches determined on a per-search basis.

Extra searches vs meta collections

The functionality provided by extra searches can sometimes be confused with that provided by meta collections. While both will bring in results from different collections the main difference is that an extra search is a completely separated set of search results from the main result set.

A meta collection searches across multiple repositories or sub-collections and merges all the results into a single set of results.

An extra search on a collection runs a secondary search providing an additional set of search results and corresponding data model object. This data model object contains a separate question and response object, just as for the main search.

A similar outcome could be achieved by running a secondary search via Ajax from the search results page to populate a secondary set of result such as a video carousel. Note however that the use of extra search within Funnelback is more efficient than making an independent request via a method such as Ajax.

Configuring extra searches

The ui.modern.extra_searches collection configuration setting is used to specify the set of extra searches that should be run in parallel to the main query.

This parameter takes a comma-separated list of extra search services to query. Each search service must be configured in a separate configuration file named extra_search.<service name>.cfg.

For example to aggregate the results from the staff_directory and intranet collections when a user searches the documentation collection:

Edit the collection.cfg for the documentation collection and set ui.modern.extra_searches=staff,intra. This specifies that the two extra searches staff and intra should be run whenever a search is processed on the documentation collection. The name of the search services doesn't need to match the collection names but does need to match the service name chosen when the configuration file defining the extra search was created.
Configure the staff and intra extra searches by creating two additional configuration files on the documentation collection. These files, extra_search.staff.cfg and extra_search.intra.cfg, can be created from the file manager.
In these configuration files, set:
- collection=[name of the target collection], such as collection=staff_directory or collection=intranet
- Set any specific query_processor_option values in addition to the ones already configured in each collection's collection.cfg.

Extra searches and the data model

Each extra search that runs will populate an element that matches the extra search name within the data model beneath the extraSearches node. e.g. for the above example it would populate a extraSearches.staff and extraSearches.intra elements.

Each extra search contains a question and response sub-element that applies to the extra search that is run.

Displaying extra search results in the template

In the search template use the <@fb.ExtraResults name="[service name]" /> tag to iterate over the results of each extra search source (i.e. <@fb.ExtraResults name="staff" /> or <@fb.ExtraResults name="intra" />). Standard tags can then be used within these to interact with the extra search's section in the data model:

<@fb.ExtraResults name="staff">
  <@s.Results>
    <#if s.result.class.simpleName != "TierBar">
      ${s.result.title}
      ...
    </#if>
  </@s.Results>
</@fb.ExtraResults>

Manipulating the extra search

When an extra search runs it uses a clone on the main search question which defines the set of parameters that are applied when the search runs. This means that the query for the main search will also be applied to the extra search.

The parameters that are applied when each extra search is run can be manipulated using the extra searches hook script (hook_extra_searches.groovy).

Examples

: remove selected input parameters from an extra search

Create a hook_extra_searches.groovy script on the collection that is being queried. This can be done using the file manager for the collection.
Loop through the inputParameterMap and remove each key found that matches meta_.

// Remove all metadata parameters for the staff extra search
if ( transaction.extraSearchesQuestions["staff"] != null ) {
    def searchQuestion = transaction.extraSearchesQuestions["staff"]   
    //remove all meta CGI parameters set on the main search  
    searchQuestion.inputParameterMap.each{ k, v -> 
        if (k.startsWith("meta_")){
            searchQuestion.inputParameterMap.remove(k); 
        }
    }
}

: conditionally run an extra search

For this example the extra searches are displayed unless there is a custom CGI parameter (showonly) set. When set, the value of showonly is used to determine which extra searches run. The extra searches in this example are named 'type1', 'type2' and 'type3'.

Create an hook_extra_searches.groovy script on the collection that is being queried containing the code below. This can be done using the file manager for the collection.

// If the showonly CGI param is set to display a single type of results disable the other extra searches.
if (transaction.question.inputParameterMap["showonly"] != null) {
        if (transaction.question.inputParameterMap["showonly"] == "type1") {
                if ( transaction.extraSearchesQuestions["type2"] != null ) {
                        transaction.extraSearchesQuestions.remove("type2")
                }
                if ( transaction.extraSearchesQuestions["type3"] != null ) {
                        transaction.extraSearchesQuestions.remove("type3")
                }
        }
        else if (transaction.question.inputParameterMap["showonly"] == "type2") {
                if ( transaction.extraSearchesQuestions["type1"] != null ) {
                        transaction.extraSearchesQuestions.remove("type1")
                }
                if ( transaction.extraSearchesQuestions["type3"] != null ) {
                        transaction.extraSearchesQuestions.remove("type3")
                }
        }
        else if (transaction.question.inputParameterMap["showonly"] == "type3") {
                if ( transaction.extraSearchesQuestions["type1"] != null ) {
                        transaction.extraSearchesQuestions.remove("type1")
                }
                if ( transaction.extraSearchesQuestions["type2"] != null ) {
                        transaction.extraSearchesQuestions.remove("type2")
                }
        }
}

Performance note

It is good practice to limit the number of extra searches run for any query otherwise performance of the search will be adversely affected. For good performance limit the number of extra searches to a maximum of 2 or 3.

Per-result extra searches

The Modern UI includes a feature that enables the running of an extra search for each result. This can be used to run a search to bring in additional content from a second index related to an item. For example in a university staff search a per results extra search might be used to return the publications authored by each staff member, which are then nested within the search result for that user.

This should not be confused with the per-search extra searches that are detailed above (using the ExtraResults macro).

Per-result extra searches are only available when using Freemarker templates. Direct integrations with Funnelback can implement per-result extra search by parsing the results returned by the initial search and constructing an additional set of searches based on the results.

Warning

Per result extra searches are expensive to run as an extra search is run independently for each result that is returned in the result set. Use of per result extra searches can have a large negative impact on search performance and should only be used in limited situations, where the number of results per page is small.

ExtraSearch macro

The ExtraSearch macro is used to configure and run an extra search, which is initiated by the Freemarker template.

When defining an extra search the following fields are available:

collection: this needs to be set to the collection ID of the collection against which the extra search will be run (mandatory).
query: this should be set to the query language string that defines the extra search (mandatory).
params: optional map of additional CGI parameters to pass to the extra search. This example will run an extra search against another collection for each search result using the title of the current result item as the query.

Run an extra search to return everything from other_collection, where the author metadata (meta_A) is set to the author of the current result. Ensure that title (t) and description (c) metadata are returned with the extra search results.

<@fb.ExtraSearch collection="other_collection" question=question query="!padrenull" params={"meta_A_sand":"${s.result.metaData['A']}","SF":"[t,c]"}>
    <#-- Freemarker code to process the extra search result set -->
</@fb.ExtraSearch>

Note: It is not possible to easily view the data model of pre-result extra searches (for example by inspecting the JSON or XML output) as the extra searches are run independently of the main search. If you wish to inspect the data model for an extra search then it is possible to print the extra search question and response variables in debugging output.

The following example shows the code required to print out search results from the extra search within each result of the main search:

<@s.Results>
    <#-- THIS IS A RESULT FROM THE MAIN SEARCH -->
    <#if s.result.class.simpleName != "TierBar">
        <#if s.result.title??>
            ${s.result.title}
            <@fb.ExtraSearch question=question collection="other_collection" query=s.result.title>
                <#--Extra search has same data model as normal search - you can access items in it in the same way.  question and response when used within the fb.ExtraSearch macro refer to the respective data model elements from the extra search.-->
                <!--DEBUG: Extra search question ${question} -->
                <!--DEBUG: Extra search response ${response} -->
                <#if response.resultPacket?size &gt; 0>
                    <#-- IF THE EXTRA SEARCH RESPONSE EXISTS -->

                    Print the URL of the item from the original search:
                    Parent URL: ${s.result.liveUrl}

                    <#if response.resultPacket.rmcs?size &gt; 0>
                        Iterate over the rmcs counts of the extra search
                        <#assign keys = response.resultPacket.rmcs?keys>
                        <#list keys as thes>

                        </#list>   
                    </#if>
                </#if>
            </@fb.ExtraSearch>
        </#if>
    </#if>
</@s.Results>

Tip: If you want to modify the query above (which is passing in s.result.title) you can create a variable before you call ExtraSearch (e.g. <#assign newquery = "A:\"+s.result.title+"\""> then call ExtraSearch with query=newquery

Faceted navigation will internally use extra searches. If you modify extra searches in groovy hook scripts, you may also need to modify the faceted navigation extra searches in the same way; otherwise, the counts and values may be inaccurately set. To do this, use the getEffectiveExtraSearchName() method on the transaction given to the groovy hook script.

For Example:

if("myExtraSearch".equals(transaction.getEffectiveExtraSearchName().orElse(""))) {
  // Modify the search transaction as though it is 'myExtraSearch'.
}