DOC-141/auto-shard-rebalance (#1064)

* added cluster rebalance docublocks * Update examples for 3.10 in DOC-141/auto-shard-rebalance at 2022-08-01T15:48:16+00:00 * release notes, api changes, description * Update administration-cluster.md * fixed docublock name Co-authored-by: ansoboleva <93702078+ansoboleva@users.noreply.github.com> Co-authored-by: arangodb-release-bot <anastasia.soboleva@arangodb.com>

Author: nerpaula

3.10/administration-cluster.md

@@ -175,9 +175,33 @@ feature does not have its own sharding strategy, it uses `hash` instead.
 Moving/Rebalancing _shards_
 ---------------------------
 
+Rebalancing redistributes resources in the cluster to optimise resource
+allocation - shards and location of leaders/followers.
+
+It aims to achieve, for example, a balanced load, fair shard distribution,
+and resiliency.
+
+Rebalancing might occur, amongst other scenarios, when:
+- There is a change in the number of nodes in the cluster and more (or fewer)
+resources are available to the cluster.
+- There is a detectable imbalance in the distribution of shards
+(i.e. specific nodes holding high number of shards while others don’t) or in
+the distribution of leaders/followers across the nodes, resulting in
+computational imbalance on the nodes.
+- There are changes in the number or size of data collections.
+
 A _shard_ can be moved from a _DB-Server_ to another, and the entire shard distribution
 can be rebalanced using the corresponding buttons in the web [UI](programs-web-interface-cluster.html).
 
+You can also do any of the following by using the API:
+- Calculate the current cluster imbalance.
+- Compute a set of move shard operations to improve balance.
+- Execute the given set of move shard operations.
+- Compute a set of move shard operations to improve balance and immediately execute them.
+
+For more information, see the [Cluster Administration & Monitoring](http/administration-and-monitoring.html#calculates-the-current-cluster-imbalance) 
+section of the HTTP API reference manual.
+
 Replacing/Removing a _Coordinator_
 ----------------------------------
 

3.10/generated/Examples/001_collectionAll.generated

@@ -2,62 +2,62 @@ arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/110&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;110&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN----&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnG--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;two&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/112&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;112&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN---_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK---&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;three&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/114&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;114&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN---A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK--_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;four&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/116&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;116&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNC---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK--A&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;five&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/118&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;118&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNC--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK--B&quot;</span> 
 }
 arangosh&gt; db.five.all().toArray();
 [ 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;110&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/110&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN----&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnG--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;one&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;112&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/112&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN---_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK---&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;two&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;114&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/114&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN---A&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;three&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;116&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/116&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNC---&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK--A&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;four&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;118&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/118&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNC--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWnK--B&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;five&quot;</span> 
  } 
 ]

3.10/generated/Examples/002_collectionAllNext.generated

@@ -2,44 +2,44 @@ arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/130&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;130&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNy--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---_&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;two&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/132&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;132&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNy--A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---A&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;three&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/134&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;134&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN2---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---B&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;four&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/136&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;136&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN2--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---C&quot;</span> 
 }
 arangosh&gt; db.five.insert({ <span class="hljs-attr">name</span> : <span class="hljs-string">&quot;five&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/138&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;138&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxN2--A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---D&quot;</span> 
 }
 arangosh&gt; db.five.all().limit(<span class="hljs-number">2</span>).toArray();
 [ 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;130&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/130&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNy--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;one&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;132&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;five/132&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxNy--A&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo---A&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;two&quot;</span> 
  } 
 ]

3.10/generated/Examples/003_collectionByExample.generated

@@ -2,38 +2,38 @@ arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/150&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;150&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOC--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--_&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Helmut&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/152&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;152&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOG---&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--A&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Angela&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/154&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;154&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOG--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--B&quot;</span> 
 }
 arangosh&gt; db.users.all().toArray();
 [ 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;150&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/150&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOC--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Gerhard&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;152&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/152&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOG---&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--A&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Helmut&quot;</span> 
  }, 
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;154&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/154&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOG--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--B&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Angela&quot;</span> 
  } 
 ]
@@ -44,7 +44,7 @@ arangosh&gt; db.users.byExample({ <span class="hljs-string">&quot;name&quot;</sp
  { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;150&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/150&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOC--_&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoO--_&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Gerhard&quot;</span> 
  } 
 ]

3.10/generated/Examples/004_collectionByExampleNext.generated

@@ -2,25 +2,25 @@ arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class=
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/172&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;172&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOW--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoi--_&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Helmut&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/174&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;174&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOW--A&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWoi--A&quot;</span> 
 }
 arangosh&gt; db.users.insert({ <span class="hljs-attr">name</span>: <span class="hljs-string">&quot;Angela&quot;</span> });
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/176&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;176&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOW--B&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWom---&quot;</span> 
 }
 arangosh&gt; <span class="hljs-keyword">var</span> a = db.users.byExample( {<span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Angela&quot;</span> } );
 arangosh&gt; <span class="hljs-keyword">while</span> (a.hasNext()) print(a.next());
 { 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;176&quot;</span>, 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;users/176&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOW--B&quot;</span>, 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWom---&quot;</span>, 
  <span class="hljs-string">&quot;name&quot;</span> : <span class="hljs-string">&quot;Angela&quot;</span> 
 }

3.10/generated/Examples/011_documentsCollectionReplaceByExample.generated

@@ -2,7 +2,7 @@ arangosh&gt; db.example.insert({ <span class="hljs-attr">Hello</span> : <span cl
 { 
  <span class="hljs-string">&quot;_id&quot;</span> : <span class="hljs-string">&quot;example/198&quot;</span>, 
  <span class="hljs-string">&quot;_key&quot;</span> : <span class="hljs-string">&quot;198&quot;</span>, 
- <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejlqxOu--_&quot;</span> 
+ <span class="hljs-string">&quot;_rev&quot;</span> : <span class="hljs-string">&quot;_ejmUWo6--_&quot;</span> 
 }
 arangosh&gt; db.example.replaceByExample({ <span class="hljs-attr">Hello</span>: <span class="hljs-string">&quot;world&quot;</span> }, {<span class="hljs-attr">Hello</span>: <span class="hljs-string">&quot;mars&quot;</span>}, <span class="hljs-literal">false</span>, <span class="hljs-number">5</span>);
 <span class="hljs-number">1</span>