SOLR-18100: Improve Combined Query Feature documentation by ilariapet · Pull Request #4144 · apache/solr

ilariapet · 2026-02-18T12:17:03Z

https://issues.apache.org/jira/browse/SOLR-18100

Description

Some sections of the Combined Query Feature documentation have been made clearer to improve understanding and usability of the feature.

Checklist

Please review the following and check all that apply:

I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
I have created a Jira issue and added the issue ID to my pull request title.
I have given Solr maintainers access to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
I have developed this patch against the main branch.
I have run ./gradlew check.
I have added tests for my changes.
I have added documentation for the Reference Guide
I have added a changelog entry for my change

…combined-query-documentation

alessandrobenedetti · 2026-02-18T14:23:00Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

-`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.


Add the full reference of the class 'QueryAndResponseCombiner'

+1, having the full class reference here would be nice.

alessandrobenedetti · 2026-02-18T14:24:15Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+```
+
+In this case, `customAlgorithm` is specified which is the name defined in the configuration; the RRF-specific parameters do not need to be provided.
+


you can add links to our blog posts, we have two on the topic, you can ask Lisa for the URLs (they will be published before this documentation will)

alessandrobenedetti

The documentation change is interesting and needs some minor changes

dsmiley

thanks for contributing!

CC @ercsonusharma

dsmiley · 2026-02-19T03:50:15Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+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/"


Hmm; okay, the need for this is something Solr should improve (to automatically add localhost same-port). If this was improved, I suspect you wouldn't of even written this entire paragraph.

--jvm-opts -- surely we can just pass -Dsolr.....

dsmiley · 2026-02-19T03:52:55Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+--jvm-opts "-Dsolr.security.allow.urls=http://localhost:8983/solr/"
+```
+
+In SolrCloud mode, this is managed automatically via ZooKeeper.


I would do away with this sentence, as redundant with the prior paragraph. And the ZK reference is a needless implementation detail reference.

dsmiley · 2026-02-19T03:54:54Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+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`.


Suggested change

This parameter can be set to put upper limit check on the maximum number of queries can be executed defined in `combiner.query`.

This parameter can be set to enforce an upper limit on the number of queries defined in `combiner.query`.

dsmiley · 2026-02-19T03:59:44Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+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`.


Rather than say these specific things, please instead refer to solr-plugins.adoc which discusses several ways to install them (IMO least preferred is WEB-INF/lib). If you want to say more about java development, I think that page would be where we might want to say such things. But not this page here.

dsmiley · 2026-02-19T04:01:07Z

changelog/unreleased/SOLR-18100-improve-combined-query-documentation.yml

please don't add to the changelog on documentation matters

ercsonusharma · 2026-02-19T05:50:56Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+[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:


I haven’t encountered this issue before, as it might vary depending on the infrastructure (?)

ercsonusharma · 2026-02-19T05:53:27Z

solr/solr-ref-guide/modules/query-guide/pages/json-combined-query-dsl.adoc

+</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:


I appreciate you breaking this down.

ilariapet added 3 commits February 18, 2026 11:50

Improve combined query documentation

c31e48f

Merge remote-tracking branch 'Upstream/main' into SOLR-18100-improve-…

2e4dae0

…combined-query-documentation

Add changelog

315c3e6

github-actions bot added the documentation Improvements or additions to documentation label Feb 18, 2026

alessandrobenedetti reviewed Feb 18, 2026

View reviewed changes

alessandrobenedetti approved these changes Feb 18, 2026

View reviewed changes

alessandrobenedetti requested a review from dsmiley February 18, 2026 14:24

dsmiley reviewed Feb 19, 2026

View reviewed changes

ercsonusharma reviewed Feb 19, 2026

View reviewed changes

		```

		In this case, `customAlgorithm` is specified which is the name defined in the configuration; the RRF-specific parameters do not need to be provided.

	This parameter can be set to put upper limit check on the maximum number of queries can be executed defined in `combiner.query`.
	This parameter can be set to enforce an upper limit on the number of queries defined in `combiner.query`.

Conversation

ilariapet commented Feb 18, 2026

Description

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alessandrobenedetti left a comment

Choose a reason for hiding this comment

Uh oh!

dsmiley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Comments