Solr Upgrade Notes

When doing atomic/partial updates to a child document:

• Supply the _root_ field (the ID of the root document) so that Solr understands you are manipulating a child document and not a root document. In its absence, Solr looks at the _route_ parameter but this may change in the future because it’s not an ideal substitute. If neither are present, Solr assumes you are updating a root document. If this assumption is false, Solr will do a cheap check that usually detects the problem and will throw an exception to alert you of the need to specify the Root ID. This backwards incompatible change was done to increase performance and robustness.

• This feature no longer requires stored=true or docValues=true on the _root_ field. You might have it for other purposes though (e.g., for uniqueBlock(…​)).

• This feature no longer requires the _nest_path_ field, although you probably ought to continue to define it as it’s useful for other things.

The search results clustering contrib (Carrot2) has been removed from 8.x Solr due to lack of Java 1.8 compatibility in the dependency that provides online clustering of search results. The contrib will be re-introduced in Solr 9.0.

Interleaving support has been added to Learning to Rank (LTR). Currently only the Team Draft Interleaving algorithm is supported. For examples using this feature, see the section Running a Rerank Query Interleaving Two Models.

Two metrics have been added for SolrCloud’s Overseer:

• solr_metrics_overseer_stateUpdateQueueSize

• solr_metrics_overseer_collectionWorkQueueSize

The ./bin scripts included with the Prometheus Exporter contrib now allow use of custom java options with environment variables. See the section Environment Variable Options for more details.

The default Grafana dashboards now include panels for query performance monitoring. The default Prometheus Exporter configuration includes metrics like queries-per-second (QPS) and 95th percentiles (P95) to populate the new panels.

The default Prometheus Exporter configuration also includes the two new metrics mentioned in the Metrics above.

The internal logic for identifying 'Solr Home' (solr.solr.home) has been refactored to make testing less error prone. Plugin developers using SolrPaths.locateSolrHome() or 'new `SolrResourceLoader’ should check deprecation warnings as existing some existing functionality will be removed in 9.0. SOLR-14934 has more technical details about this change for those concerned.

If upgrading from 8.6.0, please see the 8.6.1 Upgrade notes below for information on performance degradations introduced in 8.6.0 that require some intervention to resolve. If you are already on 8.6.1 or higher, you can ignore these instructions.

The autoscaling framework is now formally deprecated and will be removed in Solr 9.0. The Solr community is working on pluggable API to replace this functionality, with the goal for it to be ready by the time 9.0 is released. Deprecations include: autoscaling policy, triggers, withCollection support, simulation framework, autoscaling suggestions tab in the UI, autoAddReplicas and UTILIZENODE command.

Similarly, rule-based replica placement strategy has been deprecated and will be replaced in Solr 9.0 by APIs for replica placement and cluster events, with plugin-based implementations.

Support for detecting spinning disks will be removed in Lucene 9.0 (LUCENE-9576). Corresponding spins metrics in Solr are deprecated and will be removed in Solr 9.0.

Solr has replaced the terms "master" and "slave" in the codebase and all documentation with "leader" and "follower".

This impacts the functionality described in the section Legacy Scaling and Distribution. This functionality has only changed in terms of parameter names changed, and we do not expect any back-compatibility issues on upgrade to 8.7 or even 9.0 later.

However, users should update their solrconfig.xml files after completing the upgrade on all nodes of a cluster. Comparing your configuration to the updated configuration examples in Index Replication will show examples of what needs to change, but here are the main changes:

1. On the replication leader, in the definition of the /replication request handler:
   1. Replace "master" with "leader".
   2. Replace "slave" with "follower" if the former term is used in the name of any follower solrconfig.xml file definitions. This file can be named anything, so you can change it to whatever you’d like to call it if you’d like.
   3. Replace "slave" with "follower" if the former term is used in a replication repeater configuration.
2. On the replication follower, in the definition of the /replication request handler:
   1. Replace "masterUrl" with "leaderUrl".
   2. Replace "slave" with "follower" if the former term is used in a repeater configuration.

Performance enhancements for the relatedness() statistics function are included with 8.7. These yield the highest benefits with high-cardinality fields and can be disabled if working with lower cardinality fields with a new sweep_collection parameter. See the section relatedness() Options for details.

Solr has relied on the SOLR_STOP_WAIT parameter defined in solr.in.sh or solr.in.cmd to determine how long to wait on startup. A new parameter SOLR_START_WAIT allows defining how long Solr should wait for start up to complete.

If the time set by this parameter is exceeded, Solr will exit the startup process and return the last few lines of the solr.log file to the terminal.

By default, this parameter is set to the same value as SOLR_STOP_WAIT.

The default ZooKeeper client timeout (ZK_CLIENT_TIMEOUT) is now 30 seconds (30000 milliseconds) instead of 15.

It’s now possible to overwrite an existing configset when uploading changes by supplying the overwrite=true parameter to the Configset API.

A related parameter is cleanup=true, which allows deleting any files from the old configset that are left behind after the overwrite.

The default for both of these parameters is false.

When deleting a collection that has an automatically created configset (i.e., the configset was copied from the _default collection when the collection was created), the configset will also be deleted if it is not in use by any other collection.

A request ID (rid) is now logged for all distributed search requests (in SolrCloud) which can be used to correlate query events across the system. A parameter disableRequestId=true can be added to disable this if desired.

As mentioned in the 8.6 upgrade notes, a default autoscaling policy was provided starting in 8.6.0. This default autoscaling policy resulted in increasingly slow collection creation calls in large clusters (50+ collections).

In 8.6.1 the default autoscaling policy has been removed, and clusters will not use autoscaling unless a policy has explicitly been created. If your cluster is running 8.6.0 and not using an explicit autoscaling policy, upgrade to 8.6.1 and remove the default cluster policy and preferences via the following command.

Replace localhost:8983 with your Solr endpoint.

curl -X POST -H 'Content-type:application/json'  -d '{set-cluster-policy : [], set-cluster-preferences : []}' http://localhost:8983/api/cluster/autoscaling

For more details on autoscaling policies, see the section Cluster Policy.

This information is only relevant for users upgrading from 8.6.0. If upgrading from an earlier version to 8.6.1+, this warning can be ignored.

NOTE: The default autoscaling policy has been removed as of 8.6.1

Solr now includes a default autoscaling policy. This policy can be overridden with your custom rules or by specifying an empty policy to replace the default.

For details of the default policy, see the section Cluster Policy.

The ComputePlan action now supports a collection selector to identify collections based on collection properties to determine which collections should be operated on.

Prior to Solr 8.6 Solr APIs which take a file system location, such as core creation, backup, restore, and others, did not validate the path and Solr would allow any absolute or relative path. Starting in 8.6 only paths that are relative to SOLR_HOME, SOLR_DATA_HOME and coreRootDir are allowed by default.

If you need to create a core or store a backup outside the default paths, you will need to tell Solr which paths to allow. A new element in solr.xml called allowPaths takes a comma-separated list of allowed paths.

When using the solr.xml file that ships with 8.6, you can configure the list of paths to allow through the system property solr.allowPaths. Please see bin/solr.in.sh or bin\solr.in.cmd for example usage. Using the value * will allow any path as in earlier versions.

For more on this, see the section Solr.xml Parameters.

Windows SMB shares on the UNC format, such as \\myhost\myshare\mypath are now always disallowed. Please use drive letter mounts instead, i.e., S:\mypath.

A new authorization plugin ExternalRoleRuleBasedAuthorizationPlugin is now available. This plugin allows an authentication plugin (such as JWT) to supply a user’s roles instead of maintaining a user-to-role mapping inside Solr.

When authentication is enabled, the Admin UI Dashboard (main screen) now includes a panel that shows the authentication and authorization plugins in use, the logged in username, and the roles assigned to this user. A new link will also appear in the left-hand navigation to allow a user to log out.

The /export handler now supports streaming expressions to allow limiting the output of the export to only matching documents.

For more information about how to use this, see the section Specifying the Local Streaming Expression.

The stats, facet, and timeseries expressions now support percentiles and standard deviation aggregations.

Cross Data Center Replication (CDCR), in its current form, is deprecated and is scheduled to be removed in 9.0. This feature is unlikely to be replaced by an identical plugin. However, the community is working on figuring out a replacement feature for disaster recovery and failover.

The Data Import Handler (DIH) is deprecated and is scheduled to be removed in 9.0. Work to replace DIH with a community-supported plugin is underway and may be available soon.

Support to store indexes and backups in HDFS is deprecated and is scheduled to be removed in 9.0. A community-supported version of this may be available as a plugin in the future. For more details, please see SOLR-14021.

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:

1. Pause Collection API operations.
2. Cleanup queues (See the section DELETESTATUS for examples) if you use async operations.
3. Upgrade and restart the nodes.
4. Resume all normal operations.

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:

1. Pause Collection API operations.
2. Upgrade and restart all nodes.
3. Cleanup queues (See the section DELETESTATUS for examples) if you use async operations.
4. Resume all normal operations.

The solrconfig.xml file in Solr’s _default configset has been trimmed of the following previously pre-configured items:

• All <lib …​/> directives. This means that Solr Cell (aka Tika), Learning to Rank, Clustering (with Carrot2), language identification, and Velocity (for the /browse sample search interface) are no longer enabled out of the box.

• The /browse, /tvrh, and /update/extract request handlers.

• 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.xml to add them back in, or use the Config API.

  The sample_techproducts_configs and the examples found in ./example are unchanged.

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 lib directories;

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

Our default Jetty configuration has been updated to now set a Content-Security-Policy (CSP) by default. See ./server/etc/jetty.xml for details about how it is configured.

As a result of this change, any custom HTML served by Solr’s HTTP server that contains inline Javascript will no longer execute in modern browsers. The options for you are:

• Change your JavaScript code to not run inline any longer;

• Edit jetty.xml to 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.

SolrJ now supports the shards.preference parameter for single-shard scenarios to ensure multi-shard and single-shard request routing works in the same way.

See Cloud Request Routing and shards.preference Parameter for details.

QueryResponse.getExplainMap() type has changed from Map<String, String> to 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.

The precision stream evaluator can now operate on matrices.

The random streaming expression can now create the x-axis.

Two new aggregations have been added: missing and countvals.

Several aggregations now support multi-valued fields: min, max, avg, sum, sumsq, stddev, variance, and percentile.

After the addition of CaffeineCache in 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.CaffeineCache 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.

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 routedAliasName property to the core.properties file so any external code depending on this location will need to be updated.

Time-routed aliases now include a TRA infix in the collection name, in the pattern <alias>_TRA_<timestamp>.
Collections created with older versions will continue to work.

The behavior of the maxBooleanClauses parameter 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.xml for 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 solr.xml.

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 maxBooleanClauses parameter 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 SolrLogAuditLoggerPlugin is 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.xml has 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.

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.

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 GC_TUNE section of solr.in.sh (*nix) or solr.in.cmd (Windows).