The following notes describe changes to Solr in recent releases that you should be aware of before upgrading.
These notes highlight the biggest changes that may impact the largest number of implementations. It is not a comprehensive list of all changes to Solr in any release.
When planning your Solr upgrade, consider the customizations you have made to
your system and review the
file found in your Solr package. That file includes all the changes and updates
that may effect your existing implementation.
Detailed steps for upgrading a Solr cluster are in the section Upgrading a Solr Cluster.
Upgrading to 8.x Releases
If you are upgrading from 7.x, see the section Upgrading from 7.x Releases below.
See the 8.5 Release Notes for an overview of the main new features of Solr 8.5.
When upgrading to 8.5.x users should be aware of the following major changes from 8.4.
Note: an index incompatibility warning was retroactively added below to 8.4 for users choosing a non-default postings format (e.g. "FST50").
Considerations for a SolrCloud Upgrade
Solr 8.5 introduces a change in the format used for the elements in the Overseer queues and maps (see SOLR-14095 for technical discussion of the change). This queue is used internally by the Overseer to reliably handle operations, to communicate operation results between the Overseer and the coordinator node, and by the REQUESTSTATUS API for displaying information about async Collection operations.
This change won’t require you to change any client-side code you should see no differences on the client side. However, it does require some care when upgrading an existing SolrCloud cluster depending on your upgrade strategy.
If you are upgrading Solr with an atomic restart strategy:
- If you don’t use async or REQUESTSTATUS operations, you should be able to restart and not see any issues.
- If you do use Collection API operations:
- Pause Collection API operations.
- Cleanup queues (See the section DELETESTATUS for examples) if you use async operations.
- Upgrade and restart the nodes.
- Resume all normal operations.
If you are upgrading Solr with a rolling restart strategy:
- If you don’t use Collection API operations, you should be able to do a rolling restart and not see any issues.
- If you do use Collection API operations, but you can pause their use during the restart the easiest
way is to:
- Pause Collection API operations.
- Upgrade and restart all nodes.
- Cleanup queues (See the section DELETESTATUS for examples) if you use async operations.
- Resume all normal operations.
If you use Collection API operations and can’t pause them during the upgrade:
- Start 8.5 nodes with the system property:
-Dsolr.useUnsafeOverseerResponse=deserialization. Ensure the Overseer node is upgraded last.
- Once all nodes are in 8.5 and once you don’t need to read old status anymore, restart again removing the system property.
If you prefer to keep the old (but insecure) serialization strategy, you can start your nodes using the system
-Dsolr.useUnsafeOverseerResponse=true. Keep in mind that this will be removed in future version of Solr.
Solr now has the ability to run with a Java security manager enabled. To enable this, set the property
solr.in.cmd. Note that if you are using HDFS to store indexes, you cannot enable the security manager.
In Solr 9.0, this will be the default.
See also the section Enable Security Manager.
Block/Allow Specific IPs
Solr has two new parameters to allow you to restrict access to Solr using IP addresses. Use
SOLR_IP_WHITELIST to configure a whitelist, and
SOLR_IP_BLACKLIST to configure a blacklist. These properties are defined in
See also the section Enable IP Access Control.
BlockJoin Facet Deprecation
The BlockJoinFacetComponent is marked for deprecation and will be removed in 9.0.
Users are encouraged to migrate to
uniqueBlock() in JSON Facet API.
More information about this is available in the section Block Join Domain Changes.
Caching with the Boolean Query Parser
By default, the Boolean Query Parser caches queries in Solr’s filterCache. It’s now possible to disable this with the local param
Indexing Log Files
Solr now includes a command line tool,
bin/postlogs which will index Solr’s log files into a collection.
This provides an easy way to use Solr or visualization tools (such as Zeppelin) to troubleshoot problems with the system.
This tool is not yet officially documented in the Reference Guide, but draft documentation is available in a branch and can be accessed via GitHub.
Solr’s Unified Highlighter now has two parameters to help control passage sizing,
See the section The Unified Highlighter for details about these new parameters.
Regardless of the settings, the passages may be sized differently than before.
Shared Library System Parameter
solr.xml file has long had support for a
sharedLib parameter, which allows you to define a common location for .jar files that may need to be in the path for all cores.
This property can now be defined in
solr.in.cmd as a system property (
-Dsolr.sharedLib=/path/to/lib) added to
solr.in.cmd for details).
See the 8.4 Release Notes for an overview of the main new features of Solr 8.4.
When upgrading to 8.4.x users should be aware of the following major changes from 8.3.
Reminder: If you set the
docValuesFormat in the schema in order to use a non-default option, you risk preventing yourself from upgrading your Lucene/Solr software at future versions.
Multiple non-default postings formats changed in 8.4, thus rendering the index data from a previous index.
This includes "FST50" which was recommended by the Solr TaggerHandler for performance reasons.
There is now improved documentation to navigate this trade-off choice.
Package Management System
Version 8.4 introduces a package management system to Solr. The goals of the system are to allow hot (live) deployment of plugins, provide packaging guidelines for plugins, and standardize Solr’s approach by following familiar concepts used in other package management systems.
The system is designed to eventually replace use of the
<lib ../> directive,
the Blob Store, and other methods of deploying plugins and custom components
The system is currently considered experimental, so use with caution. It must be enabled with a system parameter passed at start up before it can be used. For details, please see the section Package Management.
With this feature Solr’s Blob Store functionality is now deprecated and will likely be removed in 9.0.
The follow mix of changes were all made with the intention of making Solr more secure out of the box.
solrconfig.xmlfile in Solr’s
_defaultconfigset has been trimmed of the following previously pre-configured items:
<lib …/>directives. This means that Solr Cell (aka Tika), Learning to Rank, Clustering (with Carrot2), language identification, and Velocity (for the
/browsesample search interface) are no longer enabled out of the box.
- The Term Vector Component.
The XSLT and Velocity response writers.
All of these items can be added to your Solr implementation by manually editing
solrconfig.xmlto add them back in, or use the Config API.
sample_techproducts_configsand the examples found in
Configsets that have been uploaded with an unsecured Configset API (i.e., when authentication is not enabled) are considered "Untrusted Configsets".
In order to bolster Solr’s out-of-the-box security, these untrusted configsets are no longer allowed to use the
<lib …/>directive to implement contribs or custom Jars.
When upgrading to 8.4, if you are using untrusted configsets that contain
<lib ../>directives, their corresponding collections will not load (they will cease to work). You have a few options in this case:
- You can secure your Solr instance with authentication
and re-upload the configset (using the
bin/solr zk upconfig …Solr CLI command);
- You can put your custom Jars in Solr’s classpath instead of
You can try the new package management system to manage your custom Jars.
See the section Upload a Configset for more details about trusted vs. untrusted configsets.
- You can secure your Solr instance with authentication and re-upload the configset (using the
Our default Jetty configuration has been updated to now set a Content-Security-Policy (CSP) by default. See
./server/etc/jetty.xmlfor details about how it is configured.
jetty.xmlto remove CSP (creating weaker security protection);
- Remove/alter the headers with a reverse proxy.
- Solr’s Blob Store and runtime libs functionality are now deprecated and are planned to be removed from Solr in version 9.0. It has been replaced with the new package management system.
- The Velocity response writer is also now deprecated and is planned to be removed from Solr in version 9.0.
Using Collapse with Group Disallowed
Using the CollapsingQueryParser with Result Grouping has never been supported as it causes inconsistent behavior and NullPointerException errors. We have now explicitly disallowed this combination to prevent these errors. If you are using these together, you will need to modify your queries.
SolrJ now supports the
shards.preferenceparameter for single-shard scenarios to ensure multi-shard and single-shard request routing works in the same way.
QueryResponse.getExplainMap()type has changed from
Map<String, Object>in order to support structured explanations.
This change is expected to be mostly back-compatible. Compiled third-party components will work the same due to type erasure, but source code changes may be required.
- Replica routing code has been moved to SolrJ, making those classes available to clients if necessary.
- A new DBSCAN clustering streaming evaluator has been added.
precisionstream evaluator can now operate on matrices.
randomstreaming expression can now create the x-axis.
- Two new aggregations have been added:
- Several aggregations now support multi-valued fields:
After the addition of
CaffeineCachein 8.3, legacy SolrCache implementations are deprecated and likely to be removed in 9.0.
Users are encouraged to transition their cache configurations to use
org.apache.solr.search.CaffeineCacheas soon as feasible.
See the 8.3 Release Notes for an overview of the main new features of Solr 8.3.
When upgrading to 8.3.x users should be aware of the following major changes from 8.2.
JWT Authentication now supports multiple identity providers.
To allow this, the parameter
jwkUrl has been deprecated and replaced with
jwkUrl will continue to work as normal, but users
should plan to transition their configurations to use
jwksUrl instead as
soon as feasible.
Solr has a new cache implementation,
CaffeineCache, which is now recommended over other caches. This cache is expected to generally provide most users lower memory footprint, higher hit ratio, and better multi-threaded performance.
Since caching has a direct impact on the performance of your Solr implementation, before switching to any new cache implementation in production, take care to test for your environment and traffic patterns so you fully understand the ramifications of the change.
- A new parameter,
maxIdleTime, allows automatic eviction of cache items that have not been used in the defined amount of time. This allows the cache to release some memory and should aid those who want or need to fine-tune their caches.
See the section Query Settings in SolrConfig for more details about these and other cache options and parameters.
See the 8.2 Release Notes for an overview of the main new features of Solr 8.2.
When upgrading to 8.2.x, users should be aware of the following major changes from v8.1.
Solr 8.2 updates the version of ZooKeeper included with Solr to v3.5.5.
It is recommended that external ensembles set up to work with Solr also be updated to ZooKeeper 3.5.5.
This ZooKeeper release includes many new security features.
In order for Solr’s Admin UI to work with 3.5.5, the
zoo.cfg file must allow access to ZooKeeper’s "four-letter commands".
At a minimum,
mntr must be enabled, but other commands can optionally be enabled if you choose.
See the section Configuration for a ZooKeeper Ensemble for details.
|Until 8.3, SOLR-13672 causes the ZK Status screen in the Admin UI to not be able to report status. This only impacts the UI, ZooKeeper still operates correctly.|
Routed aliases now use collection properties to identify collections that belong to the alias; prior to 8.2, these aliases used core properties.
This is backward-compatible and aliases created with prior versions will continue to work. However, new collections will no longer add the
routedAliasNameproperty to the
core.propertiesfile so any external code depending on this location will need to be updated.
- Time-routed aliases now include a
TRAinfix in the collection name, in the pattern
Collections created with older versions will continue to work.
Distributed Tracing Support
This release adds support for tracing requests in Solr. Please review the section Distributed Solr Tracing for details on how to configure this feature.
See the 8.1 Release Notes for an overview of the main new features of Solr 8.1.
When upgrading to 8.1.x, users should be aware of the following major changes from v8.0.
Global maxBooleanClauses Parameter
The behavior of the
maxBooleanClausesparameter has changed to reduce the risk of exponential query expansion when dealing with pathological query strings.
A default upper limit of 1024 clauses is now enforced at the node level. This was the default prior to 7.0, and it can be overridden with a new global parameter in
solr.xml. This limit will be enforced for all queries whether explicitly defined by the user (or client), or created by Solr and Lucene internals.
An identical parameter is available in
solrconfig.xmlfor limiting the size of queries explicitly defined by the user (or client), but this per-collection limit will still be restricted by the global limit set in
If your use case demands that you a lot of OR or AND clauses in your queries, upon upgrade to 8.1 you may need to adjust the global
maxBooleanClausesparameter since between 7.0 and 8.1 the limit was effectively unbounded.
For more information about the new parameter, see the section Format of solr.xml: maxBooleanClauses.
- JSON Web Tokens (JWT) are now supported for authentication. These allow Solr to assert a user is already authenticated via an external identity provider, such as an OpenID Connect-enabled IdP. For more information, see the section JWT Authentication Plugin.
- A new security plugin for audit logging has been added. A default class
SolrLogAuditLoggerPluginis available and configurable in
security.json. The base class is also extendable for adding custom audit plugins if needed. See the section Audit Logging for more information.
- The output of the REQUESTSTATUS command in the Collections API will now include internal asynchronous requests (if any) in the "success" or "failed" keys.
- The CREATE command will now return the appropriate status code (4xx, 5xx, etc.) when the command has failed. Previously, it always returned
0, even in failure.
- The MODIFYCOLLECTION command now accepts an attribute to set a collection as read-only. This can be used to block a collection from receiving any updates while still allowing queries to be served. See the section MODIFYCOLLECTION for details on how to use it.
- A new command RENAME allows renaming a collection by setting up a one-to-one alias using the new name. For more information, see the section RENAME.
- A new command REINDEXCOLLECTION allows indexing existing stored fields from a source collection into a new collection. For more information, please see the section REINDEXCOLLECTION.
The default Log4j2 logging mode has been changed from synchronous to asynchronous. This will improve logging throughput and reduce system contention at the cost of a slight chance that some logging messages may be missed in the event of abnormal Solr termination.
If even this slight risk is unacceptable, the Log4j configuration file found in
server/resources/log4j2.xmlhas the synchronous logging configuration in a commented section and can be edited to re-enable synchronous logging.
- The SolrGangliaReporter has been removed from Solr. The metrics library used by Solr, Dropwizard Metrics, was updated to version 4, and Ganglia support was removed from it due to a dependency on the LGPL license.
Browse UI (Velocity)
- Velocity and Velocity Tools were both upgraded as part of this release. Velocity upgraded from 1.7 to 2.0. Please see https://velocity.apache.org/engine/2.0/upgrading.html about upgrading. Velocity Tools upgraded from 2.0 to 3.0. For more details, please see https://velocity.apache.org/tools/3.0/upgrading.html for details about the upgrade.
Default Garbage Collector (GC)
- Solr’s default GC has been changed from CMS to G1. If you prefer to use CMS or any other GC method, you can modify the
Upgrading from 7.x Releases
The upgrade from 7.x to Solr 8.0 introduces several major changes that you should be aware of before upgrading. These changes are described in the section Major Changes in Solr 8. It’s strongly recommended that you do a thorough review of that section before starting your upgrade.
|If you run in SolrCloud mode, you must be on Solr version 7.3 or higher in order to upgrade to 8.x.|
Upgrading from Pre-7.x Versions
Users upgrading from versions of Solr prior to 7.x are strongly encouraged to consult
CHANGES.txt for the details of all changes since the version they are upgrading from.
The upgrade from Solr 6.x to Solr 7.0 introduced several major changes that you should be aware of before upgrading. Please do a thorough review of the section Major Changes in Solr 7 before starting your upgrade.
A summary of the significant changes between Solr 5.x and Solr 6.0 is in the section Major Changes from Solr 5 to Solr 6.