solrfn

FreeMarker development only

solrfn templating functions are used to construct search queries from FreeMarker templates and trigger Solr server searches that will return results in form of a JSON string. Such results can be easily processed in FreeMarker templates.

These templating functions are provided by the magnolia-solr-templating submodule of the Solr module.

solrfn templating functions are not bundled with the preconfigured Magnolia bundles or webapps.

Basic templating

All of the solrfn query methods are provided by the info.magnolia.search.solr.templating.SolrTemplatingFunction Java class and return a info.magnolia.search.solr.templating.SolrQueryBuilder object.

Calling one of its methods returns the same object and so you can chain the methods using the same object.

Create a query

Create a Solr query.

Method signature

SolrQueryBuilder query(String searchTerm)

SolrQueryBuilder query(String searchTerm, boolean escape)

Arguments

Argument Description

searchTerm

required

A term to search for. Leaving the argument unspecified will search for everything, which is the same as using the wildcard (*).

escape

optional

Escapes the special characters in the search term if set to true.

Usage

solrfn.query(searchTerm, escape)

[#assign results = solrfn.query("(1+1):2", true).search()]

Creates a query for the mathematical expression (1+1):2 and then triggers the search.

Trigger a search

To trigger a search after initializing the SolrQueryBuilder by one of the query methods from the SolrTemplatingFunction, call the search method.

Method signature

String search()

Usage

solrfn.query(searchTerm, escape).search()

[#assign results = solrfn.query("searchTerm").search()]
${results}

Creates a query for "searchTerm", triggers the search and prints the whole JSON string.

To convert a string to a JSON expression, use the FreeMarker eval function (eval_json since freemarker 2.3.31), as in for example:

[#assign results = solrfn.query("searchTerm").search()?eval]

Documents found: ${results.response.numFound}

[#list results.response.docs as doc]
  <li>${doc.url!}
[/#list]

Use a different Solr client

The Solr Search Provider module allows you to define more than one server (see Configuring Solr clients). To specify which Solr client should be leveraged, use the clientName method in the SolrQueryBuilder.

Method signature

SolrQueryBuilder clientName(String clientName)

Arguments

Argument Description

clientName

required

Name of a configured Solr client.

Usage

solrfn.query(searchTerm, escape).client(clientName).search()

[#assign results = solrfn.query("searchTerm").client("mySolrClient").search()]

Filter results by type

Indexers and crawlers allow you to specify the type of content to be indexed, see the type property in crawler and indexer configuration. You can use the equivalent solrfn type method as a search filter.

Method signature

SolrQueryBuilder type(String type)

Arguments

Argument Description

type

required

Name of the type.

Usage

solrfn.query(searchTerm, escape).type(type).search()

[#assign results = solrfn.query("searchTerm").type("travel_demo_website").search()]

Advanced templating

Common parameters

SolrQueryBuilder provides several most commonly used Solr query parameters.

Method Description Equivalent Solr parameter
Link to Solr documentation

filterQuery(String…​ fq)

Restrict query results.

fq

Filter Query Parameter

start(Integer start)

Sets an offset for a query result set and instructs Solr to display the results from this offset.

start

Start Parameter

rows(Integer rows)

Defines the maximum number of documents from a complete result set Solr should return.

Default value is 10.

rows

Rows Parameter

field(String…​ fields)

Limits the information included in a query response to a specified list of fields.

fl

Field List Parameter

sort(String…​ sorts)

Arranges the search results in either ascending (asc) or descending (desc) order.

sort

Sort Parameter

defaultField(String field)

Specifies a default field, overriding the default field in the Schema.

df

Default Field Parameter

Usage

[#assign results = solrfn.query("searchTerm")
                                 .start(0)
                                 .size(50)
                                 .field("url, "name", "abstract")
                                 .filterQuery("category:mobile")
                                 .sort("inStock desc, price asc")
                                 .search()]

DisMax and eDisMax query parsers

By default, the standard query parser is used. To use the DisMax or the eDisMax filter instead, use the respective method.

Method Description Link to Solr documentation

dismax()

Use the DisMax parser.

DisMax query parser

edismax()

Use the eDisMax parser.

eDisMax query parser

Parameters

Method Description Equivalent Solr parameter
Link to Solr documentation

queryField(String…​ qf)

Introduces a list of fields, each of which is assigned a boost factor to increase or decrease that particular field’s importance in the query.

qf

Query Fields Parameter

minimumMatch(String mm)

By default, all words or phrases specified in the query are treated as "optional" clauses. The mm parameter makes it possible to say that a certain minimum number of those clauses must match.

mm

Minimum Should Match

phraseField(String…​ pf)

To "boost" the score of documents in cases where all of the terms in the query appear in close proximity.

pf

Phrase Fields

boostQuery(String…​ bq)

Specifies an additional, optional, query clause that will be added to the user’s main query to influence the score.

bq

Boost Query Parameter

Usage

[#assign results = solrfn.query("searchTerm")
                                 .dismax()
                                 .queryField("title^10", "abstract^2", "content^0.5")
                                 .minimumMatch(2)
                                 .boostQuery("date:[NOW/DAY-1YEAR TO NOW/DAY]")
                                 .search()]

Specifying a requestHandler

A request handler processes incoming Solr requests. Multiple requestHandlers can be defined in the solrConfig.xml.

Method signature

SolrQueryBuilder requestHandler(String requestHandler)

Arguments

Argument Description

requestHandler

required, default is /select

Specifies which request handler should be used in the Solr configuration.

Usage

[#assign suggests = solrfn.query("searchTerm").requestHandler("/suggest").search()]

Higlighting

Highlighting allows you to include with the query response fragments of documents that match the user’s query.

Fragments (also referred to as snippets or passages) are a portion of a document field that contains matches from the query.

The fragments are included in the highlighting section, a special section of the response, and the client uses the formatting clues also included to determine how to present the fragments to users.

See also Common Highlighting Parameters in Apache Solr documentation.

Method Description Equivalent Solr parameter

highlight()

Enables highlighting.

hl=true

highlight(String…​ fields)

Enables highlighting and specifies a list of fields to highlight.

hl=true

hl.fl

highlightSnippets(int hlSnippets)

Specifies the maximum number of highlighted snippets to generate per field.

hl.snippets

highlightTag(String hlPre, String hlPost)

Specifies a tag that will be used before and after a highlighted term.

hl.simple.pre

hl.simple.post

highlightFragSize(int hlFragSize)

Specifies the approximate fragment size to consider for highlighting.

The default size is 100 characters.

hl.fragsize

Usage

[#assign results = solrfn.query("searchTerm")
                                 .highlight("title, content")
                                 .highlightTag("<h1>", "</h1>")
                                 .search()]

Faceting

Faceting is the arrangement of search results into categories based on indexed terms. It makes it easy for users to explore search results, narrowing in on exactly the results they are looking for.

Searchers are presented with the indexed terms, along with numerical counts of how many matching documents were found for each term.

See also Field-Value Faceting Parameters in Apache Solr documentation.

Method Description Equivalent Solr parameter

facet()

Enables faceting.

facet=true

facetField(String…​ facetFields)

Identifies a field that should be treated as a facet.

facet.field

facetPrefix(String prefix)

Limits the terms on which to facet to those starting with the given string prefix.

facet.prefix

facetPrefix(String field, String prefix)

For a specific field, limits the terms on which to facet to those starting with the given string prefix.

f.<field>.facet.prefix

facetContains(String contains)

Limits the terms on which to facet to those containing the given substring.

facet.contains

facetContains(String field, String contains)

For a specific field, limits the terms on which to facet to those containing the given substring.

f.<field>.facet.contains

facetContains(String contains, boolean ignoreCase)

Limits the terms on which to facet to those containing the given substring and allows case to be ignored when matching the given substring against candidate facet terms.

facet.contains

facet.contains.ignoreCase

facetContains(String field, String contains, boolean ignoreCase)

For specific field, limits the terms on which to facet to those containing the given substring and allows case to be ignored when matching the given substring against candidate facet terms.

f.<field>.facet.contains

f.<field>.facet.contains.ignoreCase

facetLimit(int limit)

Specifies the maximum number of facets for a field that are returned.

The default value is 100.

facet.limit

facetLimit(String field, int limit)

For specific field, specifies the maximum number of facets for a field that are returned.

f.<field>.facet.limit

facetSort(boolean index)

If set to true, returns the constraints sorted in their index order.

If set to false, returns the constraints sorted by count.

The default is count if the facet limit is greater than 0, otherwise, the default is index.

facet.sort

facetSort(String field, boolean index)

Same as the facetSort(boolean index) method, but only for a specific field.

f.<field>.facet.sort

facetMinCount(int minCount)

Specifies the minimum counts required for a facet field to be included in the response.

The default value is 0.

facet.mincount

Usage

[#assign results = solrfn.query("searchTerm")
                                 .facet()
                                 .facetField("category", "brand")
                                 .facetSort("category", true)
                                 .facetMinCount(5)
                                 .search()]

Range faceting

You can use range faceting on any date field or any numeric field that supports range queries.

See also Range Facet Parameters in Apache Solr documentation.

Method Description Equivalent Solr parameter

facetRange(String field, String start, String end, String gap)

Defines the field for which Solr should create range facets, with parameters start, end and gap.

facet.range

f.<field>.facet.range.start

f.<field>.facet.range.end

f.<field>.facet.range.gap

Usage

[#assign results = solrfn.query("searchTerm")
                                  .facetRange("price", "0", "100000", "1000")
                                  .search()]

Other parameters

Solr provides many more options. If a function is missing in solrfn, then use the methods below.

Method Description Equivalent Solr parameter

param(String param, String…​ values)

Any parameter supported by Solr.

<param>=<values>

param(String field, String param, String…​ values)

Any parameter supported by Solr on a per field basis.

f.<field>.<param>=<values>
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules