Configuring auto-completion data sets

There are several types of auto-completion data sets that are supported.

Before the Concierge widget can be added to a search one or more auto-completion data sets must be generated or configured. A data set will generally correspond to a column of auto-completion suggestions that is returned to the user.

The Concierge widget supports combinations of the following:

  • up to one simple auto-completion data set

  • up to one recent searches auto-completion data set

  • zero or more structured auto-completion data sets

  • In practice limitations with your search user interface will limit the total number of data sets to about four because that is all that will fit on the screen.

  • Each additional data set added to concierge will add a request to your Funnelback server for each keystroke entered into a search box so consider the impact on your server performance when making heavy use of multiple auto-completion data sets.

Simple auto-completion

Simple auto-completion is generated from the words contained within the document content and is based upon:

  • The spelling index generated for a data source

  • Link labels (e.g. <a href="...">Link label</a>)

  • Queries associated with clicks

The suggestions comprise of single words or short phrases that match the partially entered query.

Simple auto-completion is generated automatically by default for every results page that exists on a search package, and auto-completion suggestions are scoped to the set of words that apply to the results that is being queried (the the results page configuration scopes the set of pages it covers).

Simple auto-completion options

Partial matching support

The partials option will produce an index that supports word matches from the start of words within an auto-completion phrase. Enable partial matching support by setting the -partials build_autoc option.

e.g. When -partials is enabled, auto-completion of Funnelback search engine will be triggered by a person starting to type Funnelback, search or engine. With -partials not set then the suggestion will only trigger when someone starts to type Funnelback.

partial matching support only applies to simple auto-completion and is not applied to the triggers defined in any CSV based auto-completion.

Preventing words from appearing as simple auto-completion suggestions

The spelling suggestions index is used to provide the set of words for simple auto-completion.

The spelling suggestion blacklist can be used to prevent specific words from being presented as auto-completion suggestions.

Adding words to simple auto-completion

The spelling suggestion whitelist can be used to configure specific words or phases to add to the set of suggestions, with higher than normal weightings.

Simple auto-completion scope

Simple auto-completion will be automatically scoped for each results page to prevent the suggesting of queries that would show no results for that results page. This works using the query processor options specified in the results page configuration.

If a results page configuration contains scoping query processor options such as gscopes, auto-completion suggestions are only generated for queries that return results once that scoping is applied.

Structured auto-completion

Structured auto-completion is generated from CSV data that is defined in Funnelback’s auto-completion CSV format.

If you wish to have partial trigger matching for CSV based suggestions you need to include additional rows in the CSV file for each entry with triggers modified so that they left match. e.g. if you have a trigger of Funnelback search engine then you should create additional CSV rows that have triggers of search engine and engine so that you get a similar partial matching behaviour.

The CSV data can be created in a number of different ways.

Manually edited via the search dashboard

To manually edit the auto-completion CSV file:

  1. Log in to the search dashboard and locate the search package that includes the results page where the auto-completion CSV should be created.

  2. Mange the configuration for the search package and select the perl file manager.

  3. In the file manager locate the heading that has the results page name (preview). If you are using the default results page then this will be the Profile: _default (preview) heading.

  4. Create (or edit) the auto_completion.csv file. CSV data needs to be entered in valid auto-completion CSV format. Save (and publish) your changes once you have finished editing.

  5. A reindex is required to generate the updated auto-completion, or it will automatically generate the next time the search updates.

Downloading the auto-completion CSV from a URL

The auto-completion.source.csv.[name].url can be used to define a URL where a valid auto-completion CSV file can be downloaded during an update.

  1. Do whatever is required to produce an auto-completion CSV file that will be delivered when you access a web URL. This could be a static CSV file downloaded from a website, or dynamically generated when the URL is accessed. Whatever is returned when the URL is accessed must be in valid auto-completion CSV format.

  2. Log in to the search dashboard and locate the results page that corresponds to the auto-completion data set profile.

  3. Edit the results page configuration and add the following:

     auto-completion.source.csv.example.url=http://example.com/path/to/auto-completion.csv
  4. A reindex is required to generate the updated auto-completion, or it will automatically generate the next time the search updates.

Generating structured auto-completion from the search index

Metadata and content within the Funnelback search index can be used to produce the auto-completion CSV using the auto-completion CSV plugin.

e.g. if you have a staff search you could produce staff auto-completions based on the individual staff records.

To use the auto-completion plugin to generate the auto-completion CSV:

  1. Create a new results page on your search package that will be used as an auto-completion source. You may require multiple results pages for this purpose if you wish to have multiple auto-completion data sets

    e.g. for an intranet you might wish to have 3 data sets - general suggestions (organic), staff (structured) and policies (structured). For this scenario you would require two results pages to generate the two structured data sets.

  2. Enable the auto-completion plugin on the results page that you created for auto-completion by switching on the auto-completion plugin from the extensions section, or by setting the following in the results page configuration:

     plugin.auto-completion-plugin.enabled=true
     plugin.auto-completion-plugin.version=2.0.1
    You should always use the latest available version of the plugin and refer to the accompanying plugin documentation as this will include bug fixes and additional functionality.
  3. Configure the auto-completion triggers by setting the plugin.auto-completion-plugin.config.triggers in the profile configuration. The value should be one or more JSON paths (comma separated) corresponding to the result item in the data model response. e.g. plugin.auto-completion-plugin.config.triggers=/title,/listMetadata/subject

  4. (opt) If you wish to have partial matching apply to the trigger enable partial trigger matching by setting plugin.auto-completion-plugin.config.trigger-expansion to true. Auto-completion triggers always match from the left of the trigger. Enabling partial trigger matching will enable auto-completion to match each word in a multi-word trigger. e.g. A trigger of information security policy would normally only be suggested if a user started to type the word information. When you enable partial trigger matching the suggestion can also be triggered if a user starts to type security or policy.

  5. (opt) Configure the auto-completion action type by setting plugin.auto-completion-plugin.config.action-type in the profile configuration. This should be set to either U (go to the URL of the item when you click the suggestion) or Q (run a query for the suggestion when you click on the suggestion). U is the default.

  6. (opt) Restrict the suggestions to be from specified data sources by setting plugin.auto-completion-plugin.config.data-sources in the profile configuration. By default, results will be sourced from all data sources in the search package. Possible values should be a comma separated list of data source ids which are also part of the search packages' meta.components.

     plugin.auto-completion-plugin.config.data-sources=exampleorg~ds-staff
    By default, a result-page contains organic spelling suggestions. If you are seeing unexpected extra suggestions after using this plugin scoped to a data-source, consider also setting the following key to blank: auto-completion.source=
  7. Configure the display object by setting plugin.auto-completion-plugin.config.display-fields to a comma separated list of Json paths corresponding to fields that should be returned. The display object is returned in the disp element of the auto-completion JSON response (by suggest.json). The fields returned in the display object can be used in the search result template to display the auto-completion suggestion.

     plugin.auto-completion-plugin.config.display-fields=/title,/listMetadata/firstName
  8. (opt) Configure a category display group for the suggestion by setting plugin.auto-completion-plugin.config.category in the profile configuration. The category can be only sourced from a metadata field and only first value will be used.

     plugin.auto-completion-plugin.config.category=/listMetadata/category
After you enable this plugin or change any of configuration values you need to re-index your data source in order for the auto-completion suggestions to be generated.

Configuring a CSV data source

  1. Open the search dashboard and select the search package on which you would like to configure auto-completion.

  2. Create a results page for each CSV auto-completion source that you wish to add as an auto-completion data set to concierge.

    e.g. Consider a web search where you would like to provide 3 columns of auto-completion - a simple auto-completion source based on words in the index, and two additional columns based on CSV data - say people and products. To do this requires simple auto-completion to be generated on the main results page and two additional results pages created to handle the structured auto-completion data sets. Create two results pages, people-ac and products-ac.

  3. Select Edit results page configuration and set auto-completion.source to csv. This ensures that the auto-completion that is built for this results page / data set will include only the CSV based suggestions.

  4. Check that the auto-completion is generated by viewing the search package log file. There should be a Step-BuildAutoCompletion.<results-page-name>.log for each of the results pages you have created e.g. Step-BuildAutoCompletion.people-ac.log. This log file provides information on the number of auto-completion suggestions that were added, and will also report if the CSV had any incorrect lines.

Recent searches

When search sessions are enabled, Funnelback can be configured to return recent searches as an auto-completion source.

The sessions and history functionality within Funnelback requires the Javascript for the sessions and history functionality to be included in your front end design. This happens by default if you are using the default Freemarker template included with Funnelback.

The recent search keywords along with the number of results are returned as a list of suggestions under the recent searches heading.

Configuring recent searches in auto-completion

Add the following to the results page configuration of the main search (not the auto-completion specific results pages created to generate the CSV):

# Enable sessions functionality.
ui.modern.session=true
# Enable recent searches in auto-completion
ui.modern.session.search_history.suggest=true
# (opt) Set template for display of suggestions.
ui.modern.session.search_history.suggest.display_template={query} ({totalMatching})
# (opt) Set category name (def: recent searches)
ui.modern.session.search_history.suggest.category=Recent searches