From b395e577451eab6bade68e8be7afe945c9eead22 Mon Sep 17 00:00:00 2001 From: Eric Harmeling Date: Thu, 29 Aug 2019 11:38:40 -0400 Subject: [PATCH 1/2] UNSPLIT AT statement page and diagrams --- _includes/sidebar-data-v19.2.json | 6 + .../v19.2/sql/diagrams/unsplit_index_at.html | 33 +++ .../v19.2/sql/diagrams/unsplit_table_at.html | 25 +++ _includes/v19.2/sql/movr-start-nodes.md | 2 +- _includes/v19.2/sql/movr-statements-nodes.md | 2 +- .../v19.2/sql/movr-statements-partitioning.md | 2 +- v19.2/alter-index.md | 3 +- v19.2/alter-table.md | 3 +- v19.2/split-at.md | 12 +- v19.2/sql-statements.md | 3 +- v19.2/unsplit-at.md | 190 ++++++++++++++++++ 11 files changed, 267 insertions(+), 14 deletions(-) create mode 100644 _includes/v19.2/sql/diagrams/unsplit_index_at.html create mode 100644 _includes/v19.2/sql/diagrams/unsplit_table_at.html create mode 100644 v19.2/unsplit-at.md diff --git a/_includes/sidebar-data-v19.2.json b/_includes/sidebar-data-v19.2.json index 10ea6df1ad1..b7ac1bd3b7e 100644 --- a/_includes/sidebar-data-v19.2.json +++ b/_includes/sidebar-data-v19.2.json @@ -1219,6 +1219,12 @@ "/${VERSION}/truncate.html" ] }, + { + "title": "UNSPLIT AT", + "urls": [ + "/${VERSION}/unsplit-at.html" + ] + }, { "title": "UPDATE", "urls": [ diff --git a/_includes/v19.2/sql/diagrams/unsplit_index_at.html b/_includes/v19.2/sql/diagrams/unsplit_index_at.html new file mode 100644 index 00000000000..40cbbbf7116 --- /dev/null +++ b/_includes/v19.2/sql/diagrams/unsplit_index_at.html @@ -0,0 +1,33 @@ +
+ + + + +ALTER + + +INDEX + + +table_name + +@ + + +index_name + + +standalone_index_name + +UNSPLIT + + +AT + + +select_stmt + +ALL + + +
diff --git a/_includes/v19.2/sql/diagrams/unsplit_table_at.html b/_includes/v19.2/sql/diagrams/unsplit_table_at.html new file mode 100644 index 00000000000..797c0beda03 --- /dev/null +++ b/_includes/v19.2/sql/diagrams/unsplit_table_at.html @@ -0,0 +1,25 @@ +
+ + + + +ALTER + + +TABLE + + +table_name + +UNSPLIT + + +AT + + +select_stmt + +ALL + + +
diff --git a/_includes/v19.2/sql/movr-start-nodes.md b/_includes/v19.2/sql/movr-start-nodes.md index 830301d6e3f..913f2ee8107 100644 --- a/_includes/v19.2/sql/movr-start-nodes.md +++ b/_includes/v19.2/sql/movr-start-nodes.md @@ -1,4 +1,4 @@ -Run [`cockroach demo`](cockroach-demo.html) with the `--nodes` and `--demo-locality` tags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). +Run [`cockroach demo`](cockroach-demo.html) with the [`--nodes`](cockroach-demo.html#general) and [`--demo-locality`](cockroach-demo.html#general) flags This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). {% include copy-clipboard.html %} ~~~ shell diff --git a/_includes/v19.2/sql/movr-statements-nodes.md b/_includes/v19.2/sql/movr-statements-nodes.md index 2147f158b7c..f8fae23f793 100644 --- a/_includes/v19.2/sql/movr-statements-nodes.md +++ b/_includes/v19.2/sql/movr-statements-nodes.md @@ -2,7 +2,7 @@ The following examples use MovR, a fictional vehicle-sharing application, to demonstrate CockroachDB SQL statements. For more information about the MovR example application and dataset, see [MovR: A Global Vehicle-sharing App](movr.html). -To follow along, run [`cockroach demo`](cockroach-demo.html) with the `--nodes` and `--demo-locality` tags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). +To follow along, run [`cockroach demo`](cockroach-demo.html) with the [`--nodes`](cockroach-demo.html#general) and [`--demo-locality`](cockroach-demo.html#general) flags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). {% include copy-clipboard.html %} ~~~ shell diff --git a/_includes/v19.2/sql/movr-statements-partitioning.md b/_includes/v19.2/sql/movr-statements-partitioning.md index 3daa8ae2554..83c275dea45 100644 --- a/_includes/v19.2/sql/movr-statements-partitioning.md +++ b/_includes/v19.2/sql/movr-statements-partitioning.md @@ -1,6 +1,6 @@ The following examples use MovR, a fictional vehicle-sharing application, to demonstrate CockroachDB SQL statements. For more information about the MovR example application and dataset, see [MovR: A Global Vehicle-sharing App](movr.html). -To follow along with the partitioning examples below, open a new terminal and run [`cockroach demo`](cockroach-demo.html) with the `--nodes` and `--demo-locality` tags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). +To follow along with the partitioning examples below, open a new terminal and run [`cockroach demo`](cockroach-demo.html) with the [`--nodes`](cockroach-demo.html#general) and [`--demo-locality`](cockroach-demo.html#general) flags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). {% include copy-clipboard.html %} ~~~ shell diff --git a/v19.2/alter-index.md b/v19.2/alter-index.md index b4e630ec84b..729cee6d981 100644 --- a/v19.2/alter-index.md +++ b/v19.2/alter-index.md @@ -16,4 +16,5 @@ Subcommand | Description -----------|------------ [`CONFIGURE ZONE`](configure-zone.html) | [Configure replication zones](configure-replication-zones.html) for an index. [`RENAME`](rename-index.html) | Change the name of an index. -[`SPLIT AT`](split-at.html) | Force a key-value layer range split at the specified row in the index. +[`SPLIT AT`](split-at.html) | Force a range split at the specified row in the index. +[`UNSPLIT AT`](unsplit-at.html) | New in v19.2: Remove a range split enforcement at a specified row in the index. diff --git a/v19.2/alter-table.md b/v19.2/alter-table.md index 066183f7133..c4e0d3279cd 100644 --- a/v19.2/alter-table.md +++ b/v19.2/alter-table.md @@ -34,7 +34,8 @@ Subcommand | Description | Can combine with other subcommands? [`RENAME COLUMN`](rename-column.html) | Change the names of columns. | Yes [`RENAME CONSTRAINT`](rename-constraint.html) | Change constraints columns. | Yes [`RENAME TABLE`](rename-table.html) | Change the names of tables. | No -[`SPLIT AT`](split-at.html) | Force a key-value layer range split at the specified row in the table. | No +[`SPLIT AT`](split-at.html) | Force a range split at the specified row in the table. | No +[`UNSPLIT AT`](unsplit-at.html) | New in v19.2: Remove a range split enforcement at a specified row in the table. | No [`VALIDATE CONSTRAINT`](validate-constraint.html) | Check whether values in a column match a [constraint](constraints.html) on the column. | Yes ## Viewing schema changes diff --git a/v19.2/split-at.md b/v19.2/split-at.md index f6abe79cedf..79a4a42777e 100644 --- a/v19.2/split-at.md +++ b/v19.2/split-at.md @@ -1,10 +1,10 @@ --- title: SPLIT AT -summary: The SPLIT AT statement forces a key-value layer range split at the specified row in a table or index. +summary: The SPLIT AT statement forces a range split at the specified row in a table or index. toc: true --- -The `SPLIT AT` [statement](sql-statements.html) forces a key-value layer range split at the specified row in a table or index. +The `SPLIT AT` [statement](sql-statements.html) forces a range split at the specified row in a table or index. ## Synopsis @@ -27,14 +27,9 @@ The user must have the `INSERT` [privilege](authorization.html#assign-privileges `table_name`
`table_name @ index_name` | The name of the table or index that should be split. `select_stmt` | A [selection query](selection-queries.html) that produces one or more rows at which to split the table or index. -## Viewing schema changes - -{% include {{ page.version.version }}/misc/schema-change-view-job.md %} - ## Why manually split a range? -The key-value layer of CockroachDB is broken into sections of contiguous -key-space known as ranges. By default, CockroachDB attempts to keep ranges below +CockroachDB breaks data into ranges. By default, CockroachDB attempts to keep ranges below a size of 64MiB. To do this, the system will automatically [split](architecture/distribution-layer.html#range-splits) a range if it grows larger than this limit. For most use cases, this automatic range splitting is sufficient, and you should never need to worry about @@ -252,3 +247,4 @@ SHOW RANGES FROM TABLE t; - [Distribution Layer](architecture/distribution-layer.html) - [Replication Layer](architecture/replication-layer.html) - [`SHOW JOBS`](show-jobs.html) +- New in v19.2: [`UNSPLIT AT`](unsplit-at.html) diff --git a/v19.2/sql-statements.md b/v19.2/sql-statements.md index 876f28fed6a..f500c5e2dcc 100644 --- a/v19.2/sql-statements.md +++ b/v19.2/sql-statements.md @@ -77,7 +77,8 @@ Statement | Usage [`SHOW TABLES`](show-tables.html) | List tables or views in a database or virtual schema. [`SHOW RANGES`](show-ranges.html) | Show range information about a specific table or index. [`SHOW ZONE CONFIGURATIONS`](show-zone-configurations.html) | List details about existing [replication zones](configure-replication-zones.html). -[`SPLIT AT`](split-at.html) | Force a key-value layer range split at the specified row in the table or index. +[`SPLIT AT`](split-at.html) | Force a range split at the specified row in the table or index. +[`UNSPLIT AT`](unsplit-at.html) | New in v19.2: Remove a range split enforcement at a specified row in the table or index. [`VALIDATE CONSTRAINT`](validate-constraint.html) | Check whether values in a column match a [constraint](constraints.html) on the column. ## Transaction management statements diff --git a/v19.2/unsplit-at.md b/v19.2/unsplit-at.md new file mode 100644 index 00000000000..f98e19a97d6 --- /dev/null +++ b/v19.2/unsplit-at.md @@ -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 + +
+ {% include {{ page.version.version }}/sql/diagrams/unsplit_table_at.html %} +
+ +
+ {% include {{ page.version.version }}/sql/diagrams/unsplit_index_at.html %} +
+ +## Required privileges + +The user must have the `INSERT` [privilege](authorization.html#assign-privileges) on the table or index. + +## Parameters + + Parameter | Description +-----------|------------- + `table_name` | The name of the table that you want to unsplit. + `table_name @ index_name`
`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 %} + +### 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: + +{% 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 + +- [`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) From 8bcf770f9d113c6f3d5f272ce989fed58c8031e7 Mon Sep 17 00:00:00 2001 From: Eric Harmeling Date: Mon, 16 Sep 2019 15:18:11 -0400 Subject: [PATCH 2/2] - SPLIT AT movr examples added - WITH EXPIRATION added to SPLIT AT (new diagrams, new parameter, new example) --- .../v19.2/sql/diagrams/split_index_at.html | 76 +++---- .../v19.2/sql/diagrams/split_table_at.html | 60 ++--- .../v19.2/sql/movr-statements-partitioning.md | 4 +- v19.2/split-at.md | 206 ++++++++++-------- v19.2/unsplit-at.md | 8 +- 5 files changed, 183 insertions(+), 171 deletions(-) diff --git a/_includes/v19.2/sql/diagrams/split_index_at.html b/_includes/v19.2/sql/diagrams/split_index_at.html index b4325de91c5..840830a8c92 100644 --- a/_includes/v19.2/sql/diagrams/split_index_at.html +++ b/_includes/v19.2/sql/diagrams/split_index_at.html @@ -1,38 +1,38 @@ -
- - - - - - ALTER - - - INDEX - - - - table_name - - - - @ - - - - index_name - - - - SPLIT - - - AT - - - - select_stmt - - - - -
\ No newline at end of file +
+ + + + +ALTER + + +INDEX + + +table_name + +@ + + +index_name + + +standalone_index_name + +SPLIT + + +AT + + +select_stmt + +WITH + + +EXPIRATION + + +a_expr + +
diff --git a/_includes/v19.2/sql/diagrams/split_table_at.html b/_includes/v19.2/sql/diagrams/split_table_at.html index a694595b9b5..2b7b43c5a59 100644 --- a/_includes/v19.2/sql/diagrams/split_table_at.html +++ b/_includes/v19.2/sql/diagrams/split_table_at.html @@ -1,30 +1,30 @@ -
- - - - - - ALTER - - - TABLE - - - - table_name - - - - SPLIT - - - AT - - - - select_stmt - - - - -
\ No newline at end of file +
+ + + + +ALTER + + +TABLE + + +table_name + +SPLIT + + +AT + + +select_stmt + +WITH + + +EXPIRATION + + +a_expr + +
diff --git a/_includes/v19.2/sql/movr-statements-partitioning.md b/_includes/v19.2/sql/movr-statements-partitioning.md index 83c275dea45..7a865b68ce2 100644 --- a/_includes/v19.2/sql/movr-statements-partitioning.md +++ b/_includes/v19.2/sql/movr-statements-partitioning.md @@ -1,6 +1,6 @@ The following examples use MovR, a fictional vehicle-sharing application, to demonstrate CockroachDB SQL statements. For more information about the MovR example application and dataset, see [MovR: A Global Vehicle-sharing App](movr.html). -To follow along with the partitioning examples below, open a new terminal and run [`cockroach demo`](cockroach-demo.html) with the [`--nodes`](cockroach-demo.html#general) and [`--demo-locality`](cockroach-demo.html#general) flags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). +To follow along with the examples below, open a new terminal and run [`cockroach demo`](cockroach-demo.html) with the [`--nodes`](cockroach-demo.html#general) and [`--demo-locality`](cockroach-demo.html#general) flags. This command opens an interactive SQL shell to a temporary, multi-node in-memory cluster with the `movr` database preloaded and set as the [current database](sql-name-resolution.html#current-database). {% include copy-clipboard.html %} ~~~ shell @@ -8,5 +8,3 @@ $ cockroach demo \ --nodes=9 \ --demo-locality=region=us-east1:region=us-east1:region=us-east1:region=us-central1:region=us-central1:region=us-central1:region=us-west1:region=us-west1:region=us-west1 ~~~ - -{% include {{page.version.version}}/sql/partitioning-enterprise.md %} diff --git a/v19.2/split-at.md b/v19.2/split-at.md index 79a4a42777e..91791850f14 100644 --- a/v19.2/split-at.md +++ b/v19.2/split-at.md @@ -26,6 +26,7 @@ The user must have the `INSERT` [privilege](authorization.html#assign-privileges -----------|------------- `table_name`
`table_name @ index_name` | The name of the table or index that should be split. `select_stmt` | A [selection query](selection-queries.html) that produces one or more rows at which to split the table or index. + `a_expr` | The expiration of the split enforcement on the table or index. This can be a [`DECIMAL`](decimal.html), [`INTERVAL`](interval.html), [`TIMESTAMP`](timestamp.html), or [`TIMESTAMPZ`](timestamp.html). ## Why manually split a range? @@ -57,190 +58,203 @@ Note that when a table is [truncated](truncate.html), it is essentially re-creat ## Examples +### Setup + +{% include {{page.version.version}}/sql/movr-statements-partitioning.md %} + ### Split a table {% include copy-clipboard.html %} ~~~ sql -> SHOW RANGES FROM TABLE kv; +> SHOW RANGES FROM TABLE users; ~~~ ~~~ -+-----------+---------+----------+----------+--------------+ -| start_key | end_key | range_id | replicas | lease_holder | -+-----------+---------+----------+----------+--------------+ -| NULL | NULL | 72 | {1} | 1 | -+-----------+---------+----------+----------+--------------+ + start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities ++-----------+---------+----------+---------------+--------------+-----------------------+----------+------------------------------------------------------+ + NULL | NULL | 25 | 0.005563 | 8 | region=us-west1 | {3,5,8} | {region=us-east1,region=us-central1,region=us-west1} (1 row) ~~~ {% include copy-clipboard.html %} ~~~ sql -> ALTER TABLE kv SPLIT AT VALUES (10), (20), (30); +> ALTER TABLE users SPLIT AT VALUES ('chicago'), ('new york'), ('seattle'); ~~~ ~~~ -+------------+----------------+ -| key | pretty | -+------------+----------------+ -| \u0209\x92 | /Table/64/1/10 | -| \u0209\x9c | /Table/64/1/20 | -| \u0209\xa6 | /Table/64/1/30 | -+------------+----------------+ + 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) ~~~ {% include copy-clipboard.html %} ~~~ sql -> SHOW RANGES FROM TABLE kv; +> SHOW RANGES FROM TABLE users; ~~~ ~~~ -+-----------+---------+----------+----------+--------------+ -| start_key | end_key | range_id | replicas | lease_holder | -+-----------+---------+----------+----------+--------------+ -| NULL | /10 | 72 | {1} | 1 | -| /10 | /20 | 73 | {1} | 1 | -| /20 | /30 | 74 | {1} | 1 | -| /30 | NULL | 75 | {1} | 1 | -+-----------+---------+----------+----------+--------------+ + start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities ++-------------+-------------+----------+---------------+--------------+-----------------------+----------+------------------------------------------------------+ + NULL | /"chicago" | 25 | 0.000872 | 8 | region=us-west1 | {3,5,8} | {region=us-east1,region=us-central1,region=us-west1} + /"chicago" | /"new york" | 45 | 0.001943 | 8 | region=us-west1 | {3,5,8} | {region=us-east1,region=us-central1,region=us-west1} + /"new york" | /"seattle" | 46 | 0.00184 | 8 | region=us-west1 | {3,5,8} | {region=us-east1,region=us-central1,region=us-west1} + /"seattle" | NULL | 47 | 0.000908 | 7 | region=us-west1 | {1,4,7} | {region=us-east1,region=us-central1,region=us-west1} (4 rows) ~~~ -### Split a table with a composite primary key +### Split a table with a compound primary key -You may want to split a table with a composite primary key (e.g., when working with [partitions](partitioning.html#partition-using-primary-key)). +You may want to split a table with a compound primary key. -Given the table +Suppose that you want MovR to offer ride-sharing services, in addition to vehicle-sharing services. Some users need to sign up to be drivers, so you need a `drivers` table to store driver information. {% include copy-clipboard.html %} ~~~ sql -CREATE TABLE t (k1 INT, k2 INT, v INT, w INT, PRIMARY KEY (k1, k2)); +> CREATE TABLE drivers ( + id UUID DEFAULT gen_random_uuid(), + city STRING, + name STRING, + dl STRING DEFAULT left(md5(random()::text),8) UNIQUE CHECK (LENGTH(dl) < 9), + address STRING, + CONSTRAINT "primary" PRIMARY KEY (city ASC, dl ASC) +); ~~~ -we can split it at its primary key like so: +The table's compound primary key is on the `city` and `dl` columns. Note that the table automatically generates an `id` and a `dl` [using supported SQL functions](https://www.cockroachlabs.com/docs/v19.2/functions-and-operators.html), if they are not provided. + +Because this table has several columns in common with the `users` table, you can populate the table with values from the `users` table with an `INSERT` statement: {% include copy-clipboard.html %} ~~~ sql -ALTER TABLE t SPLIT AT VALUES (5,1), (5,2), (5,3); -~~~ - -~~~ -+------------+-----------------+ -| key | pretty | -+------------+-----------------+ -| \xbc898d89 | /Table/52/1/5/1 | -| \xbc898d8a | /Table/52/1/5/2 | -| \xbc898d8b | /Table/52/1/5/3 | -+------------+-----------------+ -(3 rows) +> INSERT INTO drivers (id, city, name, address) + SELECT id, city, name, address FROM users; ~~~ -To see more information about the range splits, run: - {% include copy-clipboard.html %} ~~~ sql -SHOW RANGES FROM TABLE t; +> SHOW RANGES FROM TABLE drivers; ~~~ ~~~ -+-----------+---------+----------+----------+--------------+ -| start_key | end_key | range_id | replicas | lease_holder | -+-----------+---------+----------+----------+--------------+ -| NULL | /5/1 | 151 | {2,3,5} | 5 | -| /5/1 | /5/2 | 152 | {2,3,5} | 5 | -| /5/2 | /5/3 | 153 | {2,3,5} | 5 | -| /5/3 | NULL | 154 | {2,3,5} | 5 | -+-----------+---------+----------+----------+--------------+ -(4 rows) + start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities ++-----------+---------+----------+---------------+--------------+-----------------------+----------+------------------------------------------------------+ + NULL | NULL | 45 | 0.007222 | 6 | region=us-central1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} +(1 row) ~~~ -Alternatively, you could split at a prefix of the primary key columns. For example, to add a split before all keys that start with `3`, run: +Now you can split the table based on the compound primary key. Note that you don't have to specify the entire value for the primary key, just the prefix. {% include copy-clipboard.html %} ~~~ sql -> ALTER TABLE t SPLIT AT VALUES (3); +> ALTER TABLE drivers SPLIT AT VALUES ('new york', '3'), ('new york', '7'), ('chicago', '3'), ('chicago', '7'), ('seattle', '3'), ('seattle', '7'); ~~~ ~~~ -+----------+---------------+ -| key | pretty | -+----------+---------------+ -| \xcd898b | /Table/69/1/3 | -+----------+---------------+ -(1 row) + key | pretty | split_enforced_until ++-------------------------------------------+----------------------------+----------------------------------+ + \303\211\022new york\000\001\0223\000\001 | /Table/59/1/"new york"/"3" | 2262-04-11 23:47:16.854776+00:00 + \303\211\022new york\000\001\0227\000\001 | /Table/59/1/"new york"/"7" | 2262-04-11 23:47:16.854776+00:00 + \303\211\022chicago\000\001\0223\000\001 | /Table/59/1/"chicago"/"3" | 2262-04-11 23:47:16.854776+00:00 + \303\211\022chicago\000\001\0227\000\001 | /Table/59/1/"chicago"/"7" | 2262-04-11 23:47:16.854776+00:00 + \303\211\022seattle\000\001\0223\000\001 | /Table/59/1/"seattle"/"3" | 2262-04-11 23:47:16.854776+00:00 + \303\211\022seattle\000\001\0227\000\001 | /Table/59/1/"seattle"/"7" | 2262-04-11 23:47:16.854776+00:00 +(6 rows) ~~~ -Conceptually, this means that the second range will include keys that start with `3` through `∞`: - {% include copy-clipboard.html %} ~~~ sql -SHOW RANGES FROM TABLE t; +> SHOW RANGES FROM TABLE drivers; ~~~ ~~~ -+-----------+---------+----------+----------+--------------+ -| start_key | end_key | range_id | replicas | lease_holder | -+-----------+---------+----------+----------+--------------+ -| NULL | /3 | 155 | {2,3,5} | 5 | -| /3 | NULL | 165 | {2,3,5} | 5 | -+-----------+---------+----------+----------+--------------+ -(2 rows) + start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities ++-----------------+-----------------+----------+---------------+--------------+-----------------------+----------+---------------------------------------------------------+ + NULL | /"chicago"/"3" | 45 | 0.000792 | 6 | region=us-central1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /"chicago"/"3" | /"chicago"/"7" | 48 | 0.000316 | 1 | region=us-east1 | {1,5,6} | {region=us-east1,region=us-central1,region=us-central1} + /"chicago"/"7" | /"new york"/"3" | 49 | 0.001452 | 6 | region=us-central1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /"new york"/"3" | /"new york"/"7" | 46 | 0.000094 | 6 | region=us-central1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /"new york"/"7" | /"seattle"/"3" | 47 | 0.001865 | 9 | region=us-west1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /"seattle"/"3" | /"seattle"/"7" | 50 | 0.000106 | 9 | region=us-west1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /"seattle"/"7" | NULL | 51 | 0.002597 | 9 | region=us-west1 | {1,6,9} | {region=us-east1,region=us-central1,region=us-west1} +(7 rows) ~~~ ### Split an index +Add a new secondary [index](indexes.html) to the `rides` table, on the `revenue` column: + {% include copy-clipboard.html %} ~~~ sql -> CREATE INDEX secondary ON kv (v); +> CREATE INDEX revenue_idx ON rides(revenue); ~~~ +Then split the table ranges by secondary index values: + {% include copy-clipboard.html %} ~~~ sql -> SHOW RANGES FROM INDEX kv@secondary; +> ALTER INDEX rides@revenue_idx SPLIT AT VALUES (25.00), (50.00), (75.00); ~~~ - ~~~ -+-----------+---------+----------+----------+--------------+ -| start_key | end_key | range_id | replicas | lease_holder | -+-----------+---------+----------+----------+--------------+ -| NULL | NULL | 75 | {1} | 1 | -+-----------+---------+----------+----------+--------------+ -(1 row) + 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 -> ALTER INDEX kv@secondary SPLIT AT (SELECT v FROM kv LIMIT 3); +> SHOW RANGES FROM INDEX rides@revenue_idx; +~~~ ~~~ + start_key | end_key | range_id | range_size_mb | lease_holder | lease_holder_locality | replicas | replica_localities ++-----------+---------+----------+---------------+--------------+-----------------------+----------+------------------------------------------------------+ + NULL | /25 | 55 | 0.007446 | 6 | region=us-central1 | {3,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /25 | /5E+1 | 56 | 0.008951 | 6 | region=us-central1 | {3,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /5E+1 | /75 | 57 | 0.008205 | 2 | region=us-east1 | {2,6,9} | {region=us-east1,region=us-central1,region=us-west1} + /75 | NULL | 60 | 0.009322 | 6 | region=us-central1 | {2,6,9} | {region=us-east1,region=us-central1,region=us-west1} +(4 rows) +~~~ + +### Set the expiration on a split enforcement +You can specify the time at which a split enforcement expires by adding a `WITH EXPIRATION` clause to your `SPLIT` statement. Supported expiration values include [`DECIMAL`](decimal.html), [`INTERVAL`](interval.html), [`TIMESTAMP`](timestamp.html), and [`TIMESTAMPZ`](timestamp.html). + +{% include copy-clipboard.html %} +~~~ sql +> ALTER TABLE vehicles SPLIT AT VALUES ('chicago'), ('new york'), ('seattle') WITH EXPIRATION '2020-01-10 23:30:00+00:00'; ~~~ -+---------------------+-----------------+ -| key | pretty | -+---------------------+-----------------+ -| \u020b\x12a\x00\x01 | /Table/64/3/"a" | -| \u020b\x12b\x00\x01 | /Table/64/3/"b" | -| \u020b\x12c\x00\x01 | /Table/64/3/"c" | -+---------------------+-----------------+ +~~~ + key | pretty | split_enforced_until ++------------------------------+------------------------+---------------------------+ + \276\211\022chicago\000\001 | /Table/54/1/"chicago" | 2020-01-10 23:30:00+00:00 + \276\211\022new york\000\001 | /Table/54/1/"new york" | 2020-01-10 23:30:00+00:00 + \276\211\022seattle\000\001 | /Table/54/1/"seattle" | 2020-01-10 23:30:00+00:00 (3 rows) ~~~ +You can see the split's expiration date in the `split_enforced_until` column. The `crdb_internal.ranges` table also contains information about ranges in your CockroachDB cluster, including the `split_enforced_until` column. + {% include copy-clipboard.html %} ~~~ sql -> SHOW RANGES FROM INDEX kv@secondary; +> SELECT range_id, start_pretty, end_pretty, split_enforced_until FROM crdb_internal.ranges WHERE table_name='vehicles'; ~~~ ~~~ -+-----------+---------+----------+----------+--------------+ -| start_key | end_key | range_id | replicas | lease_holder | -+-----------+---------+----------+----------+--------------+ -| NULL | /"a" | 75 | {1} | 1 | -| /"a" | /"b" | 76 | {1} | 1 | -| /"b" | /"c" | 77 | {1} | 1 | -| /"c" | NULL | 78 | {1} | 1 | -+-----------+---------+----------+----------+--------------+ + range_id | start_pretty | end_pretty | split_enforced_until ++----------+------------------------+------------------------+---------------------------+ + 26 | /Table/54 | /Table/54/1/"chicago" | NULL + 75 | /Table/54/1/"chicago" | /Table/54/1/"new york" | 2020-01-10 23:30:00+00:00 + 76 | /Table/54/1/"new york" | /Table/54/1/"seattle" | 2020-01-10 23:30:00+00:00 + 78 | /Table/54/1/"seattle" | /Table/55 | 2020-01-10 23:30:00+00:00 (4 rows) ~~~ + ## See also - [Selection Queries](selection-queries.html) diff --git a/v19.2/unsplit-at.md b/v19.2/unsplit-at.md index f98e19a97d6..3924abc002a 100644 --- a/v19.2/unsplit-at.md +++ b/v19.2/unsplit-at.md @@ -49,7 +49,7 @@ The `crdb_internal.ranges` table contains information about ranges in your Cockr (1 row) ~~~ -Now split the `users` table ranges based on primary key values: +Now [split](split-at.html) the `users` table ranges based on primary key values: {% include copy-clipboard.html %} ~~~ sql @@ -109,11 +109,11 @@ Now unsplit the table to remove the split enforcements: (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. +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](range-merges.html) 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: +Add a new secondary [index](indexes.html) to the `rides` table, on the `revenue` column, and then [split](split-at.html) the table ranges by secondary index values: {% include copy-clipboard.html %} ~~~ sql @@ -178,7 +178,7 @@ Now unsplit the index to remove the split enforcements: (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. +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](range-merges.html) in the table as needed. ## See also