diff --git a/src/current/v23.2/alter-index.md b/src/current/v23.2/alter-index.md index eee73759712..6b686f7fd0d 100644 --- a/src/current/v23.2/alter-index.md +++ b/src/current/v23.2/alter-index.md @@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands). Parameter | Description -----------|------------- -`table_name` | The name of the table with the index you want to change. -`index_name` | The current name of the index you want to change. -`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error. +`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change. +`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error. Additional parameters are documented for the respective [subcommands](#subcommands). @@ -38,6 +37,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) | Make a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that this statement does not return an error even if replicas are not moved. | [`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 +119,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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, refer to [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 +369,57 @@ SHOW INDEXES FROM users; (8 rows) ~~~ +### Scatter indexes + +Before scattering, you can view the current replica and leaseholder distribution for an index: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {2,6,9} + 123 | 6 | {2,6,9} + 122 | 9 | {2,6,9} + 120 | 9 | {3,6,9} + 121 | 9 | {3,6,9} + 119 | 6 | {2,6,9} + 93 | 6 | {1,6,9} + 91 | 2 | {2,6,9} + 92 | 6 | {2,6,8} +(9 rows) +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER INDEX rides@rides_pkey SCATTER; +~~~ + +After scattering, recheck the leaseholder distribution: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {1,6,9} + 123 | 5 | {2,5,9} + 122 | 5 | {2,5,9} + 120 | 6 | {3,6,9} + 121 | 3 | {3,6,9} + 119 | 5 | {3,5,9} + 93 | 5 | {1,5,9} + 91 | 1 | {1,5,9} + 92 | 5 | {2,5,8} +(9 rows) +~~~ + ### Split and unsplit indexes {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v23.2/alter-table.md b/src/current/v23.2/alter-table.md index c7628b37115..d374d303954 100644 --- a/src/current/v23.2/alter-table.md +++ b/src/current/v23.2/alter-table.md @@ -62,6 +62,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) | Makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that it does not return an error even if replicas are not moved. | 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 @@ -552,6 +553,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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. @@ -2792,6 +2819,57 @@ Then, change the table's schema: (6 rows) ~~~ +### Scatter tables + +Before scattering, you can view the current replica and 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 +-----------+--------------+----------- + 94 | 2 | {2,5,9} + 78 | 3 | {3,5,9} + 77 | 2 | {2,4,9} + 76 | 3 | {3,6,9} + 95 | 3 | {3,5,9} + 75 | 2 | {2,5,8} + 87 | 4 | {2,4,7} + 85 | 2 | {2,5,9} + 86 | 7 | {3,4,7} +(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 +-----------+--------------+----------- + 94 | 5 | {2,5,8} + 78 | 1 | {1,5,9} + 77 | 1 | {1,4,9} + 76 | 1 | {1,6,9} + 95 | 1 | {1,5,9} + 75 | 1 | {1,5,8} + 87 | 7 | {2,4,7} + 85 | 1 | {1,5,9} + 86 | 3 | {3,4,7} +(9 rows) +~~~ + ### Split and unsplit tables {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v24.1/alter-index.md b/src/current/v24.1/alter-index.md index eee73759712..6b686f7fd0d 100644 --- a/src/current/v24.1/alter-index.md +++ b/src/current/v24.1/alter-index.md @@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands). Parameter | Description -----------|------------- -`table_name` | The name of the table with the index you want to change. -`index_name` | The current name of the index you want to change. -`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error. +`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change. +`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error. Additional parameters are documented for the respective [subcommands](#subcommands). @@ -38,6 +37,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) | Make a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that this statement does not return an error even if replicas are not moved. | [`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 +119,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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, refer to [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 +369,57 @@ SHOW INDEXES FROM users; (8 rows) ~~~ +### Scatter indexes + +Before scattering, you can view the current replica and leaseholder distribution for an index: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {2,6,9} + 123 | 6 | {2,6,9} + 122 | 9 | {2,6,9} + 120 | 9 | {3,6,9} + 121 | 9 | {3,6,9} + 119 | 6 | {2,6,9} + 93 | 6 | {1,6,9} + 91 | 2 | {2,6,9} + 92 | 6 | {2,6,8} +(9 rows) +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER INDEX rides@rides_pkey SCATTER; +~~~ + +After scattering, recheck the leaseholder distribution: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {1,6,9} + 123 | 5 | {2,5,9} + 122 | 5 | {2,5,9} + 120 | 6 | {3,6,9} + 121 | 3 | {3,6,9} + 119 | 5 | {3,5,9} + 93 | 5 | {1,5,9} + 91 | 1 | {1,5,9} + 92 | 5 | {2,5,8} +(9 rows) +~~~ + ### Split and unsplit indexes {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v24.1/alter-table.md b/src/current/v24.1/alter-table.md index 5ed01b220d3..30192484011 100644 --- a/src/current/v24.1/alter-table.md +++ b/src/current/v24.1/alter-table.md @@ -62,6 +62,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) | Makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that it does not return an error even if replicas are not moved. | 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 @@ -541,6 +542,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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. @@ -2781,6 +2808,57 @@ Then, change the table's schema: (6 rows) ~~~ +### Scatter tables + +Before scattering, you can view the current replica and 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 +-----------+--------------+----------- + 94 | 2 | {2,5,9} + 78 | 3 | {3,5,9} + 77 | 2 | {2,4,9} + 76 | 3 | {3,6,9} + 95 | 3 | {3,5,9} + 75 | 2 | {2,5,8} + 87 | 4 | {2,4,7} + 85 | 2 | {2,5,9} + 86 | 7 | {3,4,7} +(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 +-----------+--------------+----------- + 94 | 5 | {2,5,8} + 78 | 1 | {1,5,9} + 77 | 1 | {1,4,9} + 76 | 1 | {1,6,9} + 95 | 1 | {1,5,9} + 75 | 1 | {1,5,8} + 87 | 7 | {2,4,7} + 85 | 1 | {1,5,9} + 86 | 3 | {3,4,7} +(9 rows) +~~~ + ### Split and unsplit tables {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v24.3/alter-index.md b/src/current/v24.3/alter-index.md index eee73759712..6b686f7fd0d 100644 --- a/src/current/v24.3/alter-index.md +++ b/src/current/v24.3/alter-index.md @@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands). Parameter | Description -----------|------------- -`table_name` | The name of the table with the index you want to change. -`index_name` | The current name of the index you want to change. -`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error. +`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change. +`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error. Additional parameters are documented for the respective [subcommands](#subcommands). @@ -38,6 +37,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) | Make a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that this statement does not return an error even if replicas are not moved. | [`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 +119,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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, refer to [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 +369,57 @@ SHOW INDEXES FROM users; (8 rows) ~~~ +### Scatter indexes + +Before scattering, you can view the current replica and leaseholder distribution for an index: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {2,6,9} + 123 | 6 | {2,6,9} + 122 | 9 | {2,6,9} + 120 | 9 | {3,6,9} + 121 | 9 | {3,6,9} + 119 | 6 | {2,6,9} + 93 | 6 | {1,6,9} + 91 | 2 | {2,6,9} + 92 | 6 | {2,6,8} +(9 rows) +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER INDEX rides@rides_pkey SCATTER; +~~~ + +After scattering, recheck the leaseholder distribution: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {1,6,9} + 123 | 5 | {2,5,9} + 122 | 5 | {2,5,9} + 120 | 6 | {3,6,9} + 121 | 3 | {3,6,9} + 119 | 5 | {3,5,9} + 93 | 5 | {1,5,9} + 91 | 1 | {1,5,9} + 92 | 5 | {2,5,8} +(9 rows) +~~~ + ### Split and unsplit indexes {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v24.3/alter-table.md b/src/current/v24.3/alter-table.md index 5ed01b220d3..30192484011 100644 --- a/src/current/v24.3/alter-table.md +++ b/src/current/v24.3/alter-table.md @@ -62,6 +62,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) | Makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that it does not return an error even if replicas are not moved. | 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 @@ -541,6 +542,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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. @@ -2781,6 +2808,57 @@ Then, change the table's schema: (6 rows) ~~~ +### Scatter tables + +Before scattering, you can view the current replica and 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 +-----------+--------------+----------- + 94 | 2 | {2,5,9} + 78 | 3 | {3,5,9} + 77 | 2 | {2,4,9} + 76 | 3 | {3,6,9} + 95 | 3 | {3,5,9} + 75 | 2 | {2,5,8} + 87 | 4 | {2,4,7} + 85 | 2 | {2,5,9} + 86 | 7 | {3,4,7} +(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 +-----------+--------------+----------- + 94 | 5 | {2,5,8} + 78 | 1 | {1,5,9} + 77 | 1 | {1,4,9} + 76 | 1 | {1,6,9} + 95 | 1 | {1,5,9} + 75 | 1 | {1,5,8} + 87 | 7 | {2,4,7} + 85 | 1 | {1,5,9} + 86 | 3 | {3,4,7} +(9 rows) +~~~ + ### Split and unsplit tables {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v25.2/alter-index.md b/src/current/v25.2/alter-index.md index eee73759712..6b686f7fd0d 100644 --- a/src/current/v25.2/alter-index.md +++ b/src/current/v25.2/alter-index.md @@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands). Parameter | Description -----------|------------- -`table_name` | The name of the table with the index you want to change. -`index_name` | The current name of the index you want to change. -`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error. +`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change. +`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error. Additional parameters are documented for the respective [subcommands](#subcommands). @@ -38,6 +37,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) | Make a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that this statement does not return an error even if replicas are not moved. | [`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 +119,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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, refer to [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 +369,57 @@ SHOW INDEXES FROM users; (8 rows) ~~~ +### Scatter indexes + +Before scattering, you can view the current replica and leaseholder distribution for an index: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {2,6,9} + 123 | 6 | {2,6,9} + 122 | 9 | {2,6,9} + 120 | 9 | {3,6,9} + 121 | 9 | {3,6,9} + 119 | 6 | {2,6,9} + 93 | 6 | {1,6,9} + 91 | 2 | {2,6,9} + 92 | 6 | {2,6,8} +(9 rows) +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER INDEX rides@rides_pkey SCATTER; +~~~ + +After scattering, recheck the leaseholder distribution: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {1,6,9} + 123 | 5 | {2,5,9} + 122 | 5 | {2,5,9} + 120 | 6 | {3,6,9} + 121 | 3 | {3,6,9} + 119 | 5 | {3,5,9} + 93 | 5 | {1,5,9} + 91 | 1 | {1,5,9} + 92 | 5 | {2,5,8} +(9 rows) +~~~ + ### 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 589944bbaef..a952ea00636 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) | Makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that it does not return an error even if replicas are not moved. | 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,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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. @@ -2833,6 +2860,57 @@ Then, change the table's schema: (6 rows) ~~~ +### Scatter tables + +Before scattering, you can view the current replica and 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 +-----------+--------------+----------- + 94 | 2 | {2,5,9} + 78 | 3 | {3,5,9} + 77 | 2 | {2,4,9} + 76 | 3 | {3,6,9} + 95 | 3 | {3,5,9} + 75 | 2 | {2,5,8} + 87 | 4 | {2,4,7} + 85 | 2 | {2,5,9} + 86 | 7 | {3,4,7} +(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 +-----------+--------------+----------- + 94 | 5 | {2,5,8} + 78 | 1 | {1,5,9} + 77 | 1 | {1,4,9} + 76 | 1 | {1,6,9} + 95 | 1 | {1,5,9} + 75 | 1 | {1,5,8} + 87 | 7 | {2,4,7} + 85 | 1 | {1,5,9} + 86 | 3 | {3,4,7} +(9 rows) +~~~ + ### Split and unsplit tables {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v25.3/alter-index.md b/src/current/v25.3/alter-index.md index eee73759712..6b686f7fd0d 100644 --- a/src/current/v25.3/alter-index.md +++ b/src/current/v25.3/alter-index.md @@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands). Parameter | Description -----------|------------- -`table_name` | The name of the table with the index you want to change. -`index_name` | The current name of the index you want to change. -`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error. +`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change. +`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error. Additional parameters are documented for the respective [subcommands](#subcommands). @@ -38,6 +37,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) | Make a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that this statement does not return an error even if replicas are not moved. | [`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 +119,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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, refer to [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 +369,57 @@ SHOW INDEXES FROM users; (8 rows) ~~~ +### Scatter indexes + +Before scattering, you can view the current replica and leaseholder distribution for an index: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {2,6,9} + 123 | 6 | {2,6,9} + 122 | 9 | {2,6,9} + 120 | 9 | {3,6,9} + 121 | 9 | {3,6,9} + 119 | 6 | {2,6,9} + 93 | 6 | {1,6,9} + 91 | 2 | {2,6,9} + 92 | 6 | {2,6,8} +(9 rows) +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER INDEX rides@rides_pkey SCATTER; +~~~ + +After scattering, recheck the leaseholder distribution: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {1,6,9} + 123 | 5 | {2,5,9} + 122 | 5 | {2,5,9} + 120 | 6 | {3,6,9} + 121 | 3 | {3,6,9} + 119 | 5 | {3,5,9} + 93 | 5 | {1,5,9} + 91 | 1 | {1,5,9} + 92 | 5 | {2,5,8} +(9 rows) +~~~ + ### Split and unsplit indexes {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v25.3/alter-table.md b/src/current/v25.3/alter-table.md index e12b3c94926..9f0679c48c0 100644 --- a/src/current/v25.3/alter-table.md +++ b/src/current/v25.3/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) | Makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that it does not return an error even if replicas are not moved. | 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,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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. @@ -2999,6 +3026,57 @@ Then, change the table's schema: (6 rows) ~~~ +### Scatter tables + +Before scattering, you can view the current replica and 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 +-----------+--------------+----------- + 94 | 2 | {2,5,9} + 78 | 3 | {3,5,9} + 77 | 2 | {2,4,9} + 76 | 3 | {3,6,9} + 95 | 3 | {3,5,9} + 75 | 2 | {2,5,8} + 87 | 4 | {2,4,7} + 85 | 2 | {2,5,9} + 86 | 7 | {3,4,7} +(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 +-----------+--------------+----------- + 94 | 5 | {2,5,8} + 78 | 1 | {1,5,9} + 77 | 1 | {1,4,9} + 76 | 1 | {1,6,9} + 95 | 1 | {1,5,9} + 75 | 1 | {1,5,8} + 87 | 7 | {2,4,7} + 85 | 1 | {1,5,9} + 86 | 3 | {3,4,7} +(9 rows) +~~~ + ### Split and unsplit tables {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v25.4/alter-index.md b/src/current/v25.4/alter-index.md index eee73759712..6b686f7fd0d 100644 --- a/src/current/v25.4/alter-index.md +++ b/src/current/v25.4/alter-index.md @@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands). Parameter | Description -----------|------------- -`table_name` | The name of the table with the index you want to change. -`index_name` | The current name of the index you want to change. -`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error. +`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change. +`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error. Additional parameters are documented for the respective [subcommands](#subcommands). @@ -38,6 +37,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) | Make a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that this statement does not return an error even if replicas are not moved. | [`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 +119,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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, refer to [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 +369,57 @@ SHOW INDEXES FROM users; (8 rows) ~~~ +### Scatter indexes + +Before scattering, you can view the current replica and leaseholder distribution for an index: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {2,6,9} + 123 | 6 | {2,6,9} + 122 | 9 | {2,6,9} + 120 | 9 | {3,6,9} + 121 | 9 | {3,6,9} + 119 | 6 | {2,6,9} + 93 | 6 | {1,6,9} + 91 | 2 | {2,6,9} + 92 | 6 | {2,6,8} +(9 rows) +~~~ + +{% include_cached copy-clipboard.html %} +~~~ sql +ALTER INDEX rides@rides_pkey SCATTER; +~~~ + +After scattering, recheck the leaseholder distribution: + +{% include_cached copy-clipboard.html %} +~~~ sql +WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details; +~~~ + +~~~ + range_id | lease_holder | replicas +-----------+--------------+----------- + 135 | 9 | {1,6,9} + 123 | 5 | {2,5,9} + 122 | 5 | {2,5,9} + 120 | 6 | {3,6,9} + 121 | 3 | {3,6,9} + 119 | 5 | {3,5,9} + 93 | 5 | {1,5,9} + 91 | 1 | {1,5,9} + 92 | 5 | {2,5,8} +(9 rows) +~~~ + ### Split and unsplit indexes {% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %} diff --git a/src/current/v25.4/alter-table.md b/src/current/v25.4/alter-table.md index fd9b74ac986..d87e7812434 100644 --- a/src/current/v25.4/alter-table.md +++ b/src/current/v25.4/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) | Makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of a table or index. Note that it does not return an error even if replicas are not moved. | 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,32 @@ 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. + +Note that this statement makes a best-effort attempt to redistribute replicas and leaseholders for the ranges of an index. It does not return an error even if replicas are not moved. + +{{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. @@ -2999,6 +3026,57 @@ Then, change the table's schema: (6 rows) ~~~ +### Scatter tables + +Before scattering, you can view the current replica and 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 +-----------+--------------+----------- + 94 | 2 | {2,5,9} + 78 | 3 | {3,5,9} + 77 | 2 | {2,4,9} + 76 | 3 | {3,6,9} + 95 | 3 | {3,5,9} + 75 | 2 | {2,5,8} + 87 | 4 | {2,4,7} + 85 | 2 | {2,5,9} + 86 | 7 | {3,4,7} +(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 +-----------+--------------+----------- + 94 | 5 | {2,5,8} + 78 | 1 | {1,5,9} + 77 | 1 | {1,4,9} + 76 | 1 | {1,6,9} + 95 | 1 | {1,5,9} + 75 | 1 | {1,5,8} + 87 | 7 | {2,4,7} + 85 | 1 | {1,5,9} + 86 | 3 | {3,4,7} +(9 rows) +~~~ + ### Split and unsplit tables {% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %}