From 18c62901a33243c49ba88f07e6b538bb92e0cc6b Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Mon, 27 Jun 2016 11:12:16 -0400 Subject: [PATCH 1/6] adding family_def to grammar diagrams --- _includes/sql/diagrams/col_qual_list.html | 94 +- _includes/sql/diagrams/create_table.html | 15 +- _includes/sql/diagrams/family_def.html | 30 + _includes/sql/diagrams/grammar.html | 1216 ++++++++++++++------- create-table.md | 3 + generate/main.go | 3 +- 6 files changed, 934 insertions(+), 427 deletions(-) create mode 100644 _includes/sql/diagrams/family_def.html diff --git a/_includes/sql/diagrams/col_qual_list.html b/_includes/sql/diagrams/col_qual_list.html index b586d000288..23fa72c4b55 100644 --- a/_includes/sql/diagrams/col_qual_list.html +++ b/_includes/sql/diagrams/col_qual_list.html @@ -1,53 +1,61 @@ - + - - - CONSTRAINT + + + CONSTRAINT - - - name + + + name - - - NOT - - - NULL - - - UNIQUE - - - PRIMARY - - - KEY - - - CHECK - - - ( + + + NOT + + + NULL + + + UNIQUE + + + PRIMARY + + + KEY + + + CHECK + + + ( - - - a_expr + + + a_expr - - - ) - - - DEFAULT + + + ) + + + DEFAULT - - - b_expr + + + b_expr - - - + + + FAMILY + + + + name + + + + \ No newline at end of file diff --git a/_includes/sql/diagrams/create_table.html b/_includes/sql/diagrams/create_table.html index eac0520abc7..c19732d215f 100644 --- a/_includes/sql/diagrams/create_table.html +++ b/_includes/sql/diagrams/create_table.html @@ -1,4 +1,4 @@ - + @@ -35,10 +35,15 @@ index_def + + + + family_def + - - - table_constraint + + + table_constraint @@ -46,7 +51,7 @@ ) - + \ No newline at end of file diff --git a/_includes/sql/diagrams/family_def.html b/_includes/sql/diagrams/family_def.html new file mode 100644 index 00000000000..bbe8e705a8a --- /dev/null +++ b/_includes/sql/diagrams/family_def.html @@ -0,0 +1,30 @@ + + + + + + + FAMILY + + + + name + + + + ( + + + + family_elem + + + + , + + + ) + + + + \ No newline at end of file diff --git a/_includes/sql/diagrams/grammar.html b/_includes/sql/diagrams/grammar.html index 6ae82d1c680..46c28925768 100644 --- a/_includes/sql/diagrams/grammar.html +++ b/_includes/sql/diagrams/grammar.html @@ -37,7 +37,7 @@
  • stmt_block


    • stmt:

    - + @@ -66,67 +66,82 @@ explain_stmt + + + + prepare_stmt + + + + + execute_stmt + + + + + deallocate_stmt + - - - grant_stmt + + + grant_stmt - - - insert_stmt + + + insert_stmt - - - rename_stmt + + + rename_stmt - - - revoke_stmt + + + revoke_stmt - - - savepoint_stmt + + + savepoint_stmt - - - select_stmt + + + select_stmt - - - set_stmt + + + set_stmt - - - show_stmt + + + show_stmt - - - transaction_stmt + + + transaction_stmt - - - release_stmt + + + release_stmt - - - truncate_stmt + + + truncate_stmt - - - update_stmt + + + update_stmt - + @@ -232,6 +247,7 @@

    referenced by:


    drop_stmt:

    @@ -326,6 +342,93 @@ +

    referenced by: +

    +


    prepare_stmt:

    + + + + + + + PREPARE + + + + name + + + + + prep_type_clause + + + + AS + + + + preparable_stmt + + + + + +

    referenced by: +

    +


    execute_stmt:

    + + + + + + + EXECUTE + + + + name + + + + + execute_param_clause + + + + + +

    referenced by: +

    +


    deallocate_stmt:

    + + + + + + + DEALLOCATE + + + PREPARE + + + + name + + + + ALL + + + +

    referenced by:


    unreserved_keyword:

    - + @@ -2616,256 +2809,265 @@ DAY - - - DELETE - - - DOUBLE - - - DROP - - - ENCODING - - - EXPLAIN - - - FILTER - - - FIRST - - - FOLLOWING - - - FORCE_INDEX - - - GRANTS - - - HIGH - - - HOUR - - - INDEXES - - - INSERT - - - ISOLATION - - - KEY - - - KEYS - - - LEVEL - - - LOCAL - - - LOW - - - MATCH - - - MINUTE - - - MONTH - - - NAME - - - NAMES - - - NEXT - - - NO - - - NORMAL - - - NOTHING - - - NO_INDEX_JOIN - - - NULLS - - - OF - - - OFF - - - ORDINALITY - - - OVER - - - PARTIAL - - - PARTITION - - - PRECEDING - - - PRIORITY - - - RANGE - - - READ - - - RECURSIVE - - - REF - - - RELEASE - - - RENAME - - - REPEATABLE - - - RESTRICT + + + DEALLOCATE + + + DELETE + + + DOUBLE + + + DROP + + + ENCODING + + + EXECUTE + + + EXPLAIN + + + FILTER + + + FIRST + + + FOLLOWING + + + FORCE_INDEX + + + GRANTS + + + HIGH + + + HOUR + + + INDEXES + + + INSERT + + + ISOLATION + + + KEY + + + KEYS + + + LEVEL + + + LOCAL + + + LOW + + + MATCH + + + MINUTE + + + MONTH + + + NAME + + + NAMES + + + NEXT + + + NO + + + NORMAL + + + NOTHING + + + NO_INDEX_JOIN + + + NULLS + + + OF + + + OFF + + + ORDINALITY + + + OVER + + + PARTIAL + + + PARTITION + + + PRECEDING + + + PREPARE + + + PRIORITY + + + RANGE + + + READ + + + RECURSIVE + + + REF + + + RELEASE - REVOKE - - - ROLLBACK - - - ROLLUP - - - ROWS - - - SAVEPOINT + RENAME + + + REPEATABLE + + + RESTRICT + + + REVOKE + + + ROLLBACK - SEARCH - - - SECOND - - - SERIALIZABLE - - - SESSION - - - SET - - - SHOW - - - SIMPLE - - - SNAPSHOT - - - SQL - - - START - - - STORING - - - STRICT - - - SYSTEM - - - TABLES - - - TEXT - - - TRANSACTION - - - TRUNCATE - - - TYPE - - - UNBOUNDED - - - UNCOMMITTED - - - UNKNOWN - - - UPDATE - - - UPSERT - - - VALID - - - VALIDATE - - - VALUE - - - VARYING - - - WITHIN - - - WITHOUT - - - YEAR - - - ZONE - + ROLLUP + + + ROWS + + + SAVEPOINT + + + SEARCH + + + SECOND + + + SERIALIZABLE + + + SESSION + + + SET + + + SHOW + + + SIMPLE + + + SNAPSHOT + + + SQL + + + START + + + STORING + + + STRICT + + + SYSTEM + + + TABLES + + + TEXT + + + TRANSACTION + + + TRUNCATE + + + TYPE + + + UNBOUNDED + + + UNCOMMITTED + + + UNKNOWN + + + UPDATE + + + UPSERT + + + VALID + + + VALIDATE + + + VALUE + + + VARYING + + + WITHIN + + + WITHOUT + + + YEAR + + + ZONE + @@ -3050,6 +3252,59 @@

    +


    type_list:

    + + + + + + + + typename + + + + , + + + + +

    referenced by: +

    +


    expr_list:

    + + + + + + + + a_expr + + + + , + + + + +

    referenced by: +


    privilege_list:

    @@ -3113,6 +3368,7 @@

    -


    type_list:

    - - - - - - - - typename - - - - , - - - - -

    referenced by: -


    opt_asymmetric:

    @@ -4509,7 +4743,7 @@
  • set_clause


    • table_ref:

    - + @@ -4543,13 +4777,35 @@ opt_alias_clause - + + + + joined_table + + + + ( + + + + joined_table + + + + ) + + + + alias_clause + +

    referenced by:


    simple_typename:

    @@ -4729,7 +4985,7 @@
  • target_elem


    • table_elem:

    - + @@ -4743,12 +4999,17 @@ index_def + + + + family_def + - - - table_constraint + + + table_constraint - + @@ -4953,35 +5214,6 @@

    -


    expr_list:

    - - - - - - - - a_expr - - - - , - - - - -

    referenced by: -


    type_func_name_keyword:

    @@ -5312,27 +5544,135 @@

    +


    joined_table:

    + + + + + + + ( + + + + joined_table + + + + ) + + + + table_ref + + + + CROSS + + + NATURAL + + + + join_type + + + + JOIN + + + + table_ref + + + + + join_type + + + + JOIN + + + + table_ref + + + + + join_qual + + + + + +

    referenced by: +

    +


    alias_clause:

    + + + + + + + AS + + + + name + + + + ( + + + + name_list + + + + ) + + + + +

    referenced by: +


    col_qualification:

    - + - - - CONSTRAINT + + + CONSTRAINT - - - name + + + name - - - col_qualification_elem + + + col_qualification_elem - - - + + + FAMILY + + + + name + + + +

    referenced by:

    +


    family_elem:

    + + + + + + + + name + + + + + +

    referenced by: +


    type_function_name:

    diff --git a/create-table.md b/create-table.md index 550af5d170d..45ae31ea74d 100644 --- a/create-table.md +++ b/create-table.md @@ -64,6 +64,9 @@ The user must have the `CREATE` [privilege](privileges.html) on the parent datab **index_def ::=** {% include sql/diagrams/index_def.html %} +**family_def ::=** +{% include sql/diagrams/family_def.html %} + **table_constraint ::=** {% include sql/diagrams/table_constraint.html %} diff --git a/generate/main.go b/generate/main.go index 9d16eb571c1..f6f4e799416 100644 --- a/generate/main.go +++ b/generate/main.go @@ -175,13 +175,14 @@ func main() { {name: "commit_transaction", stmt: "transaction_stmt", inline: []string{"opt_transaction"}, match: regexp.MustCompile("'COMMIT'")}, {name: "create_database_stmt", inline: []string{"opt_encoding_clause"}, replace: map[string]string{"'SCONST'": "encoding"}}, {name: "create_index_stmt", inline: []string{"opt_storing", "storing", "opt_unique", "opt_name", "index_params", "index_elem", "opt_asc_desc", "name_list"}}, - {name: "create_table_stmt", inline: []string{"opt_table_elem_list", "table_elem_list", "table_elem"}, replace: map[string]string{"| family_def": ""}}, + {name: "create_table_stmt", inline: []string{"opt_table_elem_list", "table_elem_list", "table_elem"}}, {name: "delete_stmt", inline: []string{"relation_expr_opt_alias", "where_clause", "returning_clause", "target_list", "target_elem"}}, {name: "drop_database", stmt: "drop_stmt", match: regexp.MustCompile("'DROP' 'DATABASE'")}, {name: "drop_index", stmt: "drop_stmt", match: regexp.MustCompile("'DROP' 'INDEX'"), inline: []string{"opt_drop_behavior"}}, {name: "drop_stmt", inline: []string{"any_name_list", "any_name", "qualified_name_list", "qualified_name"}}, {name: "drop_table", stmt: "drop_stmt", match: regexp.MustCompile("'DROP' 'TABLE'")}, {name: "explain_stmt", inline: []string{"explainable_stmt", "explain_option_list"}}, + {name: "family_def", inline: []string{"opt_name", "family_params"}}, {name: "grant_stmt", inline: []string{"privileges", "privilege_list", "privilege", "privilege_target", "grantee_list"}}, {name: "index_def", inline: []string{"opt_storing", "storing", "index_params", "opt_name"}}, {name: "insert_stmt", inline: []string{"insert_target", "insert_rest", "returning_clause"}, match: regexp.MustCompile("'INSERT'")}, From bdba3cb29eaccd555d61434d57d50eaf1e001bb1 Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Mon, 27 Jun 2016 16:10:51 -0400 Subject: [PATCH 2/6] docs for column families --- column-families.md | 82 +++++++++++++++++++++++++++++++++++ create-table.md | 10 +++-- data-definition.md | 3 +- frequently-asked-questions.md | 2 +- 4 files changed, 92 insertions(+), 5 deletions(-) create mode 100644 column-families.md diff --git a/column-families.md b/column-families.md new file mode 100644 index 00000000000..6fedf0689ff --- /dev/null +++ b/column-families.md @@ -0,0 +1,82 @@ +--- +title: Column Families +summary: +toc: false +--- + +As of the `beta-20160629` release, CockroachDB supports **column families**. A column family is a group of columns in a table that are stored as a single key-value pair in the underlying key-value layer. Storing column values in this way significantly reduces storage overhead. + +{{site.data.alerts.callout_info}}Tables created as of beta-20160629 are not be compatible with earlier versions of CockroachDB.{{site.data.alerts.end}} + +
    + +## Overview + +When a row is inserted into a table with column families, CockroachDB stores the values for each column family as a single key-value pair. For example, consider a table with 2 columns, where the columns are grouped into a column family: + +~~~ sql +CREATE TABLE t1 ( + a STRING PRIMARY KEY, + b INT, + FAMILY f1 (a, b) +); +~~~ + +Inserting 10 rows into this table would create 10 underlying key-value pairs, 1 per row. In contrast, if the table's columns were not grouped into a family, each column and value would be a distinct key-value pair; thus, inserting 10 rows would create 20 underlying key-value pairs, 2 per row. + +## Using Column Families + +Column families are defined at [table creation](create-table.html). Currently, when you create a table, each column is implicitly its own column family, for example: + +~~~ sql +CREATE TABLE t2 ( + a STRING PRIMARY KEY, + b INT +); + +SHOW CREATE TABLE t2; ++-------+--------------------------------------------+ +| Table | CreateTable | ++-------+--------------------------------------------+ +| t2 | CREATE TABLE t2 (␤ | +| | a STRING NOT NULL,␤ | +| | b INT NULL,␤ | +| | CONSTRAINT "primary" PRIMARY KEY (a),␤ | +| | FAMILY "primary" (a),␤ | +| | FAMILY fam_2_b (b)␤ | +| | ) | ++-------+--------------------------------------------+ +(1 row) +~~~ + +To group columns into multi-column families, you must use the `FAMILY` keyword, for example: + +~~~ sql +CREATE TABLE t3 ( + a STRING PRIMARY KEY, + b INT, + FAMILY f1 (a, b) +); + +SHOW CREATE TABLE t3; ++-------+--------------------------------------------+ +| Table | CreateTable | ++-------+--------------------------------------------+ +| t3 | CREATE TABLE t3 (␤ | +| | a STRING NOT NULL,␤ | +| | b INT NULL,␤ | +| | CONSTRAINT "primary" PRIMARY KEY (a),␤ | +| | FAMILY f1 (a, b)␤ | +| | ) | ++-------+--------------------------------------------+ +(1 row) +~~~ + +## Upcoming Improvements + +In an upcoming release, you won't need to define column families manually. Instead, CockroachDB will group columns into families for you when a table is created. CockroachDB's default groupings will ensure optimal storage and performance, but you will still have the option to define your own groups using the `FAMILY` keyword, as show above. + +## See Also + +- [`CREATE TABLE`](create-table.html) +- [Data Definition](data-definition.html) \ No newline at end of file diff --git a/create-table.md b/create-table.md index 45ae31ea74d..b737f857f13 100644 --- a/create-table.md +++ b/create-table.md @@ -79,7 +79,8 @@ Parameter | Description `any_name` | The name of the table to create, which must be unique within its database and follow these [identifier rules](keywords-and-identifiers.html#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.

    The [`UPSERT`](upsert.html) and [`INSERT ON CONFLICT`](insert.html) statements use a temporary table called `excluded` to handle uniqueness conflicts during execution. It's therefore not recommended to use the name `excluded` for any of your tables. `column_def` | A comma-separated list of column definitions. Each column requires a [name/identifier](keywords-and-identifiers.html#identifiers) and [data type](data-types.html); optionally, a [column-level constraint](constraints.html) can be specified. Column names must be unique within the table but can have the same name as indexes or constraints.

    Any `PRIMARY KEY`, `UNIQUE`, and `CHECK` [constraints](constraints.html) defined at the column level are moved to the table level as part of the table's creation. Use the `SHOW CREATE TABLE` statement to view them at the table level. `index_def` | An optional, comma-separated list of [index definitions](indexes.html). For each index, the column(s) to index must be specified; optionally, a name can be specified. Index names must be unique within the table but can have the same name as columns or constraints. See the [Create a Table with Secondary Indexes](#create-a-table-with-secondary-indexes) example below.

    The [`CREATE INDEX`](create-index.html) statement can be used to create an index separate from table creation. -`table_constraint` | An optional, comma-separated list of [table-level constraints](constraints.html). Constraint names must be unique within the table but can have the same name as columns or indexes. +`family_def` | An optional, comma-separated list of [column family definitions](column-families.html). Column family names must be unique within the table but can have the same name as columns, constraints, or indexes. +`table_constraint` | An optional, comma-separated list of [table-level constraints](constraints.html). Constraint names must be unique within the table but can have the same name as columns, column families, or indexes. ## Examples @@ -89,8 +90,11 @@ In CockroachDB, every table requires a [`PRIMARY KEY`](constraints.html#primary- {{site.data.alerts.callout_info}}Strictly speaking, a primary key's unique index is not created; it is derived from the key(s) under which the data is stored, so it takes no additional space. However, it appears as a normal unique index when using commands like SHOW INDEX.{{site.data.alerts.end}} -~~~ -> CREATE TABLE logon (user_id INT, logon_date DATE); +~~~ sql +> CREATE TABLE logon ( + user_id INT, + logon_date DATE + ); CREATE TABLE > SHOW COLUMNS FROM logon; diff --git a/data-definition.md b/data-definition.md index 8f5bad23cb8..dfb61904b3d 100644 --- a/data-definition.md +++ b/data-definition.md @@ -8,5 +8,6 @@ Click a topic for details. - [Keywords & Identifiers](keywords-and-identifiers.html) - [Constraints](constraints.html) -- [NULL Handling](null-handling.html) +- [Column Families](column-families.html) - [Indexes](indexes.html) +- [NULL Handling](null-handling.html) diff --git a/frequently-asked-questions.md b/frequently-asked-questions.md index ced8d58ee5d..2fb52943fd9 100644 --- a/frequently-asked-questions.md +++ b/frequently-asked-questions.md @@ -145,7 +145,7 @@ Not yet, but this is on our long-term roadmap. ## Can I use CockroachDB as a key-value store? -CockroachDB is a distributed SQL database built on a transactional and strongly-consistent key-value store. At this time, it is not possible to access the key-value store directly. As an alternative, you can [create a SQL table](create-table.html) with two columns, `k` and `v`, and set `k` as the primary key. +CockroachDB is a distributed SQL database built on a transactional and strongly-consistent key-value store. At this time, it is not possible to access the key-value store directly. As an alternative, you can [create a SQL table](create-table.html) with two columns, `k` and `v`, and set `k` as the primary key. Note that if you group these columns into a single [column family](column-families.html), each row will be stored as a single key-value pair in the underlying key-value store. ## Have questions that weren’t answered? From 2aec0b34cabb003fc044cb6e58c2f9d4234421fa Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Mon, 27 Jun 2016 16:45:11 -0400 Subject: [PATCH 3/6] revision for dan --- column-families.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/column-families.md b/column-families.md index 6fedf0689ff..6022d6bf29f 100644 --- a/column-families.md +++ b/column-families.md @@ -4,15 +4,15 @@ summary: toc: false --- -As of the `beta-20160629` release, CockroachDB supports **column families**. A column family is a group of columns in a table that are stored as a single key-value pair in the underlying key-value layer. Storing column values in this way significantly reduces storage overhead. +As of the `beta-20160630` release, CockroachDB supports **column families**. A column family is a group of columns in a table that are stored as a single key-value pair in the underlying key-value layer. Storing column values in this way significantly reduces storage overhead. -{{site.data.alerts.callout_info}}Tables created as of beta-20160629 are not be compatible with earlier versions of CockroachDB.{{site.data.alerts.end}} +{{site.data.alerts.callout_info}}New tables created with multi-column families will not be compatible with versions of CockroachDB earlier than beta-20160630.{{site.data.alerts.end}}
    ## Overview -When a row is inserted into a table with column families, CockroachDB stores the values for each column family as a single key-value pair. For example, consider a table with 2 columns, where the columns are grouped into a column family: +When a row is inserted into a table with column families, CockroachDB stores a single key-value pair per family. For example, consider a table with 2 columns, where the columns are grouped into a column family: ~~~ sql CREATE TABLE t1 ( @@ -22,7 +22,7 @@ CREATE TABLE t1 ( ); ~~~ -Inserting 10 rows into this table would create 10 underlying key-value pairs, 1 per row. In contrast, if the table's columns were not grouped into a family, each column and value would be a distinct key-value pair; thus, inserting 10 rows would create 20 underlying key-value pairs, 2 per row. +Inserting 10 rows into this table would create 10 underlying key-value pairs, 1 per row. This is a significant improvement over earlier versions of CockroachDB, where inserting 10 rows would have created 30 underlying key-value pairs, 3 per row: one key-value pair per column plus an extra key-value pair per row. ## Using Column Families @@ -74,7 +74,7 @@ SHOW CREATE TABLE t3; ## Upcoming Improvements -In an upcoming release, you won't need to define column families manually. Instead, CockroachDB will group columns into families for you when a table is created. CockroachDB's default groupings will ensure optimal storage and performance, but you will still have the option to define your own groups using the `FAMILY` keyword, as show above. +In an upcoming release, you won't need to define column families manually. Instead, CockroachDB will group columns into families for you when a table is created. CockroachDB's default groupings will ensure reasonable storage and performance, but you will still have the option to define your own groups using the `FAMILY` keyword, as show above. ## See Also From 7897c692b835e103604554a06eb534d407568179 Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Mon, 27 Jun 2016 17:57:49 -0400 Subject: [PATCH 4/6] revising benefints and adding recommendations --- column-families.md | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/column-families.md b/column-families.md index 6022d6bf29f..ac003c8e32a 100644 --- a/column-families.md +++ b/column-families.md @@ -4,7 +4,7 @@ summary: toc: false --- -As of the `beta-20160630` release, CockroachDB supports **column families**. A column family is a group of columns in a table that are stored as a single key-value pair in the underlying key-value layer. Storing column values in this way significantly reduces storage overhead. +As of the `beta-20160630` release, CockroachDB supports **column families**. A column family is a group of columns in a table that are stored as a single key-value pair in the underlying key-value layer. The reduced number of keys results in a smaller storage overhead and, even more signifcantly, in improved performance during `INSERT`, `UPDATE`, and `DELETE` operations. {{site.data.alerts.callout_info}}New tables created with multi-column families will not be compatible with versions of CockroachDB earlier than beta-20160630.{{site.data.alerts.end}} @@ -31,7 +31,9 @@ Column families are defined at [table creation](create-table.html). Currently, w ~~~ sql CREATE TABLE t2 ( a STRING PRIMARY KEY, - b INT + b INT, + c BOOL, + d TIMESTAMP ); SHOW CREATE TABLE t2; @@ -41,9 +43,13 @@ SHOW CREATE TABLE t2; | t2 | CREATE TABLE t2 (␤ | | | a STRING NOT NULL,␤ | | | b INT NULL,␤ | +| | c BOOL NULL,␤ | +| | d TIMESTAMP NULL,␤ | | | CONSTRAINT "primary" PRIMARY KEY (a),␤ | | | FAMILY "primary" (a),␤ | -| | FAMILY fam_2_b (b)␤ | +| | FAMILY fam_2_b (b),␤ | +| | FAMILY fam_3_c (c),␤ | +| | FAMILY fam_4_d (d)␤ | | | ) | +-------+--------------------------------------------+ (1 row) @@ -54,24 +60,37 @@ To group columns into multi-column families, you must use the `FAMILY` keyword, ~~~ sql CREATE TABLE t3 ( a STRING PRIMARY KEY, - b INT, - FAMILY f1 (a, b) + b INT, + c BOOL, + d TIMESTAMP, + FAMILY f1 (a, b), + FAMILY f2 (c, d) ); SHOW CREATE TABLE t3; +-------+--------------------------------------------+ | Table | CreateTable | +-------+--------------------------------------------+ -| t3 | CREATE TABLE t3 (␤ | +| t30 | CREATE TABLE t30 (␤ | | | a STRING NOT NULL,␤ | | | b INT NULL,␤ | +| | c BOOL NULL,␤ | +| | d TIMESTAMP NULL,␤ | | | CONSTRAINT "primary" PRIMARY KEY (a),␤ | -| | FAMILY f1 (a, b)␤ | +| | FAMILY f1 (a, b),␤ | +| | FAMILY f2 (c, d)␤ | | | ) | +-------+--------------------------------------------+ (1 row) ~~~ +## Column Family Recommendations + +When defining column families for a table, keep the following in mind: + +- Since column families reduce the number of underlying keys, it's best for performance to use as few families as is reasonable. +- Try to avoid grouping columns that get updated a lot with columns that don't. If a small column that gets updated frequently is grouped with a big column that gets updated seldomly, the big column will be rewritten every time the small one is updated. + ## Upcoming Improvements In an upcoming release, you won't need to define column families manually. Instead, CockroachDB will group columns into families for you when a table is created. CockroachDB's default groupings will ensure reasonable storage and performance, but you will still have the option to define your own groups using the `FAMILY` keyword, as show above. @@ -79,4 +98,4 @@ In an upcoming release, you won't need to define column families manually. Inste ## See Also - [`CREATE TABLE`](create-table.html) -- [Data Definition](data-definition.html) \ No newline at end of file +- [Data Definition](data-definition.html) From 5c40c733d2e21c56aca8434be3a0be91406caeb2 Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Tue, 28 Jun 2016 12:12:11 -0400 Subject: [PATCH 5/6] more revisions for dan --- column-families.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/column-families.md b/column-families.md index ac003c8e32a..9e3c2cf0eea 100644 --- a/column-families.md +++ b/column-families.md @@ -71,7 +71,7 @@ SHOW CREATE TABLE t3; +-------+--------------------------------------------+ | Table | CreateTable | +-------+--------------------------------------------+ -| t30 | CREATE TABLE t30 (␤ | +| t3 | CREATE TABLE t3 (␤ | | | a STRING NOT NULL,␤ | | | b INT NULL,␤ | | | c BOOL NULL,␤ | @@ -84,12 +84,26 @@ SHOW CREATE TABLE t3; (1 row) ~~~ -## Column Family Recommendations +## Restrictions and Recommendations When defining column families for a table, keep the following in mind: +- By default, columns that are part of the primary index are assigned to the first column family. If you manually assign primary index columns to a family, it must be the first family listed in the `CREATE TABLE` statement. + - Since column families reduce the number of underlying keys, it's best for performance to use as few families as is reasonable. -- Try to avoid grouping columns that get updated a lot with columns that don't. If a small column that gets updated frequently is grouped with a big column that gets updated seldomly, the big column will be rewritten every time the small one is updated. + +- Avoid grouping columns that get updated a lot with columns that don't. If a small column that gets updated frequently is grouped with a big column that gets updated seldomly, the big column will be rewritten every time the small one is updated. + +- By default, `STRING` columns with no length limit and `DECIMAL` columns with no precision are assigned to their own families. When you know that such columns will be small, it's best to assign them to families with other columns. For example, for a table such as the following, where you know that user names and addresses will be relatively small, you could assign all of the columns to one family: + + ~~~ sql + CREATE TABLE users ( + id SERIAL PRIMARY KEY, + name STRING, + address STRING, + FAMILY f1 (id, name, address) + ); + ~~~ ## Upcoming Improvements From 6545def8fd90b97db710c935cc7322955af9fa4c Mon Sep 17 00:00:00 2001 From: Jesse Seldess Date: Tue, 28 Jun 2016 14:17:47 -0400 Subject: [PATCH 6/6] showing column families in create table example and clearing up various examples --- create-database.md | 14 ++++++------ create-table.md | 47 +++++++++++++++++++++++++++------------- delete.md | 34 ++++++++++++----------------- drop-database.md | 12 +++++------ drop-table.md | 8 +++---- grant.md | 20 ++++++++--------- insert.md | 54 +++++++++++++++++++++++----------------------- rename-database.md | 12 +++++------ rename-table.md | 18 ++++++++-------- show-databases.md | 11 ++++------ show-index.md | 39 +++++++++++++++++---------------- upsert.md | 22 +++++++++---------- 12 files changed, 150 insertions(+), 141 deletions(-) diff --git a/create-database.md b/create-database.md index 16fbf4537f3..222e999c735 100644 --- a/create-database.md +++ b/create-database.md @@ -29,10 +29,10 @@ Parameter | Description ### Create a Database ~~~ -CREATE DATABASE bank; +> CREATE DATABASE bank; CREATE DATABASE -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -45,7 +45,7 @@ SHOW DATABASES; ### Create Fails (Name Already In Use) ~~~ -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -53,10 +53,10 @@ SHOW DATABASES; | system | +----------+ -CREATE DATABASE bank; +> CREATE DATABASE bank; pq: database "bank" already exists -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -64,10 +64,10 @@ SHOW DATABASES; | system | +----------+ -CREATE DATABASE IF NOT EXISTS bank; +> CREATE DATABASE IF NOT EXISTS bank; CREATE DATABASE -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ diff --git a/create-table.md b/create-table.md index b737f857f13..6800a622906 100644 --- a/create-table.md +++ b/create-table.md @@ -79,7 +79,7 @@ Parameter | Description `any_name` | The name of the table to create, which must be unique within its database and follow these [identifier rules](keywords-and-identifiers.html#identifiers). When the parent database is not set as the default, the name must be formatted as `database.name`.

    The [`UPSERT`](upsert.html) and [`INSERT ON CONFLICT`](insert.html) statements use a temporary table called `excluded` to handle uniqueness conflicts during execution. It's therefore not recommended to use the name `excluded` for any of your tables. `column_def` | A comma-separated list of column definitions. Each column requires a [name/identifier](keywords-and-identifiers.html#identifiers) and [data type](data-types.html); optionally, a [column-level constraint](constraints.html) can be specified. Column names must be unique within the table but can have the same name as indexes or constraints.

    Any `PRIMARY KEY`, `UNIQUE`, and `CHECK` [constraints](constraints.html) defined at the column level are moved to the table level as part of the table's creation. Use the `SHOW CREATE TABLE` statement to view them at the table level. `index_def` | An optional, comma-separated list of [index definitions](indexes.html). For each index, the column(s) to index must be specified; optionally, a name can be specified. Index names must be unique within the table but can have the same name as columns or constraints. See the [Create a Table with Secondary Indexes](#create-a-table-with-secondary-indexes) example below.

    The [`CREATE INDEX`](create-index.html) statement can be used to create an index separate from table creation. -`family_def` | An optional, comma-separated list of [column family definitions](column-families.html). Column family names must be unique within the table but can have the same name as columns, constraints, or indexes. +`family_def` | An optional, comma-separated list of [column family definitions](column-families.html). A column family is a group of columns that are stored as a single key-value pair in the underlying key-value layer. The reduced number of keys results in a smaller storage overhead and, even more signifcantly, in improved performance during data manipulation. Column family names must be unique within the table but can have the same name as columns, constraints, or indexes. `table_constraint` | An optional, comma-separated list of [table-level constraints](constraints.html). Constraint names must be unique within the table but can have the same name as columns, column families, or indexes. ## Examples @@ -90,11 +90,8 @@ In CockroachDB, every table requires a [`PRIMARY KEY`](constraints.html#primary- {{site.data.alerts.callout_info}}Strictly speaking, a primary key's unique index is not created; it is derived from the key(s) under which the data is stored, so it takes no additional space. However, it appears as a normal unique index when using commands like SHOW INDEX.{{site.data.alerts.end}} -~~~ sql -> CREATE TABLE logon ( - user_id INT, - logon_date DATE - ); +~~~ +> CREATE TABLE logon (user_id INT, logon_date DATE); CREATE TABLE > SHOW COLUMNS FROM logon; @@ -105,6 +102,7 @@ CREATE TABLE | logon_date | DATE | true | NULL | | rowid | INT | false | unique_rowid() | +------------+------+-------+----------------+ +(3 rows) > SHOW INDEX FROM logon; +-------+---------+--------+-----+--------+-----------+---------+ @@ -112,14 +110,22 @@ CREATE TABLE +-------+---------+--------+-----+--------+-----------+---------+ | logon | primary | true | 1 | rowid | ASC | false | +-------+---------+--------+-----+--------+-----------+---------+ +(1 row) ~~~ ### Create a Table (Primary Key Defined) In this example, we create a table with three columns. One column is the [`PRIMARY KEY`](constraints.html#primary-key), another is given the [`UNIQUE`](constraints.html#unique) constraint, and the third has no constraints. The primary key and column with the `UNIQUE` constraint are automatically indexed. +Also, since all three columns are likely to be small, we group them into a single [column family](column-families.html). As a result, each row inserted will be stored as a single key-value pair in the underlying key-value layer, thus reducing the storage overhead and improving performance during data manipulation. + ~~~ -> CREATE TABLE logoff (user_id INT PRIMARY KEY, user_email STRING UNIQUE, logoff_date DATE); +> CREATE TABLE logoff ( + user_id INT PRIMARY KEY, + user_email STRING UNIQUE, + logoff_date DATE, + FAMILY f1 (user_id, user_email, logoff_date) +); CREATE TABLE > SHOW COLUMNS FROM logoff; @@ -130,6 +136,7 @@ CREATE TABLE | user_email | STRING | true | NULL | | logoff_date | DATE | true | NULL | +-------------+--------+-------+---------+ +(3 rows) > SHOW INDEX FROM logoff; +--------+-----------------------+--------+-----+------------+-----------+---------+ @@ -138,6 +145,7 @@ CREATE TABLE | logoff | primary | true | 1 | user_id | ASC | false | | logoff | logoff_user_email_key | true | 1 | user_email | ASC | false | +--------+-----------------------+--------+-----+------------+-----------+---------+ +(2 rows) ~~~ ### Create a Table With Secondary Indexes @@ -176,15 +184,16 @@ CREATE TABLE | product_information | supp_id_prod_status_idx | false | 1 | supplier_id | ASC | false | | product_information | supp_id_prod_status_idx | false | 2 | product_status | ASC | false | +---------------------+--------------------------------------+--------+-----+----------------+-----------+---------+ +(6 rows) ~~~ An alternate way to create secondary indexes would be to use [`CREATE INDEX`](create-index.html) statements once the table has been created: ~~~ -CREATE INDEX date_added_idx ON product_information (date_added); +> CREATE INDEX date_added_idx ON product_information (date_added); CREATE INDEX -CREATE INDEX supp_id_prod_status_idx ON product_information (supplier_id, product_status); +> CREATE INDEX supp_id_prod_status_idx ON product_information (supplier_id, product_status); CREATE INDEX ~~~ @@ -193,12 +202,20 @@ CREATE INDEX To show the definition of a table, use the `SHOW CREATE TABLE` statement. The contents of the `CreateTable` column in the response is a string with embedded line breaks that, when echoed, produces formatted output. ~~~ -> SHOW CREATE TABLE logon; -+-------+------------------------------------------------------------------------+ -| Table | CreateTable | -+-------+------------------------------------------------------------------------+ -| logon | "CREATE TABLE logon (\n\tuser_id INT NULL,\n\tlogon_date DATE NULL\n)" | -+-------+------------------------------------------------------------------------+ +> SHOW CREATE TABLE logoff; ++--------+-------------------------------------------------------+ +| Table | CreateTable | ++--------+-------------------------------------------------------+ +| logoff | CREATE TABLE logoff (␤ | +| | user_id INT NOT NULL,␤ | +| | user_email STRING NULL,␤ | +| | logoff_date DATE NULL,␤ | +| | CONSTRAINT "primary" PRIMARY KEY (user_id),␤ | +| | UNIQUE INDEX logoff_user_email_key (user_email),␤ | +| | FAMILY f1 (user_id, user_email, logoff_date)␤ | +| | ) | ++--------+-------------------------------------------------------+ +(1 row) ~~~ ## See Also diff --git a/delete.md b/delete.md index fa230a49141..807eb36675e 100644 --- a/delete.md +++ b/delete.md @@ -49,15 +49,15 @@ Successful `DELETE` statements return one of the following: You can delete all rows from a table by not including a `WHERE` clause in your `DELETE` statement. -~~~ sql -DELETE FROM account_details; +~~~ +> DELETE FROM account_details; DELETE 7 ~~~ This is roughly equivalent to [`TRUNCATE`](truncate.html). -~~~ sql -TRUNCATE account_details; +~~~ +> TRUNCATE account_details; TRUNCATE ~~~ @@ -73,9 +73,8 @@ Using your table's `PRIMARY KEY` or `UNIQUE` columns to delete rows ensures your In this example, `account_id` is our `PRIMARY KEY` and we want to delete the row where it equals 1. Because we're positive no other rows have that value in the `account_id` column, there's no risk of accidentally removing another row. -~~~ sql -DELETE FROM account_details WHERE account_id = 1 RETURNING *; - +~~~ +> DELETE FROM account_details WHERE account_id = 1 RETURNING *; +------------+---------+--------------+ | account_id | balance | account_type | +------------+---------+--------------+ @@ -87,9 +86,8 @@ DELETE FROM account_details WHERE account_id = 1 RETURNING *; Deleting rows using non-unique columns removes _every_ row that returns `TRUE` for the `WHERE` clause's `a_expr`. This can easily result in deleting data you didn't intend to. -~~~ sql -DELETE FROM account_details WHERE balance = 30000 RETURNING *; - +~~~ +> DELETE FROM account_details WHERE balance = 30000 RETURNING *; +------------+---------+--------------+ | account_id | balance | account_type | +------------+---------+--------------+ @@ -107,9 +105,8 @@ To see which rows your statement deleted, include the `RETURNING` clause to retr #### Use All Columns By specifying `*`, you retrieve all columns of the delete rows. -~~~ sql -DELETE FROM account_details WHERE balance < 23000 RETURNING *; - +~~~ +> DELETE FROM account_details WHERE balance < 23000 RETURNING *; +------------+---------+--------------+ | account_id | balance | account_type | +------------+---------+--------------+ @@ -121,9 +118,8 @@ DELETE FROM account_details WHERE balance < 23000 RETURNING *; To retrieve specific columns, name them in the `RETURNING` clause. -~~~ sql -DELETE FROM account_details WHERE account_id = 5 RETURNING account_id, account_type; - +~~~ +> DELETE FROM account_details WHERE account_id = 5 RETURNING account_id, account_type; +------------+--------------+ | account_id | account_type | +------------+--------------+ @@ -135,9 +131,8 @@ DELETE FROM account_details WHERE account_id = 5 RETURNING account_id, account_t When `RETURNING` specific columns, you can change their labels using `AS`. -~~~ sql -DELETE FROM account_details WHERE balance < 22500 RETURNING account_id, balance AS final_balance; - +~~~ +> DELETE FROM account_details WHERE balance < 22500 RETURNING account_id, balance AS final_balance; +------------+---------------+ | account_id | final_balance | +------------+---------------+ @@ -145,7 +140,6 @@ DELETE FROM account_details WHERE balance < 22500 RETURNING account_id, balance +------------+---------------+ ~~~ - ## See Also - [`INSERT`](insert.html) diff --git a/drop-database.md b/drop-database.md index 6344992e00f..81b23945699 100644 --- a/drop-database.md +++ b/drop-database.md @@ -33,7 +33,7 @@ DROP DATABASE IF EXISTS db1; ## Example ~~~ -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -41,16 +41,16 @@ SHOW DATABASES; | system | +----------+ -DROP DATABASE db1; +> DROP DATABASE db1; DROP DATABASE -DROP DATABASE db2; +> DROP DATABASE db2; pq: database "db2" does not exist -DROP DATABASE IF EXISTS db2; +> DROP DATABASE IF EXISTS db2; DROP DATABASE -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -64,4 +64,4 @@ SHOW DATABASES; - [`SHOW DATABASES`](show-databases.html) - [`RENAME DATABASE`](rename-database.html) - [`SET DATABASE`](set-database.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html) diff --git a/drop-table.md b/drop-table.md index fa560c0235e..71377652bb6 100644 --- a/drop-table.md +++ b/drop-table.md @@ -33,7 +33,7 @@ DROP TABLE IF EXISTS db1.table1, db1.table2; ## Example ~~~ -SHOW TABLES FROM db1; +> SHOW TABLES FROM db1; +--------+ | Table | +--------+ @@ -42,10 +42,10 @@ SHOW TABLES FROM db1; | table3 | +--------+ -DROP TABLE db1.table1, db1.table2; +> DROP TABLE db1.table1, db1.table2; DROP TABLE -SHOW TABLES FROM db1; +> SHOW TABLES FROM db1; +--------+ | Table | +--------+ @@ -62,4 +62,4 @@ SHOW TABLES FROM db1; - [`SHOW COLUMNS`](show-columns.html) - [`SHOW TABLES`](show-tables.html) - [`UPDATE`](update.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html) diff --git a/grant.md b/grant.md index 3bc5a59eff9..729b501c4cd 100644 --- a/grant.md +++ b/grant.md @@ -83,7 +83,7 @@ where `` is a comma-separated list of [privileges](#supported-privil Let's say you have an `animals` database containing two tables: ~~~ -SHOW tables FROM animals; +> SHOW tables FROM animals; +-------------+ | Table | +-------------+ @@ -97,10 +97,10 @@ You want the `maxroach` user to have the `SELECT` privilege on both tables, and First, you grant the `maxroach` user the `SELECT` privilege on the two current tables: ~~~ -GRANT SELECT ON animals.* TO maxroach; +> GRANT SELECT ON animals.* TO maxroach; GRANT -SHOW GRANTS ON animals.* FOR maxroach; +> SHOW GRANTS ON animals.* FOR maxroach; +-----------+----------+------------+ | Table | User | Privileges | +-----------+----------+------------+ @@ -112,10 +112,10 @@ SHOW GRANTS ON animals.* FOR maxroach; Next, you grant the `betsyroach` user the `ALL` privilege on the two current tables: ~~~ -GRANT ALL ON animals.* TO betsyroach; +> GRANT ALL ON animals.* TO betsyroach; GRANT -SHOW GRANTS ON animals.* FOR betsyroach; +> SHOW GRANTS ON animals.* FOR betsyroach; +-----------+------------+------------+ | Table | User | Privileges | +-----------+------------+------------+ @@ -127,10 +127,10 @@ SHOW GRANTS ON animals.* FOR betsyroach; Finally, you grant the `betsyroach` user the `ALL` privilege on the `animals` database to ensure that the user retains the privilege for all new tables created in the database: ~~~ -GRANT ALL ON DATABASE animals TO betsyroach; +> GRANT ALL ON DATABASE animals TO betsyroach; GRANT -SHOW GRANTS ON DATABASE animals FOR betsyroach; +> SHOW GRANTS ON DATABASE animals FOR betsyroach; +----------+------------+------------+ | Database | User | Privileges | +----------+------------+------------+ @@ -141,10 +141,10 @@ SHOW GRANTS ON DATABASE animals FOR betsyroach; Whenever a new table is created in the `animals` database, the `betsyroach` user will inherit the `ALL` privilege on the table: ~~~ -CREATE TABLE animals.cockroaches (name STRING, count INT); +> CREATE TABLE animals.cockroaches (name STRING, count INT); CREATE TABLE -SHOW GRANTS ON animals.cockroaches FOR betsyroach; +> SHOW GRANTS ON animals.cockroaches FOR betsyroach; +-------------+------------+------------+ | Table | User | Privileges | +-------------+------------+------------+ @@ -157,4 +157,4 @@ SHOW GRANTS ON animals.cockroaches FOR betsyroach; - [Privileges](privileges.html) - [`REVOKE`](revoke.html) - [`SHOW GRANTS`](show-grants.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html) diff --git a/insert.md b/insert.md index d401b4aa10b..04a148b23f4 100644 --- a/insert.md +++ b/insert.md @@ -39,10 +39,10 @@ Parameter | Description ### Insert a Single Row ~~~ -INSERT INTO accounts (balance, id) VALUES (10000.50, 1); +> INSERT INTO accounts (balance, id) VALUES (10000.50, 1); INSERT 1 -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+---------+ | id | balance | +----+---------+ @@ -53,7 +53,7 @@ SELECT * FROM accounts; If you don't list column names, the statement will use the columns of the table in their declared order: ~~~ -SHOW COLUMNS FROM accounts; +> SHOW COLUMNS FROM accounts; +---------+---------+-------+----------------+ | Field | Type | Null | Default | +---------+---------+-------+----------------+ @@ -61,10 +61,10 @@ SHOW COLUMNS FROM accounts; | balance | DECIMAL | true | NULL | +---------+---------+-------+----------------+ -INSERT INTO accounts VALUES (2, 20000.75); +> INSERT INTO accounts VALUES (2, 20000.75); INSERT 1 -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -76,10 +76,10 @@ SELECT * FROM accounts; ### Insert Multiple Rows ~~~ -INSERT INTO accounts (id, balance) VALUES (3, 8100.73), (4, 9400.10); +> INSERT INTO accounts (id, balance) VALUES (3, 8100.73), (4, 9400.10); INSERT 2 -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -93,7 +93,7 @@ SELECT * FROM accounts; ### Insert from a `SELECT` Statement ~~~ -SHOW COLUMS FROM other_accounts; +> SHOW COLUMS FROM other_accounts; +--------+---------+-------+---------+ | Field | Type | Null | Default | +--------+---------+-------+---------+ @@ -101,10 +101,10 @@ SHOW COLUMS FROM other_accounts; | amount | DECIMAL | true | NULL | +--------+---------+-------+---------+ -INSERT INTO accounts (id, balance) SELECT number, amount FROM other_accounts WHERE id > 4; +> INSERT INTO accounts (id, balance) SELECT number, amount FROM other_accounts WHERE id > 4; INSERT 3 -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -121,13 +121,13 @@ SELECT * FROM accounts; ### Insert Default Values ~~~ -INSERT INTO accounts (id) VALUES (8); +> INSERT INTO accounts (id) VALUES (8); INSERT 1 -INSERT INTO accounts (id, balance) VALUES (9, DEFAULT); +> INSERT INTO accounts (id, balance) VALUES (9, DEFAULT); INSERT 1 -SELECT * FROM accounts WHERE id in (8, 9); +> SELECT * FROM accounts WHERE id in (8, 9); +----+---------+ | id | balance | +----+---------+ @@ -135,10 +135,10 @@ SELECT * FROM accounts WHERE id in (8, 9); | 9 | NULL | +----+---------+ -INSERT INTO accounts DEFAULT VALUES; +> INSERT INTO accounts DEFAULT VALUES; INSERT 1 -SELECT * FROM accounts; +> SELECT * FROM accounts; +--------------------+----------+ | id | balance | +--------------------+----------+ @@ -158,21 +158,21 @@ SELECT * FROM accounts; ### Insert and Return Values ~~~ -INSERT INTO accounts (id, balance) VALUES (DEFAULT, 5000.99) RETURNING id; +> INSERT INTO accounts (id, balance) VALUES (DEFAULT, 5000.99) RETURNING id; +--------------------+ | id | +--------------------+ | 142935769332121601 | +--------------------+ -INSERT INTO accounts (id, balance) VALUES (DEFAULT, 250000) RETURNING *; +> INSERT INTO accounts (id, balance) VALUES (DEFAULT, 250000) RETURNING *; +--------------------+---------+ | id | balance | +--------------------+---------+ | 142935982200750081 | 250000 | +--------------------+---------+ -INSERT INTO accounts (id, balance) VALUES (DEFAULT, 2000) RETURNING balance * 2; +> INSERT INTO accounts (id, balance) VALUES (DEFAULT, 2000) RETURNING balance * 2; +-------------+ | balance * 2 | +-------------+ @@ -185,13 +185,13 @@ INSERT INTO accounts (id, balance) VALUES (DEFAULT, 2000) RETURNING balance * 2; When a uniqueness conflict is detected, CockroachDB stores the row in a temporary table called excluded. This example demonstrates how you use the columns in the temporary excluded table to apply updates on conflict: ~~~ -INSERT INTO accounts (id, balance) +> INSERT INTO accounts (id, balance) VALUES (8, 500.50) ON CONFLICT (id) DO UPDATE SET balance = excluded.balance; INSERT 1 -SELECT * FROM accounts WHERE id = 8; +> SELECT * FROM accounts WHERE id = 8; +----+---------+ | id | balance | +----+---------+ @@ -204,27 +204,27 @@ SELECT * FROM accounts WHERE id = 8; In this example, we get an error from a uniqueness conflict: ~~~ -SELECT * FROM accounts WHERE id = 8; +> SELECT * FROM accounts WHERE id = 8; +----+---------+ | id | balance | +----+---------+ | 8 | 500.5 | +----+---------+ -INSERT INTO accounts (id, balance) VALUES (8, 125.50); +> INSERT INTO accounts (id, balance) VALUES (8, 125.50); pq: duplicate key value (id)=(8) violates unique constraint "primary" ~~~ In this example, we use `ON CONFLICT DO NOTHING` to ignore the uniqueness error and prevent the affected row from being updated: ~~~ -INSERT INTO accounts (id, balance) +> INSERT INTO accounts (id, balance) VALUES (8, 125.50) ON CONFLICT (id) DO NOTHING; INSERT 1 -SELECT * FROM accounts WHERE id = 8; +> SELECT * FROM accounts WHERE id = 8; +----+---------+ | id | balance | +----+---------+ @@ -235,13 +235,13 @@ SELECT * FROM accounts WHERE id = 8; In this example, `ON CONFLICT DO NOTHING` prevents the first row from updating while allowing the second row to be inserted: ~~~ -INSERT INTO accounts (id, balance) +> INSERT INTO accounts (id, balance) VALUES (8, 125.50), (10, 450) ON CONFLICT (id) DO NOTHING; INSERT 2 -SELECT * FROM accounts WHERE id in (8, 10); +> SELECT * FROM accounts WHERE id in (8, 10); +----+---------+ | id | balance | +----+---------+ @@ -253,4 +253,4 @@ SELECT * FROM accounts WHERE id in (8, 10); ## See Also - [`UPSERT`](upsert.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html) diff --git a/rename-database.md b/rename-database.md index 3b6813fc62d..d2944971932 100644 --- a/rename-database.md +++ b/rename-database.md @@ -27,7 +27,7 @@ Parameter | Description ### Rename a Database ~~~ -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -36,10 +36,10 @@ SHOW DATABASES; | system | +----------+ -ALTER DATABASE db1 RENAME TO db3; +> ALTER DATABASE db1 RENAME TO db3; RENAME DATABASE -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -52,7 +52,7 @@ SHOW DATABASES; ### Rename Fails (New Name Already In Use) ~~~ -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -61,7 +61,7 @@ SHOW DATABASES; | system | +----------+ -ALTER DATABASE db2 RENAME TO db3; +> ALTER DATABASE db2 RENAME TO db3; pq: the new database name "db3" already exists ~~~ @@ -71,4 +71,4 @@ pq: the new database name "db3" already exists - [`SHOW DATABASES`](show-databases.html) - [`SET DATABASE`](set-database.html) - [`DROP DATABASE`](drop-database.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html) diff --git a/rename-table.md b/rename-table.md index 3ed82c715cb..96911bc05f4 100644 --- a/rename-table.md +++ b/rename-table.md @@ -41,7 +41,7 @@ ALTER TABLE db1.table1 RENAME TO db2.table1 ### Rename a table ~~~ -SHOW TABLES FROM db1; +> SHOW TABLES FROM db1; +--------+ | Table | +--------+ @@ -49,10 +49,10 @@ SHOW TABLES FROM db1; | table2 | +--------+ -ALTER TABLE db1.table1 RENAME TO db1.tablea +> ALTER TABLE db1.table1 RENAME TO db1.tablea RENAME TABLE -SHOW TABLES FROM db1; +> SHOW TABLES FROM db1; +--------+ | Table | +--------+ @@ -64,7 +64,7 @@ SHOW TABLES FROM db1; ### Move a table ~~~ -SHOW DATABASES; +> SHOW DATABASES; +----------+ | Database | +----------+ @@ -73,7 +73,7 @@ SHOW DATABASES; | system | +----------+ -SHOW TABLES FROM db1; +> SHOW TABLES FROM db1; +--------+ | Table | +--------+ @@ -81,23 +81,23 @@ SHOW TABLES FROM db1; | tablea | +--------+ -SHOW TABLES FROM db2; +> SHOW TABLES FROM db2; +-------+ | Table | +-------+ +-------+ -ALTER TABLE db1.tablea RENAME TO db2.tablea +> ALTER TABLE db1.tablea RENAME TO db2.tablea RENAME TABLE -SHOW TABLES FROM db1; +> SHOW TABLES FROM db1; +--------+ | Table | +--------+ | table2 | +--------+ -SHOW TABLES FROM db2; +> SHOW TABLES FROM db2; +--------+ | Table | +--------+ diff --git a/show-databases.md b/show-databases.md index d85a6c028fc..62f5b0d2547 100644 --- a/show-databases.md +++ b/show-databases.md @@ -16,22 +16,19 @@ The `SHOW DATABASES` [statement](sql-statements.html) lists all database in the No [privileges](privileges.html) are required to list the databases in the CockroachDB cluster. -## Usage +## Example -To list all databases in the cluster, use the `SHOW DATABASES` statement: - -~~~ sql -SHOW DATABASES; -~~~ ~~~ +> SHOW DATABASES; +----------+ | Database | +----------+ | bank | | system | +----------+ +(2 rows) ~~~ ## See Also -[SQL Statements](sql-statements.html) \ No newline at end of file +[SQL Statements](sql-statements.html) diff --git a/show-index.md b/show-index.md index 576be62d253..6990eede9bc 100644 --- a/show-index.md +++ b/show-index.md @@ -8,9 +8,9 @@ The `SHOW INDEX` [statement](sql-statements.html) returns index information for
    -## Synopsis +## Required Privileges -{% include sql/diagrams/show_index.html %} +No [privileges](privileges.html) are required to show indexes for a table. ## Aliases @@ -19,17 +19,15 @@ In CockroachDB, the following are aliases for `SHOW INDEX`: - `SHOW INDEXES` - `SHOW KEYS` -## Required Privileges - -No [privileges](privileges.html) are required to show indexes for a table. +## Synopsis -## Usage +{% include sql/diagrams/show_index.html %} -To show indexes for a table, use the `SHOW INDEX FROM` statement followed by the table name in `database.table` format: +## Parameters -~~~ sql -SHOW INDEX FROM db1.table1; -~~~ +Parameter | Description +----------|------------ +`var_name` | The name of the table for which you want to show indexes. ## Response @@ -48,24 +46,27 @@ Field | Description ## Examples ~~~ -CREATE TABLE db1.table1 ( +> CREATE TABLE t1 ( a INT PRIMARY KEY, b DECIMAL, c TIMESTAMP, d STRING -); + ); +CREATE TABLE -CREATE INDEX b_c_idx ON db1.table1 (b, c) STORING (d); +> CREATE INDEX b_c_idx ON t1 (b, c) STORING (d); +CREATE INDEX -SHOW INDEX FROM db1.table1; +> SHOW INDEX FROM t1; +--------+---------+--------+-----+--------+-----------+---------+ | Table | Name | Unique | Seq | Column | Direction | Storing | +--------+---------+--------+-----+--------+-----------+---------+ -| table1 | primary | true | 1 | a | ASC | false | -| table1 | b_c_idx | false | 1 | b | ASC | false | -| table1 | b_c_idx | false | 2 | c | ASC | false | -| table1 | b_c_idx | false | 3 | d | N/A | true | +| t1 | primary | true | 1 | a | ASC | false | +| t1 | b_c_idx | false | 1 | b | ASC | false | +| t1 | b_c_idx | false | 2 | c | ASC | false | +| t1 | b_c_idx | false | 3 | d | N/A | true | +--------+---------+--------+-----+--------+-----------+---------+ +(4 rows) ~~~ ## See Also @@ -73,4 +74,4 @@ SHOW INDEX FROM db1.table1; - [`CREATE INDEX`](create-index.html) - [`DROP INDEX`](drop-index.html) - [`RENAME INDEX`](rename-index.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html) diff --git a/upsert.md b/upsert.md index 1766c2d1686..816a286e11d 100644 --- a/upsert.md +++ b/upsert.md @@ -50,7 +50,7 @@ INSERT INTO t (a, b, c) In this example, the `id` column is the primary key. Because the inserted `id` value does not conflict with the `id` value of any existing row, the `UPSERT` statement inserts a new row into the table. ~~~ -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -58,10 +58,10 @@ SELECT * FROM accounts; | 2 | 20000.75 | +----+----------+ -UPSERT INTO accounts (id, balance) VALUES (3, 6325.20); +> UPSERT INTO accounts (id, balance) VALUES (3, 6325.20); INSERT 1 -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -76,7 +76,7 @@ SELECT * FROM accounts; In this example, the `id` column is the primary key. Because the inserted `id` value is not unique, the `UPSERT` statement updates the row with the new `balance`. ~~~ -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -85,10 +85,10 @@ SELECT * FROM accounts; | 3 | 6325.2 | +----+----------+ -UPSERT INTO accounts (id, balance) VALUES (3, 7500.83); +> UPSERT INTO accounts (id, balance) VALUES (3, 7500.83); INSERT 1 -SELECT * FROM accounts; +> SELECT * FROM accounts; +----+----------+ | id | balance | +----+----------+ @@ -103,7 +103,7 @@ SELECT * FROM accounts; `UPSERT` will not update rows when the uniquness conflict is on columns not in the primary key. In this example, the `a` column is the primary key, but the `b` column also has the [`UNIQUE`](constraints.html#unique) constraint. Because the inserted `b` value is not unique, the `UPSERT` fails. ~~~ -SELECT * FROM unique_test; +> SELECT * FROM unique_test; +---+---+ | a | b | +---+---+ @@ -112,17 +112,17 @@ SELECT * FROM unique_test; | 3 | 3 | +---+---+ -UPSERT INTO unique_test VALUES (4, 1); +> UPSERT INTO unique_test VALUES (4, 1); pq: duplicate key value (b)=(1) violates unique constraint "unique_test_b_key" ~~~ In such a case, you would need to use the [`INSERT ON CONFLICT`](insert.html) statement to specify the `b` column as the column with the `UNIQUE` constraint. ~~~ -INSERT INTO unique_test VALUES (4, 1) ON CONFLICT (b) DO UPDATE SET a = excluded.a; +> INSERT INTO unique_test VALUES (4, 1) ON CONFLICT (b) DO UPDATE SET a = excluded.a; INSERT 1 -SELECT * FROM unique_test; +> SELECT * FROM unique_test; +---+---+ | a | b | +---+---+ @@ -135,4 +135,4 @@ SELECT * FROM unique_test; ## See Also - [`INSERT`](insert.html) -- [Other SQL Statements](sql-statements.html) \ No newline at end of file +- [Other SQL Statements](sql-statements.html)