From 85021509faffebe90d42c7c62aedd603deeb243b Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 11 Jun 2025 16:03:23 -0400 Subject: [PATCH] Add docs for `ALTER TABLE ... SCATTER` (also `ALTER INDEX ... SCATTER`) Fixes DOC-286 --- src/current/v25.2/alter-index.md | 58 ++++++++++++++++++++++++ src/current/v25.2/alter-table.md | 76 ++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) diff --git a/src/current/v25.2/alter-index.md b/src/current/v25.2/alter-index.md index eee73759712..70a85e1785e 100644 --- a/src/current/v25.2/alter-index.md +++ b/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 %} diff --git a/src/current/v25.2/alter-table.md b/src/current/v25.2/alter-table.md index b2dd4c6a65f..b2a1020de1e 100644 --- a/src/current/v25.2/alter-table.md +++ b/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 %}