Merge pull request #5242 from cockroachdb/show-partitions

SHOW PARTITIONS statement
cockroachdb · Aug 26, 2019 · 2ad117b · 2ad117b
2 parents eec5f25 + 4c8005f
commit 2ad117b
Show file tree

Hide file tree

Showing 11 changed files with 412 additions and 226 deletions.
diff --git a/_includes/sidebar-data-v19.2.json b/_includes/sidebar-data-v19.2.json
@@ -1141,6 +1141,12 @@
                   "/${VERSION}/show-locality.html"
                 ]
               },
+              {
+                "title": "<code>SHOW PARTITIONS</code> (Enterprise)",
+                "urls": [
+                  "/${VERSION}/show-partitions.html"
+                ]
+              },
               {
                 "title": "<code>SHOW QUERIES</code>",
                 "urls": [

diff --git a/_includes/v19.2/sql/diagrams/show_partitions.html b/_includes/v19.2/sql/diagrams/show_partitions.html
@@ -0,0 +1,30 @@
+<div><svg width="625" height="125">
+<polygon points="9 17 1 13 1 21"></polygon>
+<polygon points="17 17 9 13 9 21"></polygon>
+<rect x="31" y="3" width="64" height="32" rx="10"></rect>
+<rect x="29" y="1" width="64" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="39" y="21">SHOW</text>
+<rect x="115" y="3" width="106" height="32" rx="10"></rect>
+<rect x="113" y="1" width="106" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="123" y="21">PARTITIONS</text>
+<rect x="241" y="3" width="60" height="32" rx="10"></rect>
+<rect x="239" y="1" width="60" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="249" y="21">FROM</text>
+<rect x="341" y="3" width="62" height="32" rx="10"></rect>
+<rect x="339" y="1" width="62" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="349" y="21">TABLE</text><a xlink:href="sql-grammar.html#table_name" xlink:title="table_name">
+<rect x="423" y="3" width="96" height="32"></rect>
+<rect x="421" y="1" width="96" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="431" y="21">table_name</text></a><rect x="341" y="47" width="92" height="32" rx="10"></rect>
+<rect x="339" y="45" width="92" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="349" y="65">DATABASE</text><a xlink:href="sql-grammar.html#database_name" xlink:title="database_name">
+<rect x="453" y="47" width="124" height="32"></rect>
+<rect x="451" y="45" width="124" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="461" y="65">database_name</text></a><rect x="341" y="91" width="64" height="32" rx="10"></rect>
+<rect x="339" y="89" width="64" height="32" class="terminal" rx="10"></rect>
+<text class="terminal" x="349" y="109">INDEX</text><a xlink:href="sql-grammar.html#table_index_name" xlink:title="table_index_name">
+<rect x="425" y="91" width="138" height="32"></rect>
+<rect x="423" y="89" width="138" height="32" class="nonterminal"></rect>
+<text class="nonterminal" x="433" y="109">table_index_name</text></a><path class="line" d="m17 17 h2 m0 0 h10 m64 0 h10 m0 0 h10 m106 0 h10 m0 0 h10 m60 0 h10 m20 0 h10 m62 0 h10 m0 0 h10 m96 0 h10 m0 0 h58 m-276 0 h20 m256 0 h20 m-296 0 q10 0 10 10 m276 0 q0 -10 10 -10 m-286 10 v24 m276 0 v-24 m-276 24 q0 10 10 10 m256 0 q10 0 10 -10 m-266 10 h10 m92 0 h10 m0 0 h10 m124 0 h10 m-266 -10 v20 m276 0 v-20 m-276 20 v24 m276 0 v-24 m-276 24 q0 10 10 10 m256 0 q10 0 10 -10 m-266 10 h10 m64 0 h10 m0 0 h10 m138 0 h10 m0 0 h14 m23 -88 h-3"></path>
+<polygon points="615 17 623 13 623 21"></polygon>
+<polygon points="615 17 607 13 607 21"></polygon></svg></div>
diff --git 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 with the example statements, run [`cockroach demo movr`](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 movr`](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).
 
 {% include copy-clipboard.html %}
 ~~~ shell

diff --git a/_includes/v19.2/sql/movr-statements.md b/_includes/v19.2/sql/movr-statements.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 with the example statements, run [`cockroach demo movr`](cockroach-demo.html) to start a temporary, in-memory cluster with the `movr` dataset pre-loaded:
+To follow along, run [`cockroach demo movr`](cockroach-demo.html) to start a temporary, in-memory cluster with the `movr` dataset pre-loaded:
 
 {% include copy-clipboard.html %}
 ~~~ shell

diff --git a/v19.2/configure-replication-zones.md b/v19.2/configure-replication-zones.md
@@ -131,6 +131,8 @@ See [Cluster Topography](recommended-production-settings.html#topology) recommen
 
 Use the [`SHOW ZONE CONFIGURATIONS`](#view-all-replication-zones) statement to view details about existing replication zones.
 
+You can also use the [`SHOW PARTITIONS`](show-partitions.html) statement to view the zone constraints on existing table partitions.
+
 ## Basic examples
 
 These examples focus on the basic approach and syntax for working with zone configuration. For examples demonstrating how to use constraints, see [Scenario-based examples](#scenario-based-examples).
@@ -636,5 +638,6 @@ There's no need to make zone configuration changes; by default, the cluster is c
 
 - [`SHOW ZONE CONFIGURATIONS`](show-zone-configurations.html)
 - [`CONFIGURE ZONE`](configure-zone.html)
+- [`SHOW PARTITIONS`](show-partitions.html)
 - [SQL Statements](sql-statements.html)
 - [Table Partitioning](partitioning.html)
diff --git a/v19.2/demo-geo-partitioning.md b/v19.2/demo-geo-partitioning.md
@@ -651,6 +651,39 @@ The most effective way to prevent the high SQL latency resulting from cross-regi
       );
     ~~~
 
+Use [`SHOW PARTITIONS`](show-partitions.html) to check your partitions:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SHOW PARTITIONS FROM DATABASE movr;
+~~~
+
+~~~
+  database_name | table_name | partition_name | parent_partition | column_names |                     index_name                      | partition_value | zone_constraints
++---------------+------------+----------------+------------------+--------------+-----------------------------------------------------+-----------------+------------------+
+  movr          | rides      | chicago        | NULL             | city         | rides@primary                                       | ('chicago')     | NULL
+  movr          | rides      | chicago_idx1   | NULL             | city         | rides@rides_auto_index_fk_city_ref_users            | ('chicago')     | NULL
+  movr          | rides      | chicago_idx2   | NULL             | vehicle_city | rides@rides_auto_index_fk_vehicle_city_ref_vehicles | ('chicago')     | NULL
+  movr          | rides      | new_york       | NULL             | city         | rides@primary                                       | ('new york')    | NULL
+  movr          | rides      | new_york_idx1  | NULL             | city         | rides@rides_auto_index_fk_city_ref_users            | ('new york')    | NULL
+  movr          | rides      | new_york_idx2  | NULL             | vehicle_city | rides@rides_auto_index_fk_vehicle_city_ref_vehicles | ('new york')    | NULL
+  movr          | rides      | seattle        | NULL             | city         | rides@primary                                       | ('seattle')     | NULL
+  movr          | rides      | seattle_idx1   | NULL             | city         | rides@rides_auto_index_fk_city_ref_users            | ('seattle')     | NULL
+  movr          | rides      | seattle_idx2   | NULL             | vehicle_city | rides@rides_auto_index_fk_vehicle_city_ref_vehicles | ('seattle')     | NULL
+  movr          | users      | chicago        | NULL             | city         | users@primary                                       | ('chicago')     | NULL
+  movr          | users      | new_york       | NULL             | city         | users@primary                                       | ('new york')    | NULL
+  movr          | users      | seattle        | NULL             | city         | users@primary                                       | ('seattle')     | NULL
+  movr          | vehicles   | chicago        | NULL             | city         | vehicles@primary                                    | ('chicago')     | NULL
+  movr          | vehicles   | chicago_idx    | NULL             | city         | vehicles@vehicles_auto_index_fk_city_ref_users      | ('chicago')     | NULL
+  movr          | vehicles   | new_york       | NULL             | city         | vehicles@primary                                    | ('new york')    | NULL
+  movr          | vehicles   | new_york_idx   | NULL             | city         | vehicles@vehicles_auto_index_fk_city_ref_users      | ('new york')    | NULL
+  movr          | vehicles   | seattle        | NULL             | city         | vehicles@primary                                    | ('seattle')     | NULL
+  movr          | vehicles   | seattle_idx    | NULL             | city         | vehicles@vehicles_auto_index_fk_city_ref_users      | ('seattle')     | NULL
+(18 rows)
+~~~
+
+Note that in all rows, the `zone constraints` column is `NULL`. This is because no replication zones have been applied to partitions.
+
 ## Step 12. Pin partitions to regions
 
 Now that all tables and secondary indexes have been partitioned by city, for each partition, you can create a replication zone that pins the partition's replicas to nodes in a specific region, using the localities specified when nodes were started.

diff --git a/v19.2/partition-by.md b/v19.2/partition-by.md
@@ -100,3 +100,4 @@ Suppose we have an yet another existing table named `students` with the primary
 - [`ALTER TABLE`](alter-table.html)
 - [Define Table Partitions](partitioning.html)
 - [`SHOW JOBS`](show-jobs.html)
+- [`SHOW PARTITIONS`](show-partitions.html)
diff --git a/v19.2/partitioning.md b/v19.2/partitioning.md
@@ -301,7 +301,7 @@ See [Set the Trial or Enterprise License Key](enterprise-licensing.html#set-the-
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cockroach sql --insecure --host=localhost:26157
+    $ cockroach sql --insecure --host=localhost:26257
     ~~~
 
 2. Create the database and set it as current:
@@ -345,7 +345,7 @@ See [Set the Trial or Enterprise License Key](enterprise-licensing.html#set-the-
         email STRING,
         country STRING,
         expected_graduation_date DATE,   
-        PRIMARY KEY (country, id))
+        PRIMARY KEY (country, id));
     ~~~
 
     {% include copy-clipboard.html %}
@@ -367,64 +367,65 @@ To create replication zone and apply them to corresponding partitions, use the [
 
     {% include copy-clipboard.html %}
     ~~~ sql
-    > ALTER PARTITION north_america OF TABLE roachlearn.students \
+    > ALTER PARTITION north_america OF TABLE students
         CONFIGURE ZONE USING constraints='[+region=us]';
     ~~~
 
 2. Create a replication zone for the `europe` partition and constrain its data to the German datacenter:
 
     {% include copy-clipboard.html %}
     ~~~ sql
-    > ALTER PARTITION europe OF TABLE roachlearn.students \
+    > ALTER PARTITION europe OF TABLE students
         CONFIGURE ZONE USING constraints='[+region=de]';
     ~~~
 
 3. Create a replication zone for the `australia` partition and constrain its data to the Australian datacenter:
 
     {% include copy-clipboard.html %}
     ~~~ sql
-    > ALTER PARTITION australia OF TABLE roachlearn.students \
+    > ALTER PARTITION australia OF TABLE students
         CONFIGURE ZONE USING constraints='[+region=aus]';
     ~~~
 
 4. After creating these replication zones, you can view them using the [`SHOW ZONE CONFIGURATION`](show-zone-configurations.html) statement:
 
     {% include copy-clipboard.html %}
     ~~~ sql
-    > SHOW ZONE CONFIGURATION FOR PARTITION north_america OF TABLE roachlearn.students;
+    > SHOW ZONE CONFIGURATION FOR PARTITION north_america OF TABLE students;
     ~~~
 
     ~~~
-                  zone_name             |                                           config_sql
-    +-----------------------------------+------------------------------------------------------------------------------------------------+
-      roachlearn.students.north_america | ALTER PARTITION north_america OF INDEX roachlearn.public.students@primary CONFIGURE ZONE USING
-                                        |     range_min_bytes = 16777216,
-                                        |     range_max_bytes = 67108864,
-                                        |     gc.ttlseconds = 90000,
-                                        |     num_replicas = 3,
-                                        |     constraints = '[+region=us]',
-                                        |     lease_preferences = '[]'
+              zone_name             |                                  config_sql
++-----------------------------------+------------------------------------------------------------------------------+
+  roachlearn.students.north_america | ALTER PARTITION north_america OF INDEX students@primary CONFIGURE ZONE USING
+                                    |     range_min_bytes = 16777216,
+                                    |     range_max_bytes = 67108864,
+                                    |     gc.ttlseconds = 90000,
+                                    |     num_replicas = 3,
+                                    |     constraints = '[+region=us]',
+                                    |     lease_preferences = '[]'
+(1 row)
     ~~~
 
 
-#### Step 6. Verify table partitions
+#### Step 6. Check replica distribution
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> SELECT * FROM [SHOW EXPERIMENTAL_RANGES FROM TABLE roachlearn.students] WHERE "start_key" IS NOT NULL AND "start_key" NOT LIKE '%Prefix%';
+> SELECT * FROM [SHOW EXPERIMENTAL_RANGES FROM TABLE students] WHERE "start_key" IS NOT NULL AND "start_key" NOT LIKE '%Prefix%';
 ~~~
 
 You should see the following output:
 
 ~~~
   start_key |     end_key     | range_id | replicas | lease_holder
 +-----------+-----------------+----------+----------+--------------+
-  /"AU"     | /"AU"/PrefixEnd |       26 | {7,8,9}  |            8
-  /"CA"     | /"CA"/PrefixEnd |       22 | {1,2,3}  |            1
-  /"CH"     | /"CH"/PrefixEnd |       41 | {4,5,6}  |            5
-  /"DE"     | /"DE"/PrefixEnd |       43 | {4,5,6}  |            5
-  /"NZ"     | /"NZ"/PrefixEnd |       45 | {7,8,9}  |            7
-  /"US"     | /"US"/PrefixEnd |       24 | {1,2,3}  |            1
+  /"AU"     | /"AU"/PrefixEnd |       35 | {7,8,9}  |            8
+  /"CA"     | /"CA"/PrefixEnd |       31 | {1,2,3}  |            1
+  /"CH"     | /"CH"/PrefixEnd |       51 | {4,5,6}  |            5
+  /"DE"     | /"DE"/PrefixEnd |       53 | {4,5,6}  |            5
+  /"NZ"     | /"NZ"/PrefixEnd |       55 | {7,8,9}  |            8
+  /"US"     | /"US"/PrefixEnd |       33 | {1,2,3}  |            1
 (6 rows)
 ~~~
 
@@ -438,6 +439,27 @@ Node IDs | Zone
 
 We can see that, after partitioning, the replicas for `US` and `CA`-based students are located on nodes 1-3 in `north_america`, the replicas for `DE` and `CH`-based students are located on nodes 4-6 in `europe`, and the replicas for `AU` and `NZ`-based students are located on nodes 7-9 in `australia`.
 
+### Show partitions and zone constraints
+
+To retrieve table partitions, you can use the [`SHOW PARTITIONS`](show-partitions.html) statement:
+
+{% include copy-clipboard.html %}
+~~~ sql
+> SHOW PARTITIONS FROM TABLE students;
+~~~
+
+~~~
+  database_name | table_name | partition_name | parent_partition | column_names |    index_name    | partition_value | zone_constraints
++---------------+------------+----------------+------------------+--------------+------------------+-----------------+------------------+
+  roachlearn    | students   | north_america  | NULL             | country      | students@primary | ('CA'), ('US')  | [+region=us]
+  roachlearn    | students   | europe         | NULL             | country      | students@primary | ('DE'), ('CH')  | [+region=de]
+  roachlearn    | students   | australia      | NULL             | country      | students@primary | ('AU'), ('NZ')  | [+region=aus]
+  roachlearn    | students   | default        | NULL             | country      | students@primary | (DEFAULT)       | NULL
+(4 rows)
+~~~
+
+You can also view partitions by [database](show-partitions.html#show-partitions-by-database) and [index](show-partitions.html#show-partitions-by-index).
+
 ### Define table partitions by range
 
 Suppose we want to store the data of current students on fast and expensive storage devices (e.g., SSD) and store the data of the graduated students on slower, cheaper storage devices (e.g., HDD).
@@ -463,7 +485,7 @@ $ cockroach start --insecure \
 
 {% include copy-clipboard.html %}
 ~~~ shell
-# Start the first node:
+# Start the second node:
 $ cockroach start --insecure \
 --store=path=/mnt/2,attrs=hdd \
 --advertise-addr=<node2 hostname> \
@@ -500,17 +522,17 @@ To create zone configurations and apply them to corresponding partitions, use th
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> ALTER PARTITION current OF TABLE roachlearn.students_by_range \
+> ALTER PARTITION current OF TABLE students_by_range
     CONFIGURE ZONE USING constraints='[+ssd]';
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> ALTER PARTITION graduated OF TABLE roachlearn.students_by_range \
+> ALTER PARTITION graduated OF TABLE students_by_range
     CONFIGURE ZONE USING constraints='[+hdd]';
 ~~~
 
-#### Step 6. Verify table partitions
+#### Step 6. Check replica distribution
 
 {% include copy-clipboard.html %}
 ~~~ sql
@@ -520,15 +542,11 @@ To create zone configurations and apply them to corresponding partitions, use th
 You should see the following output:
 
 ~~~
-+-----------+---------+----------+----------+--------------+
-| start_key | end_key | range_id | replicas | lease_holder |
-+-----------+---------+----------+----------+--------------+
-| NULL      | /17393  |      244 | {1,2,3}  |            1 |
-| /17393    | NULL    |      242 | {1,2,3}  |            1 |
-+-----------+---------+----------+----------+--------------+
+  start_key | end_key | range_id | replicas | lease_holder | locality
++-----------+---------+----------+----------+--------------+-----------+
+  NULL      | /17393  |       52 | {2,5,8}  |            5 | region=de
+  /17393    | NULL    |       53 | {6,7,10} |            6 | region=de
 (2 rows)
-
-Time: 5.850903ms
 ~~~
 
 ### Define subpartitions on a Table
@@ -611,26 +629,26 @@ To create zone configurations and apply them to corresponding partitions, use th
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> ALTER PARTITION current_us OF TABLE roachlearn.students \
+> ALTER PARTITION current_us OF TABLE students
     CONFIGURE ZONE USING constraints='[+ssd,+datacenter=us1]';
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> ALTER PARTITION graduated_us OF TABLE roachlearn.students CONFIGURE ZONE \
+> ALTER PARTITION graduated_us OF TABLE students CONFIGURE ZONE
     USING constraints='[+hdd,+datacenter=us1]';
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> ALTER PARTITION current_au OF TABLE roachlearn.students \
-    CONFIGURE ZONE USING constraints='[+ssd,+datacenter=au1]';
+> ALTER PARTITION current_au OF TABLE students
+    CONFIGURE ZONE USING constraints='[+ssd,+datacenter=aus1]';
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ sql
-> ALTER PARTITION graduated_au OF TABLE roachlearn.students CONFIGURE ZONE \
-    USING constraints='[+hdd,+datacenter=au1]';
+> ALTER PARTITION graduated_au OF TABLE students CONFIGURE ZONE
+    USING constraints='[+hdd,+datacenter=aus1]';
 ~~~
 
 #### Step 6. Verify table partitions