Add docs for ALTER TABLE ... SCATTER

(also `ALTER INDEX ... SCATTER`)

Fixes DOC-286

Author: rmloveland

src/current/v25.2/alter-index.md

@@ -38,6 +38,7 @@ Subcommand | Description |
 [`CONFIGURE ZONE`](#configure-zone) | [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %}) for an index. | 
 [`PARTITION BY`](#partition-by)  | Partition, re-partition, or un-partition an index.
 [`RENAME TO`](#rename-to) | Change the name of an index.
+[`SCATTER`](#scatter) | Redistribute leaseholders for the ranges of a table or index. |
 [`SPLIT AT`](#split-at) | Force a [range split]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) at the specified row in the index.
 [`UNSPLIT AT`](#unsplit-at) | Remove a range split enforcement in the index.
 [`VISIBILITY`](#visibility) | Set the visibility of an index between a range of `0.0` and `1.0`.
@@ -119,6 +120,30 @@ The user must have the `CREATE` [privilege]({% link {{ page.version.version }}/s
 
 For usage, see [Synopsis](#synopsis).
 
+### `SCATTER`
+
+`ALTER INDEX ... SCATTER` runs a specified set of ranges for a table or index through the [replication layer]({% link {{ page.version.version }}/architecture/replication-layer.md %}) queue. If many ranges have been created recently, the replication queue may transfer some leases to other replicas to balance load across the cluster. Some leaseholders may not update as a result of this command.
+
+{{site.data.alerts.callout_info}}
+`SCATTER` has the potential to result in data movement proportional to the size of the table or index being scattered, thus taking additional time and resources to complete.
+{{site.data.alerts.end}}
+
+For examples, see [Scatter indexes](#scatter-indexes).
+
+#### Required privileges
+
+The user must have the `INSERT` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the table or index.
+
+#### Parameters
+
+Parameter | Description
+----------|-------------
+`table_name` | The name of the table that you want to scatter.
+`table_index_name` | The name of the index that you want to scatter.
+`expr_list` | A list of [scalar expressions]({% link {{ page.version.version }}/scalar-expressions.md %}) in the form of the primary key of the table or the specified index.
+
+For usage, see [Synopsis](#synopsis).
+
 ### `SPLIT AT`
 
 `ALTER INDEX ... SPLIT AT` forces a [range split]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) at a specified row in the index.
@@ -343,6 +368,39 @@ SHOW INDEXES FROM users;
 (8 rows)
 ~~~
 
+### Scatter indexes
+
+Before scattering, you can view the current leaseholder distribution for an index:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+WITH range_details AS (SHOW RANGES FROM DATABASE movr WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
+~~~
+
+~~~
+  range_id | lease_holder | replicas
+-----------+--------------+-----------
+        94 |            1 | {1}
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+> ALTER INDEX rides@revenue_idx SCATTER;
+~~~
+
+After scattering, recheck the leaseholder distribution:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+WITH range_details AS (SHOW RANGES FROM DATABASE movr WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
+~~~
+
+~~~
+  range_id | lease_holder | replicas
+-----------+--------------+-----------
+        94 |            1 | {1}
+~~~
+
 ### Split and unsplit indexes
 
 {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %}

src/current/v25.2/alter-table.md

@@ -65,6 +65,7 @@ Subcommand | Description | Can combine with other subcommands?
 [`SET {storage parameter}`](#set-storage-parameter) | Set a storage parameter on a table. | Yes
 [`SET LOCALITY`](#set-locality) |  Set the table locality for a table in a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). | No
 [`SET SCHEMA`](#set-schema) |  Change the [schema]({% link {{ page.version.version }}/sql-name-resolution.md %}) of a table. | No
+[`SCATTER`](#scatter) | Redistribute leaseholders for the ranges of a table or index. | No
 [`SPLIT AT`](#split-at) | Force a [range split]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) at the specified row in the table. | No
 [`UNSPLIT AT`](#unsplit-at) | Remove a range split enforcement in the table. | No
 [`VALIDATE CONSTRAINT`](#validate-constraint) | Check whether values in a column match a [constraint]({% link {{ page.version.version }}/constraints.md %}) on the column. | Yes
@@ -602,6 +603,30 @@ Parameter | Description |
 
 For usage, see [Synopsis](#synopsis).
 
+### `SCATTER`
+
+`ALTER TABLE ... SCATTER` runs a specified set of ranges for a table or index through the [replication layer]({% link {{ page.version.version }}/architecture/replication-layer.md %}) queue. If many ranges have been created recently, the replication queue may transfer some leases to other replicas to balance load across the cluster. Some leaseholders may not update as a result of this command.
+
+{{site.data.alerts.callout_info}}
+`SCATTER` has the potential to result in data movement proportional to the size of the table or index being scattered, thus taking additional time and resources to complete.
+{{site.data.alerts.end}}
+
+For examples, see [Scatter tables](#scatter-tables).
+
+#### Required privileges
+
+The user must have the `INSERT` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the table or index.
+
+#### Parameters
+
+Parameter | Description
+----------|-------------
+`table_name` | The name of the table that you want to scatter.
+`table_index_name` | The name of the index that you want to scatter.
+`expr_list` | A list of [scalar expressions]({% link {{ page.version.version }}/scalar-expressions.md %}) in the form of the primary key of the table or the specified index.
+
+For usage, see [Synopsis](#synopsis).
+
 ### `SPLIT AT`
 
 `ALTER TABLE ... SPLIT AT` forces a [range split]({% link {{ page.version.version }}/architecture/distribution-layer.md %}#range-splits) at a specified row in the table.
@@ -2827,6 +2852,57 @@ Then, change the table's schema:
 (6 rows)
 ~~~
 
+### Scatter tables
+
+Before scattering, you can view the current leaseholder distribution for a table:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+WITH range_details AS (SHOW RANGES FROM TABLE movr.users WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
+~~~
+
+~~~
+  range_id | lease_holder | replicas
+-----------+--------------+-----------
+        99 |            1 | {1}
+        82 |            1 | {1}
+        81 |            1 | {1}
+        77 |            1 | {1}
+        80 |            1 | {1}
+        75 |            1 | {1}
+        79 |            1 | {1}
+        76 |            1 | {1}
+        78 |            1 | {1}
+(9 rows)
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER TABLE movr.users SCATTER;
+~~~
+
+After scattering, recheck the leaseholder distribution:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+WITH range_details AS (SHOW RANGES FROM TABLE movr.users WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
+~~~
+
+~~~
+  range_id | lease_holder | replicas
+-----------+--------------+-----------
+        99 |            1 | {1}
+        82 |            1 | {1}
+        81 |            1 | {1}
+        77 |            1 | {1}
+        80 |            1 | {1}
+        75 |            1 | {1}
+        79 |            1 | {1}
+        76 |            1 | {1}
+        78 |            1 | {1}
+(9 rows)
+~~~
+
 ### Split and unsplit tables
 
 {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %}