From 97994ef629e9e30a41971f4369b8ec74eeab1fa3 Mon Sep 17 00:00:00 2001 From: Eric Harmeling Date: Wed, 14 Oct 2020 16:56:26 -0400 Subject: [PATCH 1/2] UPDATE FROM syntax --- _includes/v19.2/sql/diagrams/update.html | 182 ++++++++++-------- _includes/v20.1/sql/diagrams/update.html | 222 +++++++++++++--------- _includes/v20.2/sql/diagrams/update.html | 228 ++++++++++++++--------- v19.2/update.md | 28 ++- v20.1/update.md | 28 ++- v20.2/update.md | 28 ++- 6 files changed, 454 insertions(+), 262 deletions(-) diff --git a/_includes/v19.2/sql/diagrams/update.html b/_includes/v19.2/sql/diagrams/update.html index 7ead70594b4..113cfb1413c 100644 --- a/_includes/v19.2/sql/diagrams/update.html +++ b/_includes/v19.2/sql/diagrams/update.html @@ -1,118 +1,142 @@ -
+
- - + + WITH - - -common_table_expr + + +common_table_expr - - -, - - -UPDATE + + +, + + +UPDATE - - -table_name + + +table_name - - -AS + + + +opt_index_flags + + + +AS - - -table_alias_name + + +table_alias_name - - -SET + + +SET - - + + column_name - - -= + + += - - -a_expr + + +a_expr ( - - + + column_name , - - -) - - -= - - -( + + +) + + += + + +( - - -select_stmt + + +select_stmt + + + + +a_expr + + +, - - -a_expr + + +a_expr - - -, - - -) + + +, + + +) , - - -WHERE + + +FROM + + + +table_ref + + + +, + + +WHERE - - -a_expr + + +a_expr - - -sort_clause + + +sort_clause - - -limit_clause + + +limit_clause - - -RETURNING + + +RETURNING - - -target_list + + +target_list - - -NOTHING - - - + + +NOTHING + + +
diff --git a/_includes/v20.1/sql/diagrams/update.html b/_includes/v20.1/sql/diagrams/update.html index 0b81b98ad22..4eaf6bc48dd 100644 --- a/_includes/v20.1/sql/diagrams/update.html +++ b/_includes/v20.1/sql/diagrams/update.html @@ -1,97 +1,145 @@ -
+
WITH - - -RECURSIVE - - -common_table_expr - -, - - -UPDATE - - -table_name - - -opt_index_flags - -AS - - -table_alias_name - -SET - - -column_name - -= - - -a_expr + + +RECURSIVE + + + +common_table_expr + + + +, + + +UPDATE + + + +table_name + + + + +opt_index_flags + + + +AS + + + +table_alias_name + + + +SET + + + +column_name + + + += + + + +a_expr + + -( - - -column_name +( + + + +column_name + + , - - -) - - -= - - -( - - -select_stmt - - -a_expr - -, - - -a_expr - -, - - -) + + +) + + += + + +( + + + +select_stmt + + + + +a_expr + + + +, + + + +a_expr + + + +, + + +) -, - - -opt_from_list - -WHERE - - -a_expr - - -sort_clause - - -limit_clause - -RETURNING - - -target_list - -NOTHING - - -
+, + + +FROM + + + +table_ref + + + +, + + +WHERE + + + +a_expr + + + + +sort_clause + + + + +limit_clause + + + +RETURNING + + + +target_list + + + +NOTHING + + + +
diff --git a/_includes/v20.2/sql/diagrams/update.html b/_includes/v20.2/sql/diagrams/update.html index 0b81b98ad22..49b1663edbb 100644 --- a/_includes/v20.2/sql/diagrams/update.html +++ b/_includes/v20.2/sql/diagrams/update.html @@ -1,97 +1,151 @@ -
+
WITH - - -RECURSIVE - - -common_table_expr - -, - - -UPDATE - - -table_name - - -opt_index_flags - -AS - - -table_alias_name - -SET - - -column_name - -= - - -a_expr + + +RECURSIVE + + + +common_table_expr + + + +, + + +UPDATE + + +ONLY + + + +table_name + + + + +opt_index_flags + + + +* + + +AS + + + +table_alias_name + + + +SET + + + +column_name + + + += + + + +a_expr + + -( - - -column_name +( + + + +column_name + + , - - -) - - -= - - -( - - -select_stmt - - -a_expr - -, - - -a_expr - -, - - -) + + +) + + += + + +( + + + +select_stmt + + + + +a_expr + + + +, + + + +a_expr + + + +, + + +) -, - - -opt_from_list - -WHERE - - -a_expr - - -sort_clause - - -limit_clause - -RETURNING - - -target_list - -NOTHING - - -
+, + + +FROM + + + +table_ref + + + +, + + +WHERE + + + +a_expr + + + + +sort_clause + + + + +limit_clause + + + +RETURNING + + + +target_list + + + +NOTHING + + + +
diff --git a/v19.2/update.md b/v19.2/update.md index 44c583b695e..02fbf76637f 100644 --- a/v19.2/update.md +++ b/v19.2/update.md @@ -29,9 +29,8 @@ Parameter | Description `table_name` | The name of the table that contains the rows you want to update. `AS table_alias_name` | An alias for the table name. When an alias is provided, it completely hides the actual table name. `column_name` | The name of the column whose values you want to update. -`a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use. -`DEFAULT` | To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. -`column_name` | The name of a column to update. +`a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use.

To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. +`FROM table_ref` | Specify a different table to reference in `UPDATE` expressions, or `RETURNING` and `WHERE` clauses. For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). `select_stmt` | A [selection query](selection-queries.html). Each value must match the [data type](data-types.html) of its column on the left side of `=`. `WHERE a_expr`| `a_expr` must be a [scalar expression](scalar-expressions.html) that returns Boolean values using columns (e.g., ` = `). Update rows that return `TRUE`.

**Without a `WHERE` clause in your statement, `UPDATE` updates all rows in the table.** `sort_clause` | An `ORDER BY` clause. See [Ordering Query Results](query-order.html) and [Ordering of rows in DML statements](query-order.html#ordering-rows-in-dml-statements) for more details. @@ -209,6 +208,29 @@ For examples, see [Update with index hints](#update-with-index-hints). (5 rows) ~~~ +### Update using values from a different table + +{% include copy-clipboard.html %} +~~~ sql +> UPDATE rides SET revenue = NULL FROM vehicles WHERE rides.rider_id=vehicles.owner_id AND rides.vehicle_id=vehicles.id; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT * FROM rides WHERE revenue IS NULL LIMIT 5; +~~~ + +~~~ + id | city | vehicle_city | rider_id | vehicle_id | start_address | end_address | start_time | end_time | revenue ++--------------------------------------+-----------+--------------+--------------------------------------+--------------------------------------+--------------------------------+-----------------------------+---------------------------+---------------------------+---------+ + ab020c49-ba5e-4800-8000-00000000014e | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 1905 Christopher Locks Apt. 77 | 66037 Belinda Plaza Apt. 93 | 2018-12-13 03:04:05+00:00 | 2018-12-14 08:04:05+00:00 | NULL + ac083126-e978-4800-8000-000000000150 | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 50217 Victoria Fields Apt. 44 | 56217 Wilson Spring | 2018-12-07 03:04:05+00:00 | 2018-12-07 10:04:05+00:00 | NULL + af9db22d-0e56-4800-8000-000000000157 | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 20937 Gibson River | 50480 Steven Row | 2018-12-23 03:04:05+00:00 | 2018-12-25 11:04:05+00:00 | NULL + b22d0e56-0418-4000-8000-00000000015c | amsterdam | amsterdam | bd70a3d7-0a3d-4000-8000-000000000025 | bbbbbbbb-bbbb-4800-8000-00000000000b | 36054 Ward Crescent Suite 35 | 7745 John Run | 2018-12-09 03:04:05+00:00 | 2018-12-10 18:04:05+00:00 | NULL + b53f7ced-9168-4000-8000-000000000162 | amsterdam | amsterdam | bd70a3d7-0a3d-4000-8000-000000000025 | bbbbbbbb-bbbb-4800-8000-00000000000b | 86091 Mcdonald Motorway | 1652 Robert Ford | 2018-12-05 03:04:05+00:00 | 2018-12-05 06:04:05+00:00 | NULL +(5 rows) +~~~ + ### Update all rows {{site.data.alerts.callout_danger}} diff --git a/v20.1/update.md b/v20.1/update.md index b49db56e0da..ca60951bc82 100644 --- a/v20.1/update.md +++ b/v20.1/update.md @@ -29,9 +29,8 @@ Parameter | Description `table_name` | The name of the table that contains the rows you want to update. `AS table_alias_name` | An alias for the table name. When an alias is provided, it completely hides the actual table name. `column_name` | The name of the column whose values you want to update. -`a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use. -`DEFAULT` | To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. -`column_name` | The name of a column to update. +`a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use.

To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. +`FROM table_ref` | Specify a different table to reference in `UPDATE` expressions, or `RETURNING` and `WHERE` clauses. For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). `select_stmt` | A [selection query](selection-queries.html). Each value must match the [data type](data-types.html) of its column on the left side of `=`. `WHERE a_expr`| `a_expr` must be a [scalar expression](scalar-expressions.html) that returns Boolean values using columns (e.g., ` = `). Update rows that return `TRUE`.

**Without a `WHERE` clause in your statement, `UPDATE` updates all rows in the table.** `sort_clause` | An `ORDER BY` clause. See [Ordering Query Results](query-order.html) and [Ordering of rows in DML statements](query-order.html#ordering-rows-in-dml-statements) for more details. @@ -209,6 +208,29 @@ For examples, see [Update with index hints](#update-with-index-hints). (5 rows) ~~~ +### Update using values from a different table + +{% include copy-clipboard.html %} +~~~ sql +> UPDATE rides SET revenue = NULL FROM vehicles WHERE rides.rider_id=vehicles.owner_id AND rides.vehicle_id=vehicles.id; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT * FROM rides WHERE revenue IS NULL LIMIT 5; +~~~ + +~~~ + id | city | vehicle_city | rider_id | vehicle_id | start_address | end_address | start_time | end_time | revenue +---------------------------------------+-----------+--------------+--------------------------------------+--------------------------------------+--------------------------------+-----------------------------+---------------------------+---------------------------+---------- + ab020c49-ba5e-4800-8000-00000000014e | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 1905 Christopher Locks Apt. 77 | 66037 Belinda Plaza Apt. 93 | 2018-12-13 03:04:05+00:00 | 2018-12-14 08:04:05+00:00 | NULL + ac083126-e978-4800-8000-000000000150 | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 50217 Victoria Fields Apt. 44 | 56217 Wilson Spring | 2018-12-07 03:04:05+00:00 | 2018-12-07 10:04:05+00:00 | NULL + af9db22d-0e56-4800-8000-000000000157 | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 20937 Gibson River | 50480 Steven Row | 2018-12-23 03:04:05+00:00 | 2018-12-25 11:04:05+00:00 | NULL + b22d0e56-0418-4000-8000-00000000015c | amsterdam | amsterdam | bd70a3d7-0a3d-4000-8000-000000000025 | bbbbbbbb-bbbb-4800-8000-00000000000b | 36054 Ward Crescent Suite 35 | 7745 John Run | 2018-12-09 03:04:05+00:00 | 2018-12-10 18:04:05+00:00 | NULL + b53f7ced-9168-4000-8000-000000000162 | amsterdam | amsterdam | bd70a3d7-0a3d-4000-8000-000000000025 | bbbbbbbb-bbbb-4800-8000-00000000000b | 86091 Mcdonald Motorway | 1652 Robert Ford | 2018-12-05 03:04:05+00:00 | 2018-12-05 06:04:05+00:00 | NULL +(5 rows) +~~~ + ### Update all rows {{site.data.alerts.callout_danger}} diff --git a/v20.2/update.md b/v20.2/update.md index dd94d69566a..64dadaabbe3 100644 --- a/v20.2/update.md +++ b/v20.2/update.md @@ -29,9 +29,8 @@ Parameter | Description `table_name` | The name of the table that contains the rows you want to update. `AS table_alias_name` | An alias for the table name. When an alias is provided, it completely hides the actual table name. `column_name` | The name of the column whose values you want to update. -`a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use. -`DEFAULT` | To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. -`column_name` | The name of a column to update. +`a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use.

To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. +`FROM table_ref` | Specify a different table to reference in `UPDATE` expressions, or `RETURNING` and `WHERE` clauses. For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). `select_stmt` | A [selection query](selection-queries.html). Each value must match the [data type](data-types.html) of its column on the left side of `=`. `WHERE a_expr`| `a_expr` must be a [scalar expression](scalar-expressions.html) that returns Boolean values using columns (e.g., ` = `). Update rows that return `TRUE`.

**Without a `WHERE` clause in your statement, `UPDATE` updates all rows in the table.** `sort_clause` | An `ORDER BY` clause. See [Ordering Query Results](query-order.html) and [Ordering of rows in DML statements](query-order.html#ordering-rows-in-dml-statements) for more details. @@ -209,6 +208,29 @@ For examples, see [Update with index hints](#update-with-index-hints). (5 rows) ~~~ +### Update using values from a different table + +{% include copy-clipboard.html %} +~~~ sql +> UPDATE rides SET revenue = NULL FROM vehicles WHERE rides.rider_id=vehicles.owner_id AND rides.vehicle_id=vehicles.id; +~~~ + +{% include copy-clipboard.html %} +~~~ sql +> SELECT * FROM rides WHERE revenue IS NULL LIMIT 5; +~~~ + +~~~ + id | city | vehicle_city | rider_id | vehicle_id | start_address | end_address | start_time | end_time | revenue +---------------------------------------+-----------+--------------+--------------------------------------+--------------------------------------+--------------------------------+-----------------------------+---------------------------+---------------------------+---------- + ab020c49-ba5e-4800-8000-00000000014e | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 1905 Christopher Locks Apt. 77 | 66037 Belinda Plaza Apt. 93 | 2018-12-13 03:04:05+00:00 | 2018-12-14 08:04:05+00:00 | NULL + ac083126-e978-4800-8000-000000000150 | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 50217 Victoria Fields Apt. 44 | 56217 Wilson Spring | 2018-12-07 03:04:05+00:00 | 2018-12-07 10:04:05+00:00 | NULL + af9db22d-0e56-4800-8000-000000000157 | amsterdam | amsterdam | c28f5c28-f5c2-4000-8000-000000000026 | aaaaaaaa-aaaa-4800-8000-00000000000a | 20937 Gibson River | 50480 Steven Row | 2018-12-23 03:04:05+00:00 | 2018-12-25 11:04:05+00:00 | NULL + b22d0e56-0418-4000-8000-00000000015c | amsterdam | amsterdam | bd70a3d7-0a3d-4000-8000-000000000025 | bbbbbbbb-bbbb-4800-8000-00000000000b | 36054 Ward Crescent Suite 35 | 7745 John Run | 2018-12-09 03:04:05+00:00 | 2018-12-10 18:04:05+00:00 | NULL + b53f7ced-9168-4000-8000-000000000162 | amsterdam | amsterdam | bd70a3d7-0a3d-4000-8000-000000000025 | bbbbbbbb-bbbb-4800-8000-00000000000b | 86091 Mcdonald Motorway | 1652 Robert Ford | 2018-12-05 03:04:05+00:00 | 2018-12-05 06:04:05+00:00 | NULL +(5 rows) +~~~ + ### Update all rows {{site.data.alerts.callout_danger}} From 49ca64e010524bbd99184cd6b9e85454df7f653f Mon Sep 17 00:00:00 2001 From: Eric Harmeling Date: Mon, 19 Oct 2020 11:45:37 -0400 Subject: [PATCH 2/2] radu feedback --- v19.2/update.md | 10 +++++++++- v20.1/update.md | 10 +++++++++- v20.2/update.md | 10 +++++++++- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/v19.2/update.md b/v19.2/update.md index 02fbf76637f..95087caadd6 100644 --- a/v19.2/update.md +++ b/v19.2/update.md @@ -30,7 +30,7 @@ Parameter | Description `AS table_alias_name` | An alias for the table name. When an alias is provided, it completely hides the actual table name. `column_name` | The name of the column whose values you want to update. `a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use.

To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. -`FROM table_ref` | Specify a different table to reference in `UPDATE` expressions, or `RETURNING` and `WHERE` clauses. For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). +`FROM table_ref` | Specify a table to reference, but not update, in `UPDATE` expressions, or in `RETURNING` and `WHERE` clauses. For more details, see [Reference other tables in an update](#reference-other-tables-in-an-update). `select_stmt` | A [selection query](selection-queries.html). Each value must match the [data type](data-types.html) of its column on the left side of `=`. `WHERE a_expr`| `a_expr` must be a [scalar expression](scalar-expressions.html) that returns Boolean values using columns (e.g., ` = `). Update rows that return `TRUE`.

**Without a `WHERE` clause in your statement, `UPDATE` updates all rows in the table.** `sort_clause` | An `ORDER BY` clause. See [Ordering Query Results](query-order.html) and [Ordering of rows in DML statements](query-order.html#ordering-rows-in-dml-statements) for more details. @@ -63,6 +63,14 @@ To view how the index hint modifies the query plan that CockroachDB follows for For examples, see [Update with index hints](#update-with-index-hints). +## Reference other tables in an update + +To reference values from a table other than the table being updated, add a `FROM` clause that specifies one or more tables in the cluster. Values from tables specified in a `FROM` clause can be used in `UPDATE` expressions, and in `RETURNING` and `WHERE` clauses. + +When executing an `UPDATE` query with a `FROM` clause, CockroachDB [joins](joins.html) the target table (i.e., the table being updated) to the tables referenced in the `FROM` clause. The output of this join should have the same number of rows as the rows being updated in the target table, as CockroachDB uses a single row from the join output to update a given row in the target table. If the join produces more rows than the rows being updated in the target table, there is no way to predict which row from the join output will be used to update a row in the target table. + +For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). + ## Examples {% include {{page.version.version}}/sql/movr-statements.md %} diff --git a/v20.1/update.md b/v20.1/update.md index ca60951bc82..11273ce30b0 100644 --- a/v20.1/update.md +++ b/v20.1/update.md @@ -30,7 +30,7 @@ Parameter | Description `AS table_alias_name` | An alias for the table name. When an alias is provided, it completely hides the actual table name. `column_name` | The name of the column whose values you want to update. `a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use.

To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. -`FROM table_ref` | Specify a different table to reference in `UPDATE` expressions, or `RETURNING` and `WHERE` clauses. For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). +`FROM table_ref` | Specify a table to reference, but not update, in `UPDATE` expressions, or in `RETURNING` and `WHERE` clauses. For more details, see [Reference other tables in an update](#reference-other-tables-in-an-update). `select_stmt` | A [selection query](selection-queries.html). Each value must match the [data type](data-types.html) of its column on the left side of `=`. `WHERE a_expr`| `a_expr` must be a [scalar expression](scalar-expressions.html) that returns Boolean values using columns (e.g., ` = `). Update rows that return `TRUE`.

**Without a `WHERE` clause in your statement, `UPDATE` updates all rows in the table.** `sort_clause` | An `ORDER BY` clause. See [Ordering Query Results](query-order.html) and [Ordering of rows in DML statements](query-order.html#ordering-rows-in-dml-statements) for more details. @@ -63,6 +63,14 @@ To view how the index hint modifies the query plan that CockroachDB follows for For examples, see [Update with index hints](#update-with-index-hints). +## Reference other tables in an update + +To reference values from a table other than the table being updated, add a `FROM` clause that specifies one or more tables in the cluster. Values from tables specified in a `FROM` clause can be used in `UPDATE` expressions, and in `RETURNING` and `WHERE` clauses. + +When executing an `UPDATE` query with a `FROM` clause, CockroachDB [joins](joins.html) the target table (i.e., the table being updated) to the tables referenced in the `FROM` clause. The output of this join should have the same number of rows as the rows being updated in the target table, as CockroachDB uses a single row from the join output to update a given row in the target table. If the join produces more rows than the rows being updated in the target table, there is no way to predict which row from the join output will be used to update a row in the target table. + +For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). + ## Examples {% include {{page.version.version}}/sql/movr-statements.md %} diff --git a/v20.2/update.md b/v20.2/update.md index 64dadaabbe3..5f945edf548 100644 --- a/v20.2/update.md +++ b/v20.2/update.md @@ -30,7 +30,7 @@ Parameter | Description `AS table_alias_name` | An alias for the table name. When an alias is provided, it completely hides the actual table name. `column_name` | The name of the column whose values you want to update. `a_expr` | The new value you want to use, the [aggregate function](functions-and-operators.html#aggregate-functions) you want to perform, or the [scalar expression](scalar-expressions.html) you want to use.

To fill columns with their [default values](default-value.html), use `DEFAULT VALUES` in place of `a_expr`. To fill a specific column with its default value, leave the value out of the `a_expr` or use `DEFAULT` at the appropriate position. -`FROM table_ref` | Specify a different table to reference in `UPDATE` expressions, or `RETURNING` and `WHERE` clauses. For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). +`FROM table_ref` | Specify a table to reference, but not update, in `UPDATE` expressions, or in `RETURNING` and `WHERE` clauses. For more details, see [Reference other tables in an update](#reference-other-tables-in-an-update). `select_stmt` | A [selection query](selection-queries.html). Each value must match the [data type](data-types.html) of its column on the left side of `=`. `WHERE a_expr`| `a_expr` must be a [scalar expression](scalar-expressions.html) that returns Boolean values using columns (e.g., ` = `). Update rows that return `TRUE`.

**Without a `WHERE` clause in your statement, `UPDATE` updates all rows in the table.** `sort_clause` | An `ORDER BY` clause. See [Ordering Query Results](query-order.html) and [Ordering of rows in DML statements](query-order.html#ordering-rows-in-dml-statements) for more details. @@ -63,6 +63,14 @@ To view how the index hint modifies the query plan that CockroachDB follows for For examples, see [Update with index hints](#update-with-index-hints). +## Reference other tables in an update + +To reference values from a table other than the table being updated, add a `FROM` clause that specifies one or more tables in the cluster. Values from tables specified in a `FROM` clause can be used in `UPDATE` expressions, and in `RETURNING` and `WHERE` clauses. + +When executing an `UPDATE` query with a `FROM` clause, CockroachDB [joins](joins.html) the target table (i.e., the table being updated) to the tables referenced in the `FROM` clause. The output of this join should have the same number of rows as the rows being updated in the target table, as CockroachDB uses a single row from the join output to update a given row in the target table. If the join produces more rows than the rows being updated in the target table, there is no way to predict which row from the join output will be used to update a row in the target table. + +For an example, see [Update using values from a different table](#update-using-values-from-a-different-table). + ## Examples {% include {{page.version.version}}/sql/movr-statements.md %}