Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit ee7e8f3

Browse files
deanrasheeddeanrasheed
committed
Doc: Miscellaneous doc updates for MERGE.
Update a few places in the documentation that should mention MERGE among the list of applicable commands. In a couple of places, a slightly more detailed description of what happens for MERGE seems appropriate. Reviewed by Alvaro Herrera. Discussion: http://postgr.es/m/CAEZATCWqHLcxab89ATMQZNGFG_mxDPM%2BjzkSbXKD3JYPfRGvtw%40mail.gmail.com
1 parent 87f3667 commit ee7e8f3

12 files changed

+58
-23
lines changed

‎doc/src/sgml/arch-dev.sgml

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -530,13 +530,15 @@
530530
</para>
531531

532532
<para>
533-
The executor mechanism is used to evaluate all four basic SQL query
533+
The executor mechanism is used to evaluate all five basic SQL query
534534
types: <command>SELECT</command>, <command>INSERT</command>,
535-
<command>UPDATE</command>, and <command>DELETE</command>.
535+
<command>UPDATE</command>, <command>DELETE</command>, and
536+
<command>MERGE</command>.
536537
For <command>SELECT</command>, the top-level executor code
537538
only needs to send each row returned by the query plan tree
538539
off to the client. <command>INSERT ... SELECT</command>,
539-
<command>UPDATE</command>, and <command>DELETE</command>
540+
<command>UPDATE</command>, <command>DELETE</command>, and
541+
<command>MERGE</command>
540542
are effectively <command>SELECT</command>s under a special
541543
top-level plan node called <literal>ModifyTable</literal>.
542544
</para>
@@ -552,7 +554,13 @@
552554
mark the old row deleted. For <command>DELETE</command>, the only
553555
column that is actually returned by the plan is the TID, and the
554556
<literal>ModifyTable</literal> node simply uses the TID to visit each
555-
target row and mark it deleted.
557+
target row and mark it deleted. For <command>MERGE</command>, the
558+
planner joins the source and target relations, and includes all
559+
column values required by any of the <literal>WHEN</literal> clauses,
560+
plus the TID of the target row; this data is fed up to the
561+
<literal>ModifyTable</literal> node, which uses the information to
562+
work out which <literal>WHEN</literal> clause to execute, and then
563+
inserts, updates or deletes the target row, as required.
556564
</para>
557565

558566
<para>

‎doc/src/sgml/ddl.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1804,7 +1804,8 @@ REVOKE ALL ON accounts FROM PUBLIC;
18041804
view, or other table-like object.
18051805
Also allows use of <command>COPY TO</command>.
18061806
This privilege is also needed to reference existing column values in
1807-
<command>UPDATE</command> or <command>DELETE</command>.
1807+
<command>UPDATE</command>, <command>DELETE</command>,
1808+
or <command>MERGE</command>.
18081809
For sequences, this privilege also allows use of the
18091810
<function>currval</function> function.
18101811
For large objects, this privilege allows the object to be read.

‎doc/src/sgml/high-availability.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1611,7 +1611,8 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
16111611
<listitem>
16121612
<para>
16131613
Data Manipulation Language (DML): <command>INSERT</command>,
1614-
<command>UPDATE</command>, <command>DELETE</command>, <command>COPY FROM</command>,
1614+
<command>UPDATE</command>, <command>DELETE</command>,
1615+
<command>MERGE</command>, <command>COPY FROM</command>,
16151616
<command>TRUNCATE</command>.
16161617
Note that there are no allowed actions that result in a trigger
16171618
being executed during recovery. This restriction applies even to

‎doc/src/sgml/perform.sgml

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -788,9 +788,10 @@ ROLLBACK;
788788

789789
<para>
790790
As seen in this example, when the query is an <command>INSERT</command>,
791-
<command>UPDATE</command>, or <command>DELETE</command> command, the actual work of
791+
<command>UPDATE</command>, <command>DELETE</command>, or
792+
<command>MERGE</command> command, the actual work of
792793
applying the table changes is done by a top-level Insert, Update,
793-
or Delete plan node. The plan nodes underneath this node perform
794+
Delete, or Merge plan node. The plan nodes underneath this node perform
794795
the work of locating the old rows and/or computing the new data.
795796
So above, we see the same sort of bitmap table scan we've seen already,
796797
and its output is fed to an Update node that stores the updated rows.
@@ -803,7 +804,8 @@ ROLLBACK;
803804
</para>
804805

805806
<para>
806-
When an <command>UPDATE</command> or <command>DELETE</command> command affects an
807+
When an <command>UPDATE</command>, <command>DELETE</command>, or
808+
<command>MERGE</command> command affects an
807809
inheritance hierarchy, the output might look like this:
808810

809811
<screen>

‎doc/src/sgml/plpgsql.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1044,7 +1044,8 @@ INSERT INTO mytable VALUES (1,'one'), (2,'two');
10441044
<application>PL/pgSQL</application> variable values can be
10451045
automatically inserted into optimizable SQL commands, which
10461046
are <command>SELECT</command>, <command>INSERT</command>,
1047-
<command>UPDATE</command>, <command>DELETE</command>, and certain
1047+
<command>UPDATE</command>, <command>DELETE</command>,
1048+
<command>MERGE</command>, and certain
10481049
utility commands that incorporate one of these, such
10491050
as <command>EXPLAIN</command> and <command>CREATE TABLE ... AS
10501051
SELECT</command>. In these commands,

‎doc/src/sgml/protocol.sgml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4115,6 +4115,13 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
41154115
<replaceable>rows</replaceable> is the number of rows updated.
41164116
</para>
41174117

4118+
<para>
4119+
For a <command>MERGE</command> command, the tag is
4120+
<literal>MERGE <replaceable>rows</replaceable></literal> where
4121+
<replaceable>rows</replaceable> is the number of rows inserted,
4122+
updated, or deleted.
4123+
</para>
4124+
41184125
<para>
41194126
For a <command>SELECT</command> or <command>CREATE TABLE AS</command>
41204127
command, the tag is <literal>SELECT <replaceable>rows</replaceable></literal>

‎doc/src/sgml/queries.sgml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2064,8 +2064,8 @@ SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression
20642064
in a <literal>WITH</literal> clause can be a <command>SELECT</command>,
20652065
<command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command>; and the
20662066
<literal>WITH</literal> clause itself is attached to a primary statement that can
2067-
also be a <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>, or
2068-
<command>DELETE</command>.
2067+
be a <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>,
2068+
<command>DELETE</command>, or <command>MERGE</command>.
20692069
</para>
20702070

20712071
<sect2 id="queries-with-select">
@@ -2587,7 +2587,8 @@ SELECT * FROM w AS w1 JOIN w AS w2 ON w1.f = w2.f;
25872587
<para>
25882588
The examples above only show <literal>WITH</literal> being used with
25892589
<command>SELECT</command>, but it can be attached in the same way to
2590-
<command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command>.
2590+
<command>INSERT</command>, <command>UPDATE</command>,
2591+
<command>DELETE</command>, or <command>MERGE</command>.
25912592
In each case it effectively provides temporary table(s) that can
25922593
be referred to in the main command.
25932594
</para>
@@ -2597,8 +2598,9 @@ SELECT * FROM w AS w1 JOIN w AS w2 ON w1.f = w2.f;
25972598
<title>Data-Modifying Statements in <literal>WITH</literal></title>
25982599

25992600
<para>
2600-
You can use data-modifying statements (<command>INSERT</command>,
2601-
<command>UPDATE</command>, or <command>DELETE</command>) in <literal>WITH</literal>. This
2601+
You can use most data-modifying statements (<command>INSERT</command>,
2602+
<command>UPDATE</command>, or <command>DELETE</command>, but not
2603+
<command>MERGE</command>) in <literal>WITH</literal>. This
26022604
allows you to perform several different operations in the same query.
26032605
An example is:
26042606

‎doc/src/sgml/ref/create_publication.sgml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
306306
<command>UPDATE</command>, or it may not be published at all.
307307
</para>
308308

309+
<para>
310+
For a <command>MERGE</command> command, the publication will publish an
311+
<command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command>
312+
for each row inserted, updated, or deleted.
313+
</para>
314+
309315
<para>
310316
<command>ATTACH</command>ing a table into a partition tree whose root is
311317
published using a publication with <literal>publish_via_partition_root</literal>

‎doc/src/sgml/ref/explain.sgml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,8 @@ EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replac
9494
statement will happen as usual. If you wish to use
9595
<command>EXPLAIN ANALYZE</command> on an
9696
<command>INSERT</command>, <command>UPDATE</command>,
97-
<command>DELETE</command>, <command>CREATE TABLE AS</command>,
97+
<command>DELETE</command>, <command>MERGE</command>,
98+
<command>CREATE TABLE AS</command>,
9899
or <command>EXECUTE</command> statement
99100
without letting the command affect your data, use this approach:
100101
<programlisting>
@@ -272,7 +273,8 @@ ROLLBACK;
272273
<listitem>
273274
<para>
274275
Any <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>,
275-
<command>DELETE</command>, <command>VALUES</command>, <command>EXECUTE</command>,
276+
<command>DELETE</command>, <command>MERGE</command>,
277+
<command>VALUES</command>, <command>EXECUTE</command>,
276278
<command>DECLARE</command>, <command>CREATE TABLE AS</command>, or
277279
<command>CREATE MATERIALIZED VIEW AS</command> statement, whose execution
278280
plan you wish to see.

‎doc/src/sgml/ref/prepare.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,8 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class
116116
<listitem>
117117
<para>
118118
Any <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>,
119-
<command>DELETE</command>, or <command>VALUES</command> statement.
119+
<command>DELETE</command>, <command>MERGE</command>, or <command>VALUES</command>
120+
statement.
120121
</para>
121122
</listitem>
122123
</varlistentry>

‎doc/src/sgml/ref/set_transaction.sgml

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,8 @@ SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transa
121121
The transaction isolation level cannot be changed after the first query or
122122
data-modification statement (<command>SELECT</command>,
123123
<command>INSERT</command>, <command>DELETE</command>,
124-
<command>UPDATE</command>, <command>FETCH</command>, or
124+
<command>UPDATE</command>, <command>MERGE</command>,
125+
<command>FETCH</command>, or
125126
<command>COPY</command>) of a transaction has been executed. See
126127
<xref linkend="mvcc"/> for more information about transaction
127128
isolation and concurrency control.
@@ -131,8 +132,9 @@ SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transa
131132
The transaction access mode determines whether the transaction is
132133
read/write or read-only. Read/write is the default. When a
133134
transaction is read-only, the following SQL commands are
134-
disallowed: <literal>INSERT</literal>, <literal>UPDATE</literal>,
135-
<literal>DELETE</literal>, and <literal>COPY FROM</literal> if the
135+
disallowed: <command>INSERT</command>, <command>UPDATE</command>,
136+
<command>DELETE</command>, <command>MERGE</command>, and
137+
<command>COPY FROM</command> if the
136138
table they would write to is not a temporary table; all
137139
<literal>CREATE</literal>, <literal>ALTER</literal>, and
138140
<literal>DROP</literal> commands; <literal>COMMENT</literal>,
@@ -169,7 +171,8 @@ SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transa
169171
start of a transaction, before the first query or
170172
data-modification statement (<command>SELECT</command>,
171173
<command>INSERT</command>, <command>DELETE</command>,
172-
<command>UPDATE</command>, <command>FETCH</command>, or
174+
<command>UPDATE</command>, <command>MERGE</command>,
175+
<command>FETCH</command>, or
173176
<command>COPY</command>) of the transaction. Furthermore, the transaction
174177
must already be set to <literal>SERIALIZABLE</literal> or
175178
<literal>REPEATABLE READ</literal> isolation level (otherwise, the snapshot

‎doc/src/sgml/xfunc.sgml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,8 @@
186186
language can be packaged together and defined as a function.
187187
Besides <command>SELECT</command> queries, the commands can include data
188188
modification queries (<command>INSERT</command>,
189-
<command>UPDATE</command>, and <command>DELETE</command>), as well as
189+
<command>UPDATE</command>, <command>DELETE</command>, and
190+
<command>MERGE</command>), as well as
190191
other SQL commands. (You cannot use transaction control commands, e.g.,
191192
<command>COMMIT</command>, <command>SAVEPOINT</command>, and some utility
192193
commands, e.g., <literal>VACUUM</literal>, in <acronym>SQL</acronym> functions.)

0 commit comments

Comments
 (0)