From ca0d2197ca1ed1e72243c5a3466d93e4954d30b0 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Mon, 26 Jun 2006 17:24:41 +0000
Subject: Change the row constructor syntax (ROW(...)) so that list elements
 foo.* will be expanded to a list of their member fields, rather than creating
 a nested rowtype field as formerly.  (The old behavior is still available by
 omitting '.*'.)  This syntax is not allowed by the SQL spec AFAICS, so
 changing its behavior doesn't violate the spec.  The new behavior is
 substantially more useful since it allows, for example, triggers to check for
 data changes with 'if row(new.*) is distinct from row(old.*)'.  Per my recent
 proposal.

---
 doc/src/sgml/syntax.sgml | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 97020845b50..74cc813a681 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.106 2006/03/10 19:10:49 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.107 2006/06/26 17:24:40 tgl Exp $ -->
 
 <chapter id="sql-syntax">
  <title>SQL Syntax</title>
@@ -1570,6 +1570,31 @@ SELECT ROW(1,2.5,'this is a test');
     expression in the list.
    </para>
 
+   <para>
+    A row constructor can include the syntax
+    <replaceable>rowvalue</replaceable><literal>.*</literal>,
+    which will be expanded to a list of the elements of the row value,
+    just as occurs when the <literal>.*</> syntax is used at the top level
+    of a <command>SELECT</> list.  For example, if table <literal>t</> has
+    columns <literal>f1</> and <literal>f2</>, these are the same:
+<programlisting>
+SELECT ROW(t.*, 42) FROM t;
+SELECT ROW(t.f1, t.f2, 42) FROM t;
+</programlisting>
+   </para>
+
+   <note>
+    <para>
+     Before <productname>PostgreSQL</productname> 8.2, the
+     <literal>.*</literal> syntax was not expanded, so that writing
+     <literal>ROW(t.*, 42)</> created a two-field row whose first field
+     was another row value.  The new behavior is usually more useful.
+     If you need the old behavior of nested row values, write the inner
+     row value without <literal>.*</literal>, for instance
+     <literal>ROW(t, 42)</>.
+    </para>
+   </note>
+
    <para>
     By default, the value created by a <literal>ROW</> expression is of
     an anonymous record type.  If necessary, it can be cast to a named
@@ -1619,7 +1644,7 @@ SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
 <programlisting>
 SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
 
-SELECT ROW(a, b, c) IS NOT NULL FROM table;
+SELECT ROW(table.*) IS NULL FROM table;  -- detect all-null rows
 </programlisting>
    For more detail see <xref linkend="functions-comparisons">.
    Row constructors can also be used in connection with subqueries,
-- 
cgit v1.2.3