[lucene-solr] 34/47: SOLR-14511: Documented node.sysprop shard preference (#1536)

[so...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sokolov pushed a commit to branch jira/lucene-8962
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git

commit d7762e9fede9ce11bc441718c2d9dfae30da6e83
Author: Radu Gheorghe <ra...@sematext.com>
AuthorDate: Thu May 28 19:41:44 2020 +0300

    SOLR-14511: Documented node.sysprop shard preference (#1536)
    
    * Documented node.sysprop shard preference
    
    For https://issues.apache.org/jira/browse/SOLR-13445
    
    * Added defaultShardPreferences to CLUSTERPROP doc
    
    As implemented via https://issues.apache.org/jira/browse/SOLR-13445
---
 solr/solr-ref-guide/src/cluster-node-management.adoc | 19 ++++++++++++++++++-
 solr/solr-ref-guide/src/distributed-requests.adoc    |  4 ++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/solr/solr-ref-guide/src/cluster-node-management.adoc b/solr/solr-ref-guide/src/cluster-node-management.adoc
index 571666f..e477802 100644
--- a/solr/solr-ref-guide/src/cluster-node-management.adoc
+++ b/solr/solr-ref-guide/src/cluster-node-management.adoc
@@ -131,7 +131,7 @@ Add, edit or delete a cluster-wide property.
 === CLUSTERPROP Parameters
 
 `name`::
-The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode` and `urlScheme`. Other properties can be set
+The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode`, `urlScheme` and `defaultShardPreferences`. Other properties can be set
 (for example, if you need them for custom plugins) but they must begin with the prefix `ext.`. Unknown properties that don't begin with `ext.` will be rejected.
 
 `val`::
@@ -213,6 +213,23 @@ replaced with `defaults`. Using the `collectionDefaults` parameter in Solr 7.4 o
  but the format of the properties will automatically be converted to the new nested structure.
 Support for the "collectionDefaults" key will be removed in Solr 9.
 
+=== Default Shard Preferences
+
+Using the `defaultShardPreferences` parameter, you can implement rack or availability zone awareness. First, make sure to "label" your nodes using a <<configuring-solrconfig-xml.adoc#jvm-system-properties,system property>> (e.g. `-Drack=rack1`). Then, set the value of `defaultShardPreferences` to `node.sysprop:sysprop.YOUR_PROPERTY_NAME` like this:
+
+[source,bash]
+----
+curl -X POST -H 'Content-type:application/json' --data-binary '
+{
+  "set-property" : {
+    "name" : "defaultShardPreferences",
+    "val" : "node.sysprop:sysprop.rack"
+  }
+}' http://localhost:8983/api/cluster
+----
+
+At this point, if you run a query on a node having e.g. `rack=rack1`, Solr will try to hit only replicas from `rack1`.
+
 [[balanceshardunique]]
 == BALANCESHARDUNIQUE: Balance a Property Across Nodes
 
diff --git a/solr/solr-ref-guide/src/distributed-requests.adoc b/solr/solr-ref-guide/src/distributed-requests.adoc
index 7b9a109..191bb85 100644
--- a/solr/solr-ref-guide/src/distributed-requests.adoc
+++ b/solr/solr-ref-guide/src/distributed-requests.adoc
@@ -189,6 +189,10 @@ Applied after sorting by inherent replica attributes, this property defines a fa
 +
 `stable[:hash[:_paramName_]]` the string value associated with the given parameter name is hashed to a dividend that is used to determine replica preference order (analogous to the explicit `dividend` property above); `_paramName_` defaults to `q` if not specified, providing stable routing keyed to the string value of the "main query". Note that this may be inappropriate for some use cases (e.g., static main queries that leverage parameter substitution)
 
+`node.sysprop`::
+Query will be routed to nodes with same defined system properties as the current one. For example, if you start Solr nodes on different racks, you'll want to identify those nodes by a <<configuring-solrconfig-xml.adoc#jvm-system-properties,system property>> (e.g. `-Drack=rack1`). Then, queries can contain `shards.preference=node.sysprop:sysprop.rack`, to make sure you always hit shards with the same value of `rack`.
+
+
 Examples:
 
 * Prefer stable routing (keyed to client "sessionId" param) among otherwise equivalent replicas: