From c31e48f6b9be52a8b4915d3b904870759e61c026 Mon Sep 17 00:00:00 2001 From: ilariapet Date: Wed, 18 Feb 2026 11:30:10 +0100 Subject: [PATCH 1/2] Improve combined query documentation --- .../pages/json-combined-query-dsl.adoc | 87 ++++++++++++++----- 1 file changed, 64 insertions(+), 23 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 98d3c2e96b89..34c3838bd2b0 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,43 @@ 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: + +``` +--jvm-opts "-Dsolr.security.allow.urls=http://localhost:8983/solr/" +``` + +In SolrCloud mode, this is managed automatically via ZooKeeper. +==== + +== Configuration Requirements + +Combined Query Feature has a separate handler with class `solr.CombinedQuerySearchHandler` which can be configured as below: + +``` + +..... + +``` + +In addition, the `QueryComponent` has been extended to create a new `CombinedQueryComponent`, which must be declared as a search component: +``` + + 2 + +``` + + +The Search Component also accepts parameters as below: + +`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. + + == Query DSL Structure The query structure is similar to JSON Query DSL except for how multiple queries are defined along with their parameters. @@ -71,37 +108,41 @@ Below is a sample JSON query payload: } ``` -== Search Handler Configuration - -Combined Query Feature has a separate handler with class `solr.CombinedQuerySearchHandler` which can be configured as below: - -``` - -..... - -``` +== Combiner Algorithm Plugin -The Search Handler also accepts parameters as below: +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]. -`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. +The class to implement the custom logic has to extend `QueryAndResponseCombiner`, which is an abstract base class that provides a framework for implementing various algorithms used to merge ranked lists and shard documents. -=== Combiner Algorithm Plugin +The custom class must be implemented in a Java project built against the Solr version that includes this feature (declared as a dependency in the build configuration), and the compiled JAR must then be deployed to the Solr libraries directory `../server/solr-webapp/webapp/WEB-INF/lib`. -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: ``` - 2 + 2 - - org.apache.solr.search.combine.CustomCombiner - 35 - customValue + + org.apache.solr.handler.component.combine.CustomCombiner + 35 + customValue - + +``` + +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. + From 315c3e65b6dd803f5e7192f8a1c295744ba6ee47 Mon Sep 17 00:00:00 2001 From: ilariapet Date: Wed, 18 Feb 2026 12:08:32 +0100 Subject: [PATCH 2/2] Add changelog --- .../SOLR-18100-improve-combined-query-documentation.yml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 changelog/unreleased/SOLR-18100-improve-combined-query-documentation.yml diff --git a/changelog/unreleased/SOLR-18100-improve-combined-query-documentation.yml b/changelog/unreleased/SOLR-18100-improve-combined-query-documentation.yml new file mode 100644 index 000000000000..99f24c7d1470 --- /dev/null +++ b/changelog/unreleased/SOLR-18100-improve-combined-query-documentation.yml @@ -0,0 +1,9 @@ +# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc +title: Improve combined query documentation +type: other +authors: + - name: Ilaria Petreti + - name: Alessandro Benedetti +links: + - name: SOLR-18100 + url: https://issues.apache.org/jira/browse/SOLR-18100