Solr Server Side Query templates

march 09 2015

Categories : search
Tags : solr, query

Use a simple API to keep your Solr clients free from query complexity

We've published a simple yet useful implementation of a solr querycomponent that enables the use of server side query (ssq) templates. The jar and source code is available on github.


The purpose of this component is to store solr queries in the solr (server side) configuration. This hides solr query complexity for the clients and avoids the distribution of complex queries on client side.
This results in easier maintenance and upgrade of your solr index and solr implementation: your clients will only be affected when the API has changed, not when the index has changed.

E.g. an entered query


will be executed under the hood as


The <complex-query> is no longer set on client-side, but determined centrally by the server where also the index configuration happens.

Also, this ssq component supports the configuration of multiple server side queries (ssq) as query-templates (see configuration examples below).

This could also be achieved in vanilla Solr with the use of parameter dereferencing together with different requesthandlers that provide different default queries in the q-parameter. For more info on parameter dereferencing, check out

The ssq approach has the following advantages:

  • the client side is no longer affected as the use of explicit request handlers (or &qt parameter) is no longer required
  • other searchcomponents within the search request are not affected: using parameter dereferencing with the query-syntax in the q parameter affects the other searchcomponents (e.g. highlighting and spellcheck component)
  • the default Solr Admin query client and the velocity client (/browse) don't have to be changed to use the different requesthandlers

This ssq functionality keeps it simple by using the q parameter for search terms.


After installation (see readme on github), the configuration of the queries is done via the parameter setup for the requestHandler (optionally via initParams (in case of Solr version > 5.0)) e.g.

1) Configuration with simple setup for 1 ssq query

<lst name="defaults">
<str name="ssq">on</str>
<str name="ssq.query">{!edismax qf='subject^10.0 content flags' v=$qq}</str>

2) Configuration with 3 different ssq queries (subject, content, flags)

<lst name="defaults">
<str name="ssq">on</str>
<str name="ssq.query">content</str>
<str name="ssq.query.subject">{!edismax qf='subject^10.0 content flags' v=$qq}</str>
<str name="ssq.query.content">{!edismax qf='subject content^10.0 flags' v=$qq}</str>
<str name="ssq.query.flags">{!edismax qf='subject content flags^10.0' v=$qq}</str>


Based on the simple configuration above, the query for foo will be translated under the hood:

--> /select?q={!edismax qf='subject content^10.0 flags' v=$qq}&qq=foo

Based on the 2nd configuration above, the below sample queries for foo will be translated under the hood:

--> /select?q={!edismax qf='subject content^10.0 flags' v=$qq}&qq=foo
--> /select?q={!edismax qf='subject content flags^10.0' v=$qq}&qq=foo
--> /select?q={!edismax qf='subject^10.0 content flags' v=$qq}&qq=foo
  /select?q=foo&ssq.query={!query ...}
--> /select?q={!query ...}&qq=foo

Additional notes

The parameter name qq can optionally be changed to another arbitrary (valid parameter name) value via configuration of the parameter:

    <str name="ssq.param">qqq</str>

When the qq parameter (or the parameter defined in "ssq.param") is set in the query request by the user/client, than the ssq query template will not be applied (as qq parameter needs to be set to the query-terms for the query template to work).

/select?q=foo&qq=bar&ssq.query={!query ...}
--> /select?q=foo

To verify whether the ssq functionality was applied on your request, review the request parameters (via &echoParams=all) in the response.
The following (request) parameters will additionally be set when ssq functionality was applied:

    "ssq.applied": "true",
"qq": <set-to-value-of-original-q>,
"ssq.query.applied": "{!edismax qf='subject content^10.0 flags' v=$qq}"

For further info, please contact us or leave a comment. As always, we appreciate your feedback.


Total 1 comments.
Hendrik 2015-04-03 15:57:05
I think I understand. Looks good. Thanks!

Add a comment