Help Center

Menu

Extra searches

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 for 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.

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. However, 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 search package 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 IDs to run. Each extra search ID must be configured by adding a pair of corresponding configuration keys: ui.modern.extra_searches.ID.source and ui.modern.extra_searches.ID.query_processor_options.

For example to return additional results from the staff_directory and intranet when a user searches documentation content:

  1. Edit the configuration for the search package containing the documentation results page and set ui.modern.extra_searches=staff,intra. Note: the IDs used here can be set to any text identifier, but the IDs must match the IDs used in the corresponding source and query processor option configuration keys.

    This specifies that the two extra searches staff and intra should be run whenever a search is processed on the documentation results page.

  2. Configure the staff and intra extra searches by creating two additional configuration options for each extra search. These keys must be defined on the same search package where the ui.modern.extra_searches is set. These keys, ui.modern.extra_searches.staff.source, ui.modern.extra_searches.staff.query_processor_options, ui.modern.extra_searches.intra.source and ui.modern.extra_searches.intra.query_processor_options are created from the search package’s configuration editor.

  3. Set these additional keys as follows:

    • ui.modern.extra_searches.ID.source to the search package or data source where the extra search should run.

    • ui.modern.extra_searches.ID.query_processor_options to any query processor options in addition to the ones already configured in search package or data source’s configuration keys.

      For the above example four additional keys would be required:

      ui.modern.extra_searches.staff.source=example~ds-people
ui.modern.extra_searches.staff.query_processor_options=-num_ranks=3
ui.modern.extra_searches.intra.source=example~ds-intranet
ui.modern.extra_searches.intra.query_processor_options=-num_ranks=5

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 Freemarker templates

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>

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 Map URL parameters plugin.

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

Per-result extra searches are only available when using Freemarker templates. Integrations with Funnelback JSON or XML 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.

The Freemarker templating 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 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 ID of the source 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_author) is set to the author of the current result. Ensure that title (title) and description (description) metadata are returned with the extra search results.

<@fb.ExtraSearch collection="other_collection" question=question query="!padrenull" params={"meta_author_sand":"${s.result.metaData['author']}","SF":"[title,description]"}>
    <#-- Freemarker code to process the extra search result set -->
</@fb.ExtraSearch>
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>
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.

See also