UNSPLIT AT statement page and diagrams #5360
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| <div><svg width="625" height="191"> | ||
| <polygon points="9 17 1 13 1 21"></polygon> | ||
| <polygon points="17 17 9 13 9 21"></polygon> | ||
| <rect x="31" y="3" width="62" height="32" rx="10"></rect> | ||
| <rect x="29" y="1" width="62" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="39" y="21">ALTER</text> | ||
| <rect x="113" y="3" width="64" height="32" rx="10"></rect> | ||
| <rect x="111" y="1" width="64" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="121" y="21">INDEX</text> | ||
| <rect x="217" y="3" width="96" height="32"></rect> | ||
| <rect x="215" y="1" width="96" height="32" class="nonterminal"></rect> | ||
| <text class="nonterminal" x="225" y="21">table_name</text><rect x="333" y="3" width="32" height="32" rx="10"></rect> | ||
| <rect x="331" y="1" width="32" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="341" y="21">@</text> | ||
| <rect x="385" y="3" width="98" height="32"></rect> | ||
| <rect x="383" y="1" width="98" height="32" class="nonterminal"></rect> | ||
| <text class="nonterminal" x="393" y="21">index_name</text><a xlink:href="sql-grammar.html#standalone_index_name" xlink:title="standalone_index_name"> | ||
| <rect x="217" y="47" width="176" height="32"></rect> | ||
| <rect x="215" y="45" width="176" height="32" class="nonterminal"></rect> | ||
| <text class="nonterminal" x="225" y="65">standalone_index_name</text></a><rect x="523" y="3" width="80" height="32" rx="10"></rect> | ||
| <rect x="521" y="1" width="80" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="531" y="21">UNSPLIT</text> | ||
| <rect x="425" y="113" width="38" height="32" rx="10"></rect> | ||
| <rect x="423" y="111" width="38" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="433" y="131">AT</text><a xlink:href="sql-grammar.html#select_stmt" xlink:title="select_stmt"> | ||
| <rect x="483" y="113" width="94" height="32"></rect> | ||
| <rect x="481" y="111" width="94" height="32" class="nonterminal"></rect> | ||
| <text class="nonterminal" x="491" y="131">select_stmt</text></a><rect x="425" y="157" width="44" height="32" rx="10"></rect> | ||
| <rect x="423" y="155" width="44" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="433" y="175">ALL</text> | ||
| <path class="line" d="m17 17 h2 m0 0 h10 m62 0 h10 m0 0 h10 m64 0 h10 m20 0 h10 m96 0 h10 m0 0 h10 m32 0 h10 m0 0 h10 m98 0 h10 m-306 0 h20 m286 0 h20 m-326 0 q10 0 10 10 m306 0 q0 -10 10 -10 m-316 10 v24 m306 0 v-24 m-306 24 q0 10 10 10 m286 0 q10 0 10 -10 m-296 10 h10 m176 0 h10 m0 0 h90 m20 -44 h10 m80 0 h10 m2 0 l2 0 m2 0 l2 0 m2 0 l2 0 m-242 110 l2 0 m2 0 l2 0 m2 0 l2 0 m22 0 h10 m38 0 h10 m0 0 h10 m94 0 h10 m-192 0 h20 m172 0 h20 m-212 0 q10 0 10 10 m192 0 q0 -10 10 -10 m-202 10 v24 m192 0 v-24 m-192 24 q0 10 10 10 m172 0 q10 0 10 -10 m-182 10 h10 m44 0 h10 m0 0 h108 m23 -44 h-3"></path> | ||
| <polygon points="615 127 623 123 623 131"></polygon> | ||
| <polygon points="615 127 607 123 607 131"></polygon></svg></div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| <div><svg width="631" height="81"> | ||
| <polygon points="9 17 1 13 1 21"></polygon> | ||
| <polygon points="17 17 9 13 9 21"></polygon> | ||
| <rect x="31" y="3" width="62" height="32" rx="10"></rect> | ||
| <rect x="29" y="1" width="62" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="39" y="21">ALTER</text> | ||
| <rect x="113" y="3" width="62" height="32" rx="10"></rect> | ||
| <rect x="111" y="1" width="62" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="121" y="21">TABLE</text> | ||
| <rect x="195" y="3" width="96" height="32"></rect> | ||
| <rect x="193" y="1" width="96" height="32" class="nonterminal"></rect> | ||
| <text class="nonterminal" x="203" y="21">table_name</text><rect x="311" y="3" width="80" height="32" rx="10"></rect> | ||
| <rect x="309" y="1" width="80" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="319" y="21">UNSPLIT</text> | ||
| <rect x="431" y="3" width="38" height="32" rx="10"></rect> | ||
| <rect x="429" y="1" width="38" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="439" y="21">AT</text><a xlink:href="sql-grammar.html#select_stmt" xlink:title="select_stmt"> | ||
| <rect x="489" y="3" width="94" height="32"></rect> | ||
| <rect x="487" y="1" width="94" height="32" class="nonterminal"></rect> | ||
| <text class="nonterminal" x="497" y="21">select_stmt</text></a><rect x="431" y="47" width="44" height="32" rx="10"></rect> | ||
| <rect x="429" y="45" width="44" height="32" class="terminal" rx="10"></rect> | ||
| <text class="terminal" x="439" y="65">ALL</text> | ||
| <path class="line" d="m17 17 h2 m0 0 h10 m62 0 h10 m0 0 h10 m62 0 h10 m0 0 h10 m96 0 h10 m0 0 h10 m80 0 h10 m20 0 h10 m38 0 h10 m0 0 h10 m94 0 h10 m-192 0 h20 m172 0 h20 m-212 0 q10 0 10 10 m192 0 q0 -10 10 -10 m-202 10 v24 m192 0 v-24 m-192 24 q0 10 10 10 m172 0 q10 0 10 -10 m-182 10 h10 m44 0 h10 m0 0 h108 m23 -44 h-3"></path> | ||
| <polygon points="621 17 629 13 629 21"></polygon> | ||
| <polygon points="621 17 613 13 613 21"></polygon></svg></div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,190 @@ | ||
| --- | ||
| title: UNSPLIT AT | ||
| summary: The UNSPLIT AT statement removes a range split enforcement at a specified row in the table or index. | ||
| toc: true | ||
| --- | ||
|
|
||
| The `UNSPLIT AT` [statement](sql-statements.html) removes a [split enforcement](split-at.html) on a [range split](architecture/distribution-layer.html#range-splits), at a specified row in a table or index. | ||
|
|
||
| Removing a split enforcement from a table or index ("unsplitting") allows CockroachDB to merge ranges as needed, to help improve your cluster's performance. For more information, see [Range Merges](range-merges.html). | ||
|
|
||
| ## Synopsis | ||
|
|
||
| <div> | ||
| {% include {{ page.version.version }}/sql/diagrams/unsplit_table_at.html %} | ||
| </div> | ||
|
|
||
| <div> | ||
| {% include {{ page.version.version }}/sql/diagrams/unsplit_index_at.html %} | ||
| </div> | ||
|
|
||
| ## Required privileges | ||
|
|
||
| The user must have the `INSERT` [privilege](authorization.html#assign-privileges) on the table or index. | ||
|
There was a problem hiding this comment. I wish we could link directly to this privilege somehow. |
||
|
|
||
| ## Parameters | ||
|
|
||
| Parameter | Description | ||
| -----------|------------- | ||
| `table_name` | The name of the table that you want to unsplit. | ||
| `table_name @ index_name`<br>`standalone_index_name` | The name of the index that you want to unsplit. | ||
| `select_stmt` | A [selection query](selection-queries.html) that produces one or more rows at which to unsplit a table or index. | ||
|
|
||
| ## Examples | ||
|
|
||
| {% include {{page.version.version}}/sql/movr-statements-nodes.md %} | ||
|
There was a problem hiding this comment. Could the text of |
||
|
|
||
| ### Unsplit a table | ||
|
|
||
| The `crdb_internal.ranges` table contains information about ranges in your CockroachDB cluster. At this point, just one range contains the data in the `users` table: | ||
|
There was a problem hiding this comment. I would reword the last clause slightly to "At this point, the data in the |
||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > SELECT range_id, start_pretty, end_pretty, split_enforced_until FROM crdb_internal.ranges WHERE table_name='users'; | ||
| ~~~ | ||
| ~~~ | ||
| range_id | start_pretty | end_pretty | split_enforced_until | ||
| +----------+--------------+------------+----------------------+ | ||
| 21 | /Table/53 | /Table/54 | NULL | ||
| (1 row) | ||
| ~~~ | ||
|
|
||
| Now split the `users` table ranges based on primary key values: | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > ALTER TABLE users SPLIT AT VALUES ('chicago'), ('new york'), ('seattle'); | ||
| ~~~ | ||
| ~~~ | ||
| key | pretty | split_enforced_until | ||
| +------------------------------+------------------------+----------------------------------+ | ||
| \275\211\022chicago\000\001 | /Table/53/1/"chicago" | 2262-04-11 23:47:16.854776+00:00 | ||
| \275\211\022new york\000\001 | /Table/53/1/"new york" | 2262-04-11 23:47:16.854776+00:00 | ||
| \275\211\022seattle\000\001 | /Table/53/1/"seattle" | 2262-04-11 23:47:16.854776+00:00 | ||
| (3 rows) | ||
| ~~~ | ||
|
|
||
| You can see the additional ranges in the `crdb_internal.ranges` table: | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > SELECT range_id, start_pretty, end_pretty, split_enforced_until FROM crdb_internal.ranges WHERE table_name='users'; | ||
| ~~~ | ||
| ~~~ | ||
| range_id | start_pretty | end_pretty | split_enforced_until | ||
| +----------+------------------------+------------------------+----------------------------------+ | ||
| 21 | /Table/53 | /Table/53/1/"chicago" | NULL | ||
| 27 | /Table/53/1/"chicago" | /Table/53/1/"new york" | 2262-04-11 23:47:16.854776+00:00 | ||
| 28 | /Table/53/1/"new york" | /Table/53/1/"seattle" | 2262-04-11 23:47:16.854776+00:00 | ||
| 29 | /Table/53/1/"seattle" | /Table/54 | 2262-04-11 23:47:16.854776+00:00 | ||
| (4 rows) | ||
| ~~~ | ||
|
|
||
| Now unsplit the table to remove the split enforcements: | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > ALTER TABLE users UNSPLIT AT VALUES ('chicago'), ('new york'), ('seattle'); | ||
| ~~~ | ||
| ~~~ | ||
| key | pretty | ||
| +------------------------------+------------------------+ | ||
| \275\211\022chicago\000\001 | /Table/53/1/"chicago" | ||
| \275\211\022new york\000\001 | /Table/53/1/"new york" | ||
| \275\211\022seattle\000\001 | /Table/53/1/"seattle" | ||
| (3 rows) | ||
| ~~~ | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > SELECT range_id, start_pretty, end_pretty, split_enforced_until FROM crdb_internal.ranges WHERE table_name='users'; | ||
| ~~~ | ||
| ~~~ | ||
| range_id | start_pretty | end_pretty | split_enforced_until | ||
| +----------+------------------------+------------------------+----------------------+ | ||
| 21 | /Table/53 | /Table/53/1/"chicago" | NULL | ||
| 27 | /Table/53/1/"chicago" | /Table/53/1/"new york" | NULL | ||
| 28 | /Table/53/1/"new york" | /Table/53/1/"seattle" | NULL | ||
| 29 | /Table/53/1/"seattle" | /Table/54 | NULL | ||
| (4 rows) | ||
| ~~~ | ||
|
|
||
| The `users` table is still split into ranges at `'chicago'`, `'new york'`, and `'seattle'`, but the `split_enforced_until` column is now `NULL` for all ranges in the table. The split is no longer enforced, and CockroachDB can merge the data in the table as needed. | ||
|
|
||
| ### Unsplit an index | ||
|
|
||
| Add a new secondary [index](indexes.html) to the `rides` table, on the `revenue` column, and then split the table ranges by secondary index values: | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > CREATE INDEX revenue_idx ON rides(revenue); | ||
| ~~~ | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > ALTER INDEX rides@revenue_idx SPLIT AT VALUES (25.00), (50.00), (75.00); | ||
| ~~~ | ||
| ~~~ | ||
| key | pretty | split_enforced_until | ||
| +-------------------+------------------+----------------------------------+ | ||
| \277\214*2\000 | /Table/55/4/25 | 2262-04-11 23:47:16.854776+00:00 | ||
| \277\214*d\000 | /Table/55/4/5E+1 | 2262-04-11 23:47:16.854776+00:00 | ||
| \277\214*\226\000 | /Table/55/4/75 | 2262-04-11 23:47:16.854776+00:00 | ||
| (3 rows) | ||
| ~~~ | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > SELECT range_id, start_pretty, end_pretty, split_enforced_until FROM crdb_internal.ranges WHERE table_name='rides'; | ||
| ~~~ | ||
| ~~~ | ||
| range_id | start_pretty | end_pretty | split_enforced_until | ||
| +----------+------------------+------------------+----------------------------------+ | ||
| 23 | /Table/55 | /Table/55/4 | NULL | ||
| 32 | /Table/55/4 | /Table/55/4/25 | 2019-09-10 21:27:35.056275+00:00 | ||
| 33 | /Table/55/4/25 | /Table/55/4/5E+1 | 2262-04-11 23:47:16.854776+00:00 | ||
| 34 | /Table/55/4/5E+1 | /Table/55/4/75 | 2262-04-11 23:47:16.854776+00:00 | ||
| 35 | /Table/55/4/75 | /Table/56 | 2262-04-11 23:47:16.854776+00:00 | ||
| (5 rows) | ||
| ~~~ | ||
|
|
||
| Now unsplit the index to remove the split enforcements: | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > ALTER INDEX rides@revenue_idx UNSPLIT AT VALUES (25.00), (50.00), (75.00); | ||
| ~~~ | ||
| ~~~ | ||
| key | pretty | ||
| +-------------------+------------------+ | ||
| \277\214*2\000 | /Table/55/4/25 | ||
| \277\214*d\000 | /Table/55/4/5E+1 | ||
| \277\214*\226\000 | /Table/55/4/75 | ||
| (3 rows) | ||
| ~~~ | ||
|
|
||
| {% include copy-clipboard.html %} | ||
| ~~~ sql | ||
| > SELECT range_id, start_pretty, end_pretty, split_enforced_until FROM crdb_internal.ranges WHERE table_name='rides'; | ||
| ~~~ | ||
| ~~~ | ||
| range_id | start_pretty | end_pretty | split_enforced_until | ||
| +----------+------------------+------------------+----------------------------------+ | ||
| 23 | /Table/55 | /Table/55/4 | NULL | ||
| 32 | /Table/55/4 | /Table/55/4/25 | 2019-09-10 21:27:35.056275+00:00 | ||
| 33 | /Table/55/4/25 | /Table/55/4/5E+1 | NULL | ||
| 34 | /Table/55/4/5E+1 | /Table/55/4/75 | NULL | ||
| 35 | /Table/55/4/75 | /Table/56 | NULL | ||
| (5 rows) | ||
| ~~~ | ||
|
|
||
| The table is still split into ranges at `25.00`, `50.00`, and `75.00`, but the `split_enforced_until` column is now `NULL` for all ranges in the table. The split is no longer enforced, and CockroachDB can merge the data in the table as needed. | ||
|
|
||
| ## See also | ||
|
|
||
|
There was a problem hiding this comment. I think we should also link to the Range Merges doc here. |
||
| - [`SPLIT AT`](split-at.html) | ||
| - [Selection Queries](selection-queries.html) | ||
| - [Distribution Layer](architecture/distribution-layer.html) | ||
| - [Range Merges](range-merges.html) | ||
| - [Replication Layer](architecture/replication-layer.html) | ||
| - [`SHOW JOBS`](show-jobs.html) | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These diagrams look great!