Templates for Solr search queries

You can define a template for search queries sent to the Solr search service. The search term entered by the user will be integrated into this template before the query is sent. This allows you to fine-tune the service’s behaviour individually.

Custom query templates can be used in smart.finder to include an entered search term in complex queries to the search service.

For configuration details, see Solr Queries and the documentation for the sf_store bundle.
Example with the default query template

By default, a query template is used that passes the entered search term to the search service more or less unchanged:

Input term: soil
Search query: full_text:soil

The field full_text is designated for a full text search. Translated, this query reads: "Search all documents containing the term `soil`".

The default query template for smartfinder is defined as follows:

{$field}:{$value}
Example with a user defined query template

If a query template is used, the search query can be customized to search on multiple fields, where each field is has an individual weight value assigned. Example:

Input term: soil
Search query: title:soil^100 OR description:soil^99

Translated, this query reads: "Search all documents containing the term 'soil' in the field title or description. Value the results with soil in the field title higher than in description ".

So a template allows you to define the field of the index to search on and how the search term should be integrated into the search query.

The following sections provide an overview of how to define your own query templates.

Template syntax

A template is a string value which may include plain text or expressions.

Plain text will be added to the resulting query as it is.

An expression always appears in curly brackets ({<expression>}). It will be interpreted, i.e. variables and functions will be evaluated, before the result is added to the final query.

Example

The template:

{$field}:{$value.prefix('*')}

contains two simple expressions and the colon (:) as plain text. If $field is "full_text" and $value is "water", we will get a search query as such:

full_text:*water.

Variables

A query template can include two different variables:

  • $field: The field on which to search. This variable will be replaced with the name of the search field configured in smart.finder.

  • $value: The search term entered by the user.

Functions

Functions are used to manipulate the $value variable, e.g. adding a prefix or a suffix to a search term, split it into partial strings, and join these together into a single string.

Function calls can be chained with the . character to execute different operations on the search term sequentially.

Curly braces can not be used as parameters for the functions.
Function name Description Parameter Return value Example

split

This function splits the variable by an arbitrary separator

A single character that should be used to separate the variable.

A list of values.

{$value.split(';')}

prefix

This function adds a prefix to the variable using a string value.

One or more characters by which the variable should be prefixed.

A list of values.

{$value.prefix('*')}

suffix

This function adds a suffix to the variable using string value.

One or more characters by which the variable should be suffixed.

A list of values.

{$value.suffix('*^90')}

join

This function joins a previously split variable using a given string value.

One or more characters by which the single tokens shall be joined.

A list wih a single value.

{$value.join('AND')}

Examples

This section shows some examples of what query templates can look like and how they are parsed.

  1. This template produces a Solr query to search on the field title with the search term that was typed in by the user. The configured search field will be ignored because the template does not include an expression with the variable $field.

    • User input: climate

    • Configured search field: full_text

    • Template: title:{$value}

    • Resulting query: title:climate

  2. This template produces a Solr query to search on the configured search field full_text with the search term that was typed in by the user:

    • User input: climate

    • Configured search field: full_text

    • Template: {$field}:{$value}

    • Resulting query: full_text:climate

  3. This template splits the user input by whitespace and then joins each term with an AND:

    • User input: climate change

    • Configured search field: full_text

    • Template: full_text:{$value.split(' ').join('AND')}

    • Resulting query: full_text:climate AND change

  4. This template splits the user input by whitespace and then suffix each term with a star. After all the suffixed terms will be joined with OR

    • User input: climate change

    • Configured search field: full_text

    • Template: full_text:{$value.split(' ').suffix('*').join('OR')}

    • Resulting query: full_text:climate* OR change*

  5. This example shows a more complex template with multiple use of $value variables and shows how the search term could be boosted.

    • User input: climate change

    • Configured search field: full_text

    • Template: full_text:({$value})^99 OR ({$value.split(' ').suffix('*').join('OR')})^95

    • Resulting query: full_text:(climate change)^99 OR (climate* OR change*)^95

  6. This example shows how to perform a search on two different custom search fields.

    • User input: climate

    • Configured search field: full_text

    • Template: title:{$value} OR topic:{$value}

    • Resulting query: title:climate OR topic: climate