This is an automated email from the ASF dual-hosted git repository. dsmiley pushed a commit to branch branch_9x in repository https://gitbox.apache.org/repos/asf/solr.git
commit a4c7aa08e9bf6f691f695a9d34bcec7b57b313c7 Author: Ilaria Petreti <[email protected]> AuthorDate: Mon Mar 16 11:48:48 2026 +0100 SOLR-18100: Improve Combined Query Feature documentation (#4144) (cherry picked from commit 3724ebb50a4bf3b07e8e620ef327d4d458cb58da) --- .../query-guide/pages/json-combined-query-dsl.adoc | 92 ++++++++++++++++------ 1 file changed, 68 insertions(+), 24 deletions(-) diff --git a/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc b/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc index e5649f0cad2..de62c7a6d1b 100644 --- a/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc +++ b/solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc @@ -25,6 +25,42 @@ It is extending JSON Query DSL ultimately enabling Hybrid Search. This feature is currently unsupported for grouping and Cursors. ==== +[IMPORTANT] +==== +This feature works in both Standalone and SolrCloud modes and always performs distributed search execution. +In Standalone (user-managed) mode, shard URLs must be explicitly allow-listed using the *allowUrls* parameter, otherwise Solr returns HTTP 403. For example: + +``` +"-Dsolr.security.allow.urls=http://localhost:8983/solr/"; +``` + +==== + +== Configuration Requirements + +Combined Query Feature has a separate handler with class `solr.CombinedQuerySearchHandler` which can be configured as below: + +``` +<requestHandler name="/search" class="solr.CombinedQuerySearchHandler"> +..... +</requestHandler> +``` + +In addition, the `QueryComponent` has been extended to create a new `CombinedQueryComponent`, which must be declared as a search component: +``` +<searchComponent class="solr.CombinedQueryComponent" name="combined_query"> + <int name="maxCombinerQueries">2</int> +</searchComponent> +``` + + +The Search Component also accepts parameters as below: + +`maxCombinerQueries`:: +This parameter can be set to enforce an upper limit on the number of queries defined in `combiner.query`. +It defaults to `5` if not set. + + == Query DSL Structure The query structure is similar to JSON Query DSL except for how multiple queries are defined along with their parameters. @@ -100,37 +136,45 @@ QueryResponse queryResponse = query.process(solrClient, COLLECTION_NAME); ==== ====== -== Search Handler Configuration - -Combined Query Feature has a separate handler with class `solr.CombinedQuerySearchHandler` which can be configured as below: - -``` -<requestHandler name="/search" class="solr.CombinedQuerySearchHandler"> -..... -</requestHandler> -``` - -The Search Handler also accepts parameters as below: +== Combiner Algorithm Plugin -`maxCombinerQueries`:: - This parameter can be set to put upper limit check on the maximum number of queries can be executed defined in `combiner.query`. - It defaults to `5` if not set. +As mentioned xref:json-combined-query-dsl.adoc#query-dsl-structure[above], custom algorithms can be configured to combine the results across multiple queries using a https://solr.apache.org/guide/solr/latest/configuration-guide/solr-plugins.html[Solr plugin]. -=== Combiner Algorithm Plugin +The class to implement the custom logic has to extend `org.apache.solr.handler.component.combine.QueryAndResponseCombiner`, which is an abstract base class that provides a framework for implementing various algorithms used to merge ranked lists and shard documents. -As mentioned xref:json-combined-query-dsl.adoc#query-dsl-structure[above], custom algorithms can be configured to combine the results across multiple queries. -The Combined Query Search Handler definition takes parameter `combiners` where a custom class can be used to define the algorithm by giving a name and the parameters required. +The Combined Query Component definition takes the `combiners` parameter, where the custom class can be declared by specifying a name and the custom parameters required by the custom algorithm. -Example of the Search Handler as below: +Example of the Search Component as below: ``` <searchComponent class="solr.CombinedQueryComponent" name="combined_query"> - <int name="maxCombinerQueries">2</int> + <int name="maxCombinerQueries">2</int> <lst name="combiners"> - <lst name="customAlgorithm"> - <str name="class">org.apache.solr.search.combine.CustomCombiner</str> - <int name="var1">35</int> - <str name="var2">customValue</str> + <lst name="customAlgorithm"> + <str name="class">org.apache.solr.handler.component.combine.CustomCombiner</str> + <int name="customParam1">35</int> + <str name="customParam2">customValue</str> </lst> </lst> - </searchComponent> +</searchComponent> ``` + +Then, when executing the combined query, the only thing that changes in the JSON query payload is the value specified in the `combiner.algorithm` parameter: + +``` + ... + "params": { + "combiner": true, + "combiner.query": ["lexical1", "vector"], + "combiner.algorithm": "customAlgorithm" + } +... +``` + +In this case, `customAlgorithm` is specified which is the name defined in the configuration; the RRF-specific parameters do not need to be provided. + +== Additional Resources + +Blog posts: + +* https://sease.io/2026/03/hybrid-search-with-reciprocal-rank-fusion-in-apache-solr.html[Hybrid Search with Reciprocal Rank Fusion in Apache Solr] +* https://sease.io/2026/03/hybrid-search-using-a-custom-algorithm-in-apache-solr.html[Hybrid Search using a Custom Algorithm in Apache Solr]
