SOLR-17915: Add shards.preference=replica.location:host (#3654)

(cherry picked from commit aa81f20)

Author: HoustonPutman

solr/CHANGES.txt

@@ -7,7 +7,7 @@ https://github.com/apache/solr/blob/main/solr/solr-ref-guide/modules/upgrade-not
 ==================  9.10.0 ==================
 New Features
 ---------------------
-(No changes)
+* SOLR-17915: shards.preference=replica.location now supports the "host" option for routing to replicas on the same host. (Houston Putman)
 
 Improvements
 ---------------------

solr/core/src/java/org/apache/solr/handler/StreamHandler.java

@@ -213,6 +213,7 @@ public void handleRequestBody(SolrQueryRequest req, SolrQueryResponse rsp) throw
                   .toString(),
               zkController.getNodeName(),
               zkController.getBaseUrl(),
+              zkController.getHostName(),
               zkController.getSysPropsCacher());
     } else {
       requestReplicaListTransformerGenerator = new RequestReplicaListTransformerGenerator();

solr/core/src/java/org/apache/solr/handler/component/HttpShardHandlerFactory.java

@@ -409,6 +409,7 @@ protected ReplicaListTransformer getReplicaListTransformer(final SolrQueryReques
               .toString(),
           zkController.getNodeName(),
           zkController.getBaseUrl(),
+          zkController.getHostName(),
           zkController.getSysPropsCacher());
     } else {
       return requestReplicaListTransformerGenerator.getReplicaListTransformer(params);

solr/solr-ref-guide/modules/deployment-guide/pages/solrcloud-distributed-requests.adoc

@@ -183,22 +183,26 @@ One or more replica types that are preferred.
 Any combination of `PULL`, `TLOG` and `NRT` is allowed.
 
 `replica.location`::
-One or more replica locations that are preferred.
-+
-A location starts with `http://hostname:port`.
-Matching is done for the given string as a prefix, so it's possible to e.g., leave out the port.
-+
-A special value `local` may be used to denote any local replica running on the same Solr instance as the one handling the query.
+Prefer replicas that match the given location. Available options are:
+- `local` - Replicas in the same Solr instance as the one handling the query.
 This is useful when a query requests many fields or large fields to be returned per document because it avoids moving large amounts of data over the network when it is available locally.
 In addition, this feature can be useful for minimizing the impact of a problematic replica with degraded performance, as it reduces the likelihood that the degraded replica will be hit by other healthy replicas.
 +
 The value of `replica.location:local` diminishes as the number of shards (that have no locally-available replicas) in a collection increases because the query controller will have to direct the query to non-local replicas for most of the shards.
 +
 In other words, this feature is mostly useful for optimizing queries directed towards collections with a small number of shards and many replicas.
+- `host` - Replicas in Solr instances running on the same host as the one handling the query.
+This can be useful in many of the same ways as `local`, but can help spare network costs when multiple Solr instances are running per host.
 +
-Also, this option should only be used if you are load balancing requests across all nodes that host replicas for the collection you are querying, as Solr's `CloudSolrClient` will do.
+As the number of shards grows, `replica.location:host` may be more useful than `replica.location:local`, since it is more likely that all shards can be found on the same host than all shards being found in the same Solr instance.
+- `_host-prefix_` - A replica location starts with `http://hostname:port`, i.e. `replica.location:http://hostname:port`.
+Matching is done for the given string as a prefix, so it's possible to e.g., leave out the port.
+
+IMPORTANT: The `local` and `host` options should only be used if you are load balancing requests across all nodes that host replicas for the collection you are querying, as Solr's `CloudSolrClient` will do.
 If not load-balancing, this feature can introduce a hotspot in the cluster since queries won't be evenly distributed across the cluster.
 
+NOTE: The `local` and `host` options are equivalent when only 1 Solr node is running on each host. This is also true in a setup like Kubernetes where each Solr node has a unique hostname.
+
 `replica.base`::
 Applied after sorting by inherent replica attributes, this property defines a fallback ordering among sets of preference-equivalent replicas; if specified, only one value may be specified for this property, and it must be specified last.
 +
@@ -252,10 +256,10 @@ shards.preference=replica.location:local
 [source,text]
 shards.preference=replica.location:http://server1,replica.location:http://server2
 
-* Prefer PULL replicas if available, otherwise TLOG replicas, and local replicas among those:
+* Prefer PULL replicas if available, otherwise TLOG replicas, and among those, replicas on the same host:
 +
 [source,text]
-shards.preference=replica.type:PULL,replica.type:TLOG,replica.location:local
+shards.preference=replica.type:PULL,replica.type:TLOG,replica.location:host
 
 * Prefer local replicas, and among them PULL replicas when available, otherwise TLOG replicas:
 +
@@ -352,7 +356,7 @@ For example, the following line makes Solr use the `ExactStatsCache` implementat
 
 The query param distrib.statsCache defaults to `true`. If set to `false`, distributed calls to fetch global term stats is turned off for this query. This can reduce overhead for queries that do not utilize distributed IDF for score calculation.
 
-[source,xml]
+[source,plain]
 ----
 http://localhost:8987/solr/collection1/select?q=*%3A*&wt=json&fq={!terms f=id}id1,id2&distrib.statsCache=false
 ----

solr/solrj-streaming/src/test/org/apache/solr/client/solrj/io/stream/StreamingTest.java

@@ -2822,7 +2822,7 @@ public void testTupleStreamGetShardsPreference() throws Exception {
     streamContext.setSolrClientCache(new SolrClientCache());
     streamContext.setRequestReplicaListTransformerGenerator(
         new RequestReplicaListTransformerGenerator(
-            ShardParams.SHARDS_PREFERENCE_REPLICA_TYPE + ":TLOG", null, null, null));
+            ShardParams.SHARDS_PREFERENCE_REPLICA_TYPE + ":TLOG", null, null, null, null));
 
     streamContext.setRequestParams(
         params(ShardParams.SHARDS_PREFERENCE, ShardParams.SHARDS_PREFERENCE_REPLICA_TYPE + ":nrt"));