Query templates

Custom query templates can be used in the map.apps Smart Search Extension to include an entered search term in complex queries to the search service.

Example with default query template

In the default search of the map.apps Smart Search Extension, a query template is used to pass the entered search term to the search service heavily processed and weighted. This search template is the default setting:

Input: soil
Search: full_text:((soil~1) OR (soil*^98) OR ((soil)^100))

The field full_text is intended for a full text search. Translated, this query reads: "Search all documents that contain a term similar to soil or start with soil or contain the exact term soil. The exact term is to be ranked higher than the term with wildcard, which is to be ranked higher than the similar term."

The default query template for map.apps Smart Search Extension is defined as follows:

{$field}:(({$value.split(' ').suffix('~1').join('OR')}) OR ({$value.split(' ').suffix('*^98').join('OR')}) OR (({$value})^100))
Example with custom query template

The default search template can be customized to search on other fields, for example:

Input: soil
Search: 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 with a template you can define on which field of the index is searched and how the search term should be formatted.

For configuration details, see Solr Queries.

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