Apache Solr open-source search software
SOLR-15429: Documentation updates regarding global setting based behavior changes introduced in LUCENE-8811 / LUCENE-9970
Chris Hostettere316ac40db36
diff --git a/solr/solr-ref-guide/src/format-of-solr-xml.adoc b/solr/solr-ref-guide/src/format-of-solr-xml.adocindex dc76bb83f3f..1d9a1aee61e 100644--- a/solr/solr-ref-guide/src/format-of-solr-xml.adoc+++ b/solr/solr-ref-guide/src/format-of-solr-xml.adoc@@ -121,9 +121,9 @@ The directory under which configsets for Solr cores can be found. Defaults to `$[[global-maxbooleanclauses]]`maxBooleanClauses`::-Sets the maximum number of clauses allowed in any boolean query.+Sets the maximum number of (nested) clauses allowed in any query.+-This global limit provides a safety constraint on the number of clauses allowed in any boolean queries against any collection -- regardless of whether those clauses were explicitly specified in a query string, or were the result of query expansion/re-writing from a more complex type of query based on the terms in the index.+This global limit provides a safety constraint on the total number of clauses allowed in any query against any collection -- regardless of whether those clauses were explicitly specified in a query string, or were the result of query expansion/re-writing from a more complex type of query based on the terms in the index. This limit is enforced at multiple points in the Lucene code base, both to prevent primative query objects (mainly `BooleanQuery`) from being constructed with an excessive number of clauses in a way that may exhaust the JVM Heap, but also to ensure that no composite query (made up of multiple primative queries) can be executed with an excessive _total_ number of nested clauses in a way that may cause a search thread to use excessive CPU.+In default configurations this property uses the value of the `solr.max.booleanClauses` system property if specified. This is the same system property used in the `_default` configset for the <<query-settings-in-solrconfig#maxbooleanclauses,`<maxBooleanClauses>` setting of `solrconfig.xml`>> making it easy for Solr administrators to increase both values (in all collections) without needing to search through and update all of their configs.+diff --git a/solr/solr-ref-guide/src/major-changes-in-solr-9.adoc b/solr/solr-ref-guide/src/major-changes-in-solr-9.adocindex a22e957d16d..36231ce53e7 100644--- a/solr/solr-ref-guide/src/major-changes-in-solr-9.adoc+++ b/solr/solr-ref-guide/src/major-changes-in-solr-9.adoc@@ -182,7 +182,17 @@ If re-indexing is too onerous, use this mechanism in Solr 8.== Configuration and Default Parameter Changes in Solr 9-* base_url removed from stored state*+=== solr.xml maxBooleanClauses now enforced recursively++Lucene 9.0 has additional safety checks over previous versions that impact how the `solr.xml` global `<<format-of-solr-xml#global-maxbooleanclauses,maxBooleanClauses>>` option is enforced.++In previous versios of Solr, this option was a hard limit on the number of clauses in any `BooleanQuery` object - but it was only enforced for the _direct_ clauses. Starting with Solr 9, this global limit is now also enforced against the total number of clauses in a _nested_ query structure.++Users who upgrade from prior versions of Solr may find that some requests involving complex internal query structures (Example: long query strings using `edismax` with many `qf` and `pf` fields that include query time synonym expansion) which worked in the past now hit this limit and fail.++User's in this situation are advised to consider the complexity f their queries/configuration, and increase the value of `<<format-of-solr-xml#global-maxbooleanclauses,maxBooleanClauses>>` if warranted.++=== base_url removed from stored stateIf you're able to upgrade SolrJ to 8.8.x for all of your client applications, then you can set `-Dsolr.storeBaseUrl=false` (introduced in Solr 8.8.1)to better align the stored state in Zookeeper with future versions of Solr; as of Solr 9.x, the `base_url` will no longer be