Migrating to Querqy 5 for Solr¶
Querqy 5 for Solr comes with a number of changes that are incompatible with earlier Querqy versions.
We normally avoid large breaking changes but when we started to implement a way to deploy rewriter configurations without having to reload the Solr collection, it soon became clear that the change would be bigger and incompatible with the previous version this time. And as we had to introduce breaking changes anyway, we used the opportunity and renamed some components and changed part of the Java package structure - hopefully for greater simplicity and clarity.
Enabling Querqy in
1<!-- 2 Add the Querqy request handler. 3--> 4<requestHandler name="/querqy/rewriter" class="querqy.solr.QuerqyRewriterRequestHandler" /> 5 6<!-- 7 Add the Querqy query parser. 8--> 9<queryParser name="querqy" class="querqy.solr.QuerqyDismaxQParserPlugin"/> 10 11<!-- 12 Override the default QueryComponent. 13--> 14<searchComponent name="query" class="querqy.solr.QuerqyQueryComponent"/>
Querqy now needs an additional
requestHandler in the configuration
(line #4). In addition, the name of the QParserPlugin class has changed from
querqy.solr.QuerqyDismaxQParserPlugin (#9). The
configuration remains unchanged.
Configuring and using rewriters¶
In Querqy 4, rewriters used to be configured as child elements of the
solrconfig.xml. Additional artefacts, like the
file for the Common Rules Rewriter were kept separately in ZooKeeper (SolrCloud)
or in the configuration directory (standalone). In Querqy 5, rewriters are
managed via an HTTP API. That’s what the new
requestHandler is for. The
new API is documented here.
This change also means that rewriters no longer have a dependency on additional
rules.txt of the Common Rules Rewriter no longer exists,
the rules are part of the rewriter configuration.
To make the new rewriter API easy to use, we provide a configuration
request builder for most rewriters for SolrJ. Look out for classes named
*ConfigRequestBuilder in the rewriter packages. For example, the
read the rules from a
As the rewriter configuration is no longer pre-defined in
solrconfig.xml, the previously static rewrite chain is replaced with a
flexible rewrite chain that is to be specified per request parameter
(see here for further
We recognise that search teams will need time to adapt their applications to
this new way of deploying rewriter configurations. To facilitate a stepwise
transition to Querqy 5, we provide a way to configure a static rewrite chain in
1<query> 2 <listener event="firstSearcher" class="querqy.solr.ClassicRewriteChainLoader"> 3 <lst name="rewriteChain"> 4 <lst name="rewriter"> 5 <str name="id">common_rules</str> 6 <str name="class">querqy.solr.rewriter.commonrules.CommonRulesRewriterFactory</str> 7 <str name="rules">rules.txt</str> 8 <bool name="ignoreCase">true</bool> 9 <str name="querqyParser">querqy.rewrite.commonrules.WhiteSpaceQuerqyParserFactory</str> 10 </lst> 11 <lst name="rewriter"> 12 <str name="id">replace</str> 13 <str name="class">...</str> 14 <!-- ... --> 15 </lst> 16 </lst> 17 </listener> 18</query> 19<requestHandler name="/querqy/rewriter" class="querqy.solr.QuerqyRewriterRequestHandler"> 20 <bool name="inMemory">true</bool> 21</requestHandler>
While the definition of the
rewriteChain (lines #3-11) looks the same
like in Querqy 4, this XML element must now be configured under a searcher
listener (#2). Note that if you use Querqy’s term query cache, the
ClassicRewriteChainLoader must be configured before the listener that preloads
terms into that cache. To update a rewriter configuration or an artefact
(‘rules.txt’) you will have to reload the collection (SolrCloud) or the core
(standalone Solr) and cannot use the rewriter API.
inMemory flag of the
QuerqyRewriterRequestHandler must be
true. Internally, the request handler is still responsible for
managing the rewriters but it will not try to persist the configuration as it is
already kept in
You will need to select rewriters per request by passing the rewriter ids in the
querqy.rewriters parameter (for example,
querqy.rewriters=replace,common_rules for the above configuration).
Configuring the rewrite chain in
solrconfig.xml is deprecated and will
be removed as part of the first Querqy release in 2022.
Renaming of rewriters¶
We have renamed some rewriters and put almost all of them each into its own
Java package (packages under querqy.solr.rewriter). Most notably the
querqy.solr.SimpleCommonRulesRewriterFactory is now named
querqy.solr.rewriter.commonrules.CommonRulesRewriterFactory. Please see
the individual rewriter documentation for the new class name.
If you have written your own Querqy rewriter, you will have to change the
factory that plugs it into Solr. You will need to extend the
querqy.solr.SolrRewriterFactoryAdapter and implement the following abstract
List<String> validateConfiguration(Map<String, Object> config)
configmap. This is the config object from the JSON rewriter configuration. Returns a list of validation error messages or an empty list if the configuration is valid.
void configure(Map<String, Object> config)
Applies the configuration to this factory instance
querqy.rewrite.RewriterFactorythat is kept in memory and that finally provides the rewriter instance per search request.
If you want to use the static, deprecated rewriter configuration in
solrconfig.xml instead of the rewriter API, your factory must additionally
querqy.solr.rewriter.ClassicConfigurationParser interface. Use
the Map<String, Object> parseConfigurationToRequestHandlerBody(NamedList<Object> configuration, ResourceLoader resourceLoader) method to
solrconfig.xml configuration to a
config map that can be
consumed by the above ‘validateConfiguration’ and ‘configure’ methods.