Skip to content

Commit a2f49c5

Browse files
rmlovelandrmloveland
committed
Add docs for ALTER TABLE ... SCATTER
(also `ALTER INDEX ... SCATTER`) Fixes DOC-286 NB. Changes applied to all supported versions v23.2 and later
1 parent 1b3815d commit a2f49c5

File tree

12 files changed

+948
-18
lines changed

12 files changed

+948
-18
lines changed

‎src/current/v23.2/alter-index.md‎

Lines changed: 80 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands).
2525

2626
Parameter | Description
2727
-----------|-------------
28-
`table_name` | The name of the table with the index you want to change.
29-
`index_name` | The current name of the index you want to change.
30-
`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error.
28+
`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change.
29+
`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error.
3130

3231
Additional parameters are documented for the respective [subcommands](#subcommands).
3332

@@ -38,6 +37,7 @@ Subcommand | Description |
3837
[`CONFIGURE ZONE`](#configure-zone) | [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %}) for an index. |
3938
[`PARTITION BY`](#partition-by) | Partition, re-partition, or un-partition an index.
4039
[`RENAME TO`](#rename-to) | Change the name of an index.
40+
[`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. |
4141
[`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.
4242
[`UNSPLIT AT`](#unsplit-at) | Remove a range split enforcement in the index.
4343
[`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
119119

120120
For usage, see [Synopsis](#synopsis).
121121

122+
### `SCATTER`
123+
124+
`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.
125+
126+
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.
127+
128+
{{site.data.alerts.callout_info}}
129+
`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.
130+
{{site.data.alerts.end}}
131+
132+
For examples, refer to [Scatter indexes](#scatter-indexes).
133+
134+
#### Required privileges
135+
136+
The user must have the `INSERT` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the table or index.
137+
138+
#### Parameters
139+
140+
Parameter | Description
141+
----------|-------------
142+
`table_name` | The name of the table that you want to scatter.
143+
`table_index_name` | The name of the index that you want to scatter.
144+
`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.
145+
146+
For usage, see [Synopsis](#synopsis).
147+
122148
### `SPLIT AT`
123149

124150
`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;
343369
(8 rows)
344370
~~~
345371

372+
### Scatter indexes
373+
374+
Before scattering, you can view the current replica and leaseholder distribution for an index:
375+
376+
{% include_cached copy-clipboard.html %}
377+
~~~ sql
378+
WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
379+
~~~
380+
381+
~~~
382+
range_id | lease_holder | replicas
383+
-----------+--------------+-----------
384+
135 | 9 | {2,6,9}
385+
123 | 6 | {2,6,9}
386+
122 | 9 | {2,6,9}
387+
120 | 9 | {3,6,9}
388+
121 | 9 | {3,6,9}
389+
119 | 6 | {2,6,9}
390+
93 | 6 | {1,6,9}
391+
91 | 2 | {2,6,9}
392+
92 | 6 | {2,6,8}
393+
(9 rows)
394+
~~~
395+
396+
{% include_cached copy-clipboard.html %}
397+
~~~ sql
398+
ALTER INDEX rides@rides_pkey SCATTER;
399+
~~~
400+
401+
After scattering, recheck the leaseholder distribution:
402+
403+
{% include_cached copy-clipboard.html %}
404+
~~~ sql
405+
WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
406+
~~~
407+
408+
~~~
409+
range_id | lease_holder | replicas
410+
-----------+--------------+-----------
411+
135 | 9 | {1,6,9}
412+
123 | 5 | {2,5,9}
413+
122 | 5 | {2,5,9}
414+
120 | 6 | {3,6,9}
415+
121 | 3 | {3,6,9}
416+
119 | 5 | {3,5,9}
417+
93 | 5 | {1,5,9}
418+
91 | 1 | {1,5,9}
419+
92 | 5 | {2,5,8}
420+
(9 rows)
421+
~~~
422+
346423
### Split and unsplit indexes
347424

348425
{% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %}

‎src/current/v23.2/alter-table.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ Subcommand | Description | Can combine with other subcommands?
6262
[`SET {storage parameter}`](#set-storage-parameter) | Set a storage parameter on a table. | Yes
6363
[`SET LOCALITY`](#set-locality) | Set the table locality for a table in a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). | No
6464
[`SET SCHEMA`](#set-schema) | Change the [schema]({% link {{ page.version.version }}/sql-name-resolution.md %}) of a table. | No
65+
[`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
6566
[`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
6667
[`UNSPLIT AT`](#unsplit-at) | Remove a range split enforcement in the table. | No
6768
[`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 |
552553

553554
For usage, see [Synopsis](#synopsis).
554555

556+
### `SCATTER`
557+
558+
`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.
559+
560+
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.
561+
562+
{{site.data.alerts.callout_info}}
563+
`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.
564+
{{site.data.alerts.end}}
565+
566+
For examples, see [Scatter tables](#scatter-tables).
567+
568+
#### Required privileges
569+
570+
The user must have the `INSERT` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the table or index.
571+
572+
#### Parameters
573+
574+
Parameter | Description
575+
----------|-------------
576+
`table_name` | The name of the table that you want to scatter.
577+
`table_index_name` | The name of the index that you want to scatter.
578+
`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.
579+
580+
For usage, see [Synopsis](#synopsis).
581+
555582
### `SPLIT AT`
556583

557584
`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:
27922819
(6 rows)
27932820
~~~
27942821
2822+
### Scatter tables
2823+
2824+
Before scattering, you can view the current replica and leaseholder distribution for a table:
2825+
2826+
{% include_cached copy-clipboard.html %}
2827+
~~~ sql
2828+
WITH range_details AS (SHOW RANGES FROM TABLE movr.users WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
2829+
~~~
2830+
2831+
~~~
2832+
range_id | lease_holder | replicas
2833+
-----------+--------------+-----------
2834+
94 | 2 | {2,5,9}
2835+
78 | 3 | {3,5,9}
2836+
77 | 2 | {2,4,9}
2837+
76 | 3 | {3,6,9}
2838+
95 | 3 | {3,5,9}
2839+
75 | 2 | {2,5,8}
2840+
87 | 4 | {2,4,7}
2841+
85 | 2 | {2,5,9}
2842+
86 | 7 | {3,4,7}
2843+
(9 rows)
2844+
~~~
2845+
2846+
{% include_cached copy-clipboard.html %}
2847+
~~~ sql
2848+
ALTER TABLE movr.users SCATTER;
2849+
~~~
2850+
2851+
After scattering, recheck the leaseholder distribution:
2852+
2853+
{% include_cached copy-clipboard.html %}
2854+
~~~ sql
2855+
WITH range_details AS (SHOW RANGES FROM TABLE movr.users WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
2856+
~~~
2857+
2858+
~~~
2859+
range_id | lease_holder | replicas
2860+
-----------+--------------+-----------
2861+
94 | 5 | {2,5,8}
2862+
78 | 1 | {1,5,9}
2863+
77 | 1 | {1,4,9}
2864+
76 | 1 | {1,6,9}
2865+
95 | 1 | {1,5,9}
2866+
75 | 1 | {1,5,8}
2867+
87 | 7 | {2,4,7}
2868+
85 | 1 | {1,5,9}
2869+
86 | 3 | {3,4,7}
2870+
(9 rows)
2871+
~~~
2872+
27952873
### Split and unsplit tables
27962874
27972875
{% include {{page.version.version}}/sql/movr-statements-geo-partitioned-replicas.md %}

‎src/current/v24.1/alter-index.md‎

Lines changed: 80 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,8 @@ Refer to the respective [subcommands](#subcommands).
2525

2626
Parameter | Description
2727
-----------|-------------
28-
`table_name` | The name of the table with the index you want to change.
29-
`index_name` | The current name of the index you want to change.
30-
`IF EXISTS` | Alter the index only if an index `index_name` exists; if one does not exist, do not return an error.
28+
`index_name` | The name of the [index]({% link {{ page.version.version }}/indexes.md %}) you want to change.
29+
`IF EXISTS` | Alter the index only if an index `table_index_name` exists; if one does not exist, do not return an error.
3130

3231
Additional parameters are documented for the respective [subcommands](#subcommands).
3332

@@ -38,6 +37,7 @@ Subcommand | Description |
3837
[`CONFIGURE ZONE`](#configure-zone) | [Replication Controls]({% link {{ page.version.version }}/configure-replication-zones.md %}) for an index. |
3938
[`PARTITION BY`](#partition-by) | Partition, re-partition, or un-partition an index.
4039
[`RENAME TO`](#rename-to) | Change the name of an index.
40+
[`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. |
4141
[`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.
4242
[`UNSPLIT AT`](#unsplit-at) | Remove a range split enforcement in the index.
4343
[`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
119119

120120
For usage, see [Synopsis](#synopsis).
121121

122+
### `SCATTER`
123+
124+
`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.
125+
126+
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.
127+
128+
{{site.data.alerts.callout_info}}
129+
`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.
130+
{{site.data.alerts.end}}
131+
132+
For examples, refer to [Scatter indexes](#scatter-indexes).
133+
134+
#### Required privileges
135+
136+
The user must have the `INSERT` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) on the table or index.
137+
138+
#### Parameters
139+
140+
Parameter | Description
141+
----------|-------------
142+
`table_name` | The name of the table that you want to scatter.
143+
`table_index_name` | The name of the index that you want to scatter.
144+
`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.
145+
146+
For usage, see [Synopsis](#synopsis).
147+
122148
### `SPLIT AT`
123149

124150
`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;
343369
(8 rows)
344370
~~~
345371

372+
### Scatter indexes
373+
374+
Before scattering, you can view the current replica and leaseholder distribution for an index:
375+
376+
{% include_cached copy-clipboard.html %}
377+
~~~ sql
378+
WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
379+
~~~
380+
381+
~~~
382+
range_id | lease_holder | replicas
383+
-----------+--------------+-----------
384+
135 | 9 | {2,6,9}
385+
123 | 6 | {2,6,9}
386+
122 | 9 | {2,6,9}
387+
120 | 9 | {3,6,9}
388+
121 | 9 | {3,6,9}
389+
119 | 6 | {2,6,9}
390+
93 | 6 | {1,6,9}
391+
91 | 2 | {2,6,9}
392+
92 | 6 | {2,6,8}
393+
(9 rows)
394+
~~~
395+
396+
{% include_cached copy-clipboard.html %}
397+
~~~ sql
398+
ALTER INDEX rides@rides_pkey SCATTER;
399+
~~~
400+
401+
After scattering, recheck the leaseholder distribution:
402+
403+
{% include_cached copy-clipboard.html %}
404+
~~~ sql
405+
WITH range_details AS (SHOW RANGES FROM index rides@rides_pkey WITH DETAILS) SELECT range_id, lease_holder, replicas from range_details;
406+
~~~
407+
408+
~~~
409+
range_id | lease_holder | replicas
410+
-----------+--------------+-----------
411+
135 | 9 | {1,6,9}
412+
123 | 5 | {2,5,9}
413+
122 | 5 | {2,5,9}
414+
120 | 6 | {3,6,9}
415+
121 | 3 | {3,6,9}
416+
119 | 5 | {3,5,9}
417+
93 | 5 | {1,5,9}
418+
91 | 1 | {1,5,9}
419+
92 | 5 | {2,5,8}
420+
(9 rows)
421+
~~~
422+
346423
### Split and unsplit indexes
347424

348425
{% include {{ page.version.version }}/sql/movr-statements-geo-partitioned-replicas.md %}

0 commit comments

Comments
 (0)