From 07f1264dda0e776a7e329b091c127059bce8cc54 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 15 Oct 2010 19:53:59 -0400 Subject: Allow WITH clauses to be attached to INSERT, UPDATE, DELETE statements. This is not the hoped-for facility of using INSERT/UPDATE/DELETE inside a WITH, but rather the other way around. It seems useful in its own right anyway. Note: catversion bumped because, although the contents of stored rules might look compatible, there's actually a subtle semantic change. A single Query containing a WITH and INSERT...VALUES now represents writing the WITH before the INSERT, not before the VALUES. While it's not clear that that matters to anyone, it seems like a good idea to have it cited in the git history for catversion.h. Original patch by Marko Tiikkaja, with updating and cleanup by Hitoshi Harada. --- doc/src/sgml/queries.sgml | 16 ++++++++++++---- doc/src/sgml/ref/delete.sgml | 16 +++++++++++++++- doc/src/sgml/ref/insert.sgml | 25 ++++++++++++++++++++++++- doc/src/sgml/ref/update.sgml | 16 +++++++++++++++- 4 files changed, 66 insertions(+), 7 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index d16824eddd5..f6e081ea732 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -472,7 +472,7 @@ FROM table_reference , table_r (1 row) This is because a restriction placed in the ON - clause is processed before the join, while + clause is processed before the join, while a restriction placed in the WHERE clause is processed after the join. @@ -1139,7 +1139,7 @@ SELECT a "value", b + c AS sum FROM ... The naming of output columns here is different from that done in the FROM clause (see ). It is possible + linkend="queries-table-aliases">). It is possible to rename the same column twice, but the name assigned in the select list is the one that will be passed on. @@ -1539,7 +1539,7 @@ SELECT select_list FROM table_expression WITH provides a way to write subqueries for use in a larger - SELECT query. The subqueries can be thought of as defining + query. The subqueries can be thought of as defining temporary tables that exist just for this query. One use of this feature is to break down complicated queries into simpler parts. An example is: @@ -1791,12 +1791,20 @@ SELECT n FROM t LIMIT 100; However, the other side of this coin is that the optimizer is less able to push restrictions from the parent query down into a WITH query than an ordinary sub-query. The WITH query will generally be - evaluated as stated, without suppression of rows that the parent query + evaluated as written, without suppression of rows that the parent query might discard afterwards. (But, as mentioned above, evaluation might stop early if the reference(s) to the query demand only a limited number of rows.) + + The examples above only show WITH being used with + SELECT, but it can be attached in the same way to + INSERT, UPDATE, or DELETE. + In each case it effectively provides temporary table(s) that can + be referred to in the main command. + + diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index c87f35c9b40..9406f4e3af0 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -21,6 +21,7 @@ PostgreSQL documentation +[ WITH [ RECURSIVE ] with_query [, ...] ] DELETE FROM [ ONLY ] table [ [ AS ] alias ] [ USING using_list ] [ WHERE condition | WHERE CURRENT OF cursor_name ] @@ -83,6 +84,18 @@ DELETE FROM [ ONLY ] table [ [ AS ] Parameters + + with_query + + + The WITH clause allows you to specify one or more + subqueries that can be referenced by name in the DELETE + query. See and + for details. + + + + ONLY @@ -272,7 +285,8 @@ DELETE FROM tasks WHERE CURRENT OF c_tasks; This command conforms to the SQL standard, except that the USING and RETURNING clauses - are PostgreSQL extensions. + are PostgreSQL extensions, as is the ability + to use WITH with DELETE. diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index 6d17ef05f75..629cc7ea558 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -21,6 +21,7 @@ PostgreSQL documentation +[ WITH [ RECURSIVE ] with_query [, ...] ] INSERT INTO table [ ( column [, ...] ) ] { DEFAULT VALUES | VALUES ( { expression | DEFAULT } [, ...] ) [, ...] | query } [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ] @@ -84,6 +85,26 @@ INSERT INTO table [ ( Parameters + + with_query + + + The WITH clause allows you to specify one or more + subqueries that can be referenced by name in the INSERT + query. See and + for details. + + + It is possible for the query + (SELECT statement) + to also contain a WITH clause. In such a case both + sets of with_query can be referenced within + the query, but the + second one takes precedence since it is more closely nested. + + + + table @@ -287,7 +308,9 @@ INSERT INTO distributors (did, dname) VALUES (DEFAULT, 'XYZ Widgets') INSERT conforms to the SQL standard, except that the RETURNING clause is a - PostgreSQL extension. Also, the case in + PostgreSQL extension, as is the ability + to use WITH with INSERT. + Also, the case in which a column name list is omitted, but not all the columns are filled from the VALUES clause or query, is disallowed by the standard. diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index c89763492ff..5968db1f6fe 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -21,6 +21,7 @@ PostgreSQL documentation +[ WITH [ RECURSIVE ] with_query [, ...] ] UPDATE [ ONLY ] table [ [ AS ] alias ] SET { column = { expression | DEFAULT } | ( column [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...] @@ -79,6 +80,18 @@ UPDATE [ ONLY ] table [ [ AS ] Parameters + + with_query + + + The WITH clause allows you to specify one or more + subqueries that can be referenced by name in the UPDATE + query. See and + for details. + + + + table @@ -345,7 +358,8 @@ UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films; This command conforms to the SQL standard, except that the FROM and RETURNING clauses - are PostgreSQL extensions. + are PostgreSQL extensions, as is the ability + to use WITH with UPDATE. -- cgit v1.2.3