Documentation for VALUES lists. Joe Conway and Tom Lane

doc/src/sgml/dml.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.13 2006/02/18 23:14:45 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.14 2006/09/18 19:54:01 tgl Exp $ -->
 
 <chapter id="dml">
  <title>Data Manipulation</title>
@@ -93,6 +93,16 @@ INSERT INTO products DEFAULT VALUES;
 </programlisting>
   </para>
 
+  <para>
+   You can insert multiple rows in a single command:
+<programlisting>
+INSERT INTO products (product_no, name, price) VALUES
+    (1, 'Cheese', 9.99),
+    (2, 'Bread', 1.99),
+    (3, 'Milk', 2.99);
+</programlisting>
+  </para>
+
   <tip>
    <para>
     When inserting a lot of data at the same time, considering using

doc/src/sgml/queries.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.35 2006/02/18 23:14:45 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.36 2006/09/18 19:54:01 tgl Exp $ -->
 
 <chapter id="queries">
  <title>Queries</title>
@@ -511,33 +511,36 @@ SELECT * FROM some_very_long_table_name s JOIN another_fairly_long_name a ON s.i
 <programlisting>
 SELECT * FROM my_table AS m WHERE my_table.a &gt; 5;
 </programlisting>
-     is not valid SQL syntax.  What will actually happen (this is a
-     <productname>PostgreSQL</productname> extension to the standard)
-     is that an implicit table reference is added to the
+     is not valid according to the SQL standard.  In
+     <productname>PostgreSQL</productname> this will draw an error if the
+     <xref linkend="guc-add-missing-from"> configuration variable is
+     <literal>off</>.  If it is <literal>on</>, an implicit table reference
+     will be added to the
      <literal>FROM</literal> clause, so the query is processed as if
      it were written as
 <programlisting>
 SELECT * FROM my_table AS m, my_table AS my_table WHERE my_table.a &gt; 5;
 </programlisting>
-     which will result in a cross join, which is usually not what you
-     want.
+     That will result in a cross join, which is usually not what you want.
     </para>
 
     <para>
      Table aliases are mainly for notational convenience, but it is
      necessary to use them when joining a table to itself, e.g.,
 <programlisting>
-SELECT * FROM my_table AS a CROSS JOIN my_table AS b ...
+SELECT * FROM people AS mother JOIN people AS child ON mother.id = child.mother_id;
 </programlisting>
      Additionally, an alias is required if the table reference is a
      subquery (see <xref linkend="queries-subqueries">).
     </para>
 
     <para>
-     Parentheses are used to resolve ambiguities.  The following
-     statement will assign the alias <literal>b</literal> to the
-     result of the join, unlike the previous example:
+     Parentheses are used to resolve ambiguities.  In the following example,
+     the first statement assigns the alias <literal>b</literal> to the second
+     instance of <literal>my_table</>, but the second statement assigns the
+     alias to the result of the join:
 <programlisting>
+SELECT * FROM my_table AS a CROSS JOIN my_table AS b ...
 SELECT * FROM (my_table AS a CROSS JOIN my_table) AS b ...
 </programlisting>
     </para>
@@ -592,6 +595,17 @@ FROM (SELECT * FROM table1) AS alias_name
      reduced to a plain join, arise when the subquery involves
      grouping or aggregation.
     </para>
+
+    <para>
+     A subquery can also be a <command>VALUES</> list:
+<programlisting>
+FROM (VALUES ('anne', 'smith'), ('bob', 'jones'), ('joe', 'blow'))
+     AS names(first, last)
+</programlisting>
+     Again, a table alias is required.  Assigning alias names to the columns
+     of the <command>VALUES</> list is optional, but is good practice.
+     For more information see <xref linkend="queries-values">.
+    </para>
    </sect3>
 
    <sect3 id="queries-tablefunctions">
@@ -1335,4 +1349,74 @@ SELECT <replaceable>select_list</replaceable>
   </para>
  </sect1>
 
+
+ <sect1 id="queries-values">
+  <title><literal>VALUES</literal> Lists</title>
+
+  <indexterm zone="queries-values">
+   <primary>VALUES</primary>
+  </indexterm>
+
+  <para>
+   <literal>VALUES</> provides a way to generate a <quote>constant table</>
+   that can be used in a query without having to actually create and populate
+   a table on-disk.  The syntax is
+<synopsis>
+VALUES ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) [, ...]
+</synopsis>
+   Each parenthesized list of expressions generates a row in the table.
+   The lists must all have the same number of elements (i.e., the number
+   of columns in the table), and corresponding entries in each list must
+   have compatible datatypes.  The actual datatype assigned to each column
+   of the result is determined using the same rules as for <literal>UNION</>
+   (see <xref linkend="typeconv-union-case">).
+  </para>
+
+  <para>
+   As an example,
+
+<programlisting>
+VALUES (1, 'one'), (2, 'two'), (3, 'three');
+</programlisting>
+
+   will return a table of two columns and three rows.  It's effectively
+   equivalent to
+
+<programlisting>
+SELECT 1 AS column1, 'one' AS column2
+UNION ALL
+SELECT 2, 'two'
+UNION ALL
+SELECT 3, 'three';
+</programlisting>
+
+   By default, <productname>PostgreSQL</productname> assigns the names
+   <literal>column1</>, <literal>column2</>, etc. to the columns of a
+   <literal>VALUES</> table.  The column names are not specified by the
+   SQL standard and different database systems do it differently, so
+   it's usually better to override the default names with a table alias
+   list.
+  </para>
+
+  <para>
+   Syntactically, <literal>VALUES</> followed by expression lists is
+   treated as equivalent to
+<synopsis>
+SELECT <replaceable>select_list</replaceable> FROM <replaceable>table_expression</replaceable>
+</synopsis>
+   and can appear anywhere a <literal>SELECT</> can.  For example, you can
+   use it as an arm of a <literal>UNION</>, or attach a
+   <replaceable>sort_specification</replaceable> (<literal>ORDER BY</>,
+   <literal>LIMIT</>, and/or <literal>OFFSET</>) to it.  <literal>VALUES</>
+   is most commonly used as the data source in an <command>INSERT</> command,
+   and next most commonly as a subquery.
+  </para>
+
+  <para>
+   For more information see <xref linkend="sql-values"
+   endterm="sql-values-title">.
+  </para>
+
+ </sect1>
+
 </chapter>

doc/src/sgml/ref/allfiles.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.67 2005/11/21 12:49:30 alvherre Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.68 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 Complete list of usable sgml source files in this directory.
 -->
@@ -116,6 +116,7 @@ Complete list of usable sgml source files in this directory.
 <!entity unlisten           system "unlisten.sgml">
 <!entity update             system "update.sgml">
 <!entity vacuum             system "vacuum.sgml">
+<!entity values             system "values.sgml">
 
 <!-- applications and utilities -->
 <!entity clusterdb          system "clusterdb.sgml">

doc/src/sgml/ref/copy.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/copy.sgml,v 1.76 2006/09/16 00:30:17 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/copy.sgml,v 1.77 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -107,7 +107,9 @@ COPY { <replaceable class="parameter">tablename</replaceable> [ ( <replaceable c
     <term><replaceable class="parameter">query</replaceable></term>
     <listitem>
      <para>
-      A <command>SELECT</> query whose results are to be copied.
+      A <xref linkend="sql-select" endterm="sql-select-title"> or
+      <xref linkend="sql-values" endterm="sql-values-title"> command
+      whose results are to be copied.
       Note that parentheses are required around the query.
      </para>
     </listitem>

doc/src/sgml/ref/create_table_as.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.35 2006/09/16 00:30:17 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.36 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -34,9 +34,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
 
   <para>
    <command>CREATE TABLE AS</command> creates a table and fills it
-   with data computed by a <command>SELECT</command> command or an
-   <command>EXECUTE</command> that runs a prepared
-   <command>SELECT</command> command.  The table columns have the
+   with data computed by a <command>SELECT</command> command.
+   The table columns have the
    names and data types associated with the output columns of the
    <command>SELECT</command> (except that you can override the column
    names by giving an explicit list of new column names).
@@ -196,12 +195,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
     <term><replaceable>query</replaceable></term>
     <listitem>
      <para>
-      A query statement (that is, a <command>SELECT</command> command
-      or an <command>EXECUTE</command> command that runs a prepared
-      <command>SELECT</command> command).  Refer to <xref
-      linkend="sql-select" endterm="sql-select-title"> or <xref
-      linkend="sql-execute" endterm="sql-execute-title">,
-      respectively, for a description of the allowed syntax.
+      A <xref linkend="sql-select" endterm="sql-select-title"> or
+      <xref linkend="sql-values" endterm="sql-values-title"> command,
+      or an <xref linkend="sql-execute" endterm="sql-execute-title"> command
+      that runs a prepared <command>SELECT</> or <command>VALUES</> query.
      </para>
     </listitem>
    </varlistentry>
@@ -326,6 +323,7 @@ CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS
    <member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
    <member><xref linkend="sql-select" endterm="sql-select-title"></member>
    <member><xref linkend="sql-selectinto" endterm="sql-selectinto-title"></member>
+   <member><xref linkend="sql-values" endterm="sql-values-title"></member>
   </simplelist>
  </refsect1>
  

doc/src/sgml/ref/create_view.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_view.sgml,v 1.32 2006/09/16 00:30:17 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_view.sgml,v 1.33 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -99,13 +99,9 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] VIEW <replaceable class="PARAMETER">n
     <term><replaceable class="parameter">query</replaceable></term>
     <listitem>
      <para>
-      A query (that is, a <command>SELECT</> statement) which will
-      provide the columns and rows of the view.
-     </para>
-
-     <para>
-      Refer to <xref linkend="sql-select" endterm="sql-select-title">
-      for more information about valid queries.
+      A <xref linkend="sql-select" endterm="sql-select-title"> or
+      <xref linkend="sql-values" endterm="sql-values-title"> command
+      which will provide the columns and rows of the view.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/declare.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.38 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.39 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -157,10 +157,9 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
     <term><replaceable class="parameter">query</replaceable></term>
     <listitem>
      <para>
-      A <command>SELECT</> command that will provide the rows to be
-      returned by the cursor.  Refer to <xref linkend="sql-select"
-      endterm="sql-select-title"> for further information about valid
-      queries.
+      A <xref linkend="sql-select" endterm="sql-select-title"> or
+      <xref linkend="sql-values" endterm="sql-values-title"> command
+      which will provide the rows to be returned by the cursor.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/explain.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.37 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/explain.sgml,v 1.38 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -121,8 +121,8 @@ ROLLBACK;
     <listitem>
      <para>
       Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
-      <command>DELETE</>, <command>EXECUTE</>, or <command>DECLARE</>
-      statement, whose execution plan you wish to see.
+      <command>DELETE</>, <command>VALUES</>, <command>EXECUTE</>, or
+      <command>DECLARE</> statement, whose execution plan you wish to see.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/insert.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.32 2006/09/16 00:30:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/insert.sgml,v 1.33 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -31,8 +31,8 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
 
   <para>
    <command>INSERT</command> inserts new rows into a table.
-   One can insert rows specified by value expressions,
-   or rows computed as a result of a query.
+   One can insert one or more rows specified by value expressions,
+   or zero or more rows resulting from a query.
   </para>
 
   <para>
@@ -67,8 +67,9 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
   </para>
 
   <para>
-   You must have <literal>INSERT</literal> privilege to a table in
-   order to insert into it.  If you use the <replaceable
+   You must have <literal>INSERT</literal> privilege on a table in
+   order to insert into it, and <literal>SELECT</> privilege on it to
+   use <literal>RETURNING</>.  If you use the <replaceable
    class="PARAMETER">query</replaceable> clause to insert rows from a
    query, you also need to have <literal>SELECT</literal> privilege on
    any table used in the query.
@@ -232,6 +233,16 @@ INSERT INTO films DEFAULT VALUES;
 </programlisting>
   </para>
 
+  <para>
+   To insert multiple rows using the multi-row <command>VALUES</> syntax:
+
+<programlisting>
+INSERT INTO films (code, title, did, date_prod, kind) VALUES
+    ('B6717', 'Tampopo', 110, '1985-02-10', 'Comedy'),
+    ('HG120', 'The Dinner Game', 140, DEFAULT, 'Comedy');
+</programlisting>
+  </para>
+
   <para>
    This example inserts some rows into table
    <literal>films</literal> from a table <literal>tmp_films</literal>

doc/src/sgml/ref/prepare.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.20 2006/09/16 00:30:19 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.21 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -116,7 +116,7 @@ PREPARE <replaceable class="PARAMETER">name</replaceable> [ (<replaceable class=
     <listitem>
      <para>
       Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
-      or <command>DELETE</> statement.
+      <command>DELETE</>, or <command>VALUES</> statement.
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/select.sgml

 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.92 2006/09/16 00:30:20 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/select.sgml,v 1.93 2006/09/18 19:54:01 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -226,7 +226,9 @@ where <replaceable class="parameter">from_item</replaceable> can be one of:
         this single <command>SELECT</command> command.  Note that the
         sub-<command>SELECT</command> must be surrounded by
         parentheses, and an alias <emphasis>must</emphasis> be
-        provided for it.
+        provided for it.  A
+        <xref linkend="sql-values" endterm="sql-values-title"> command
+        can also be used here.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/values.sgml

+<!--
+$PostgreSQL: pgsql/doc/src/sgml/ref/values.sgml,v 1.1 2006/09/18 19:54:01 tgl Exp $
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-VALUES">
+ <refmeta>
+  <refentrytitle id="SQL-VALUES-TITLE">VALUES</refentrytitle>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>VALUES</refname>
+  <refpurpose>compute a set of rows</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-values">
+  <primary>VALUES</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+VALUES ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) [, ...]
+    [ ORDER BY <replaceable class="parameter">sort_expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [, ...] ]
+    [ LIMIT { <replaceable class="parameter">count</replaceable> | ALL } ]
+    [ OFFSET <replaceable class="parameter">start</replaceable> ]
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <command>VALUES</command> computes a row value or set of row values
+   specified by value expressions.  It is most commonly used to generate
+   a <quote>constant table</> within a larger command, but it can be
+   used on its own.
+  </para>
+
+  <para>
+   When more than one row is specified, all the rows must have the same
+   number of elements.  The data types of the resulting table's columns are
+   determined by combining the explicit or inferred types of the expressions
+   appearing in that column, using the same rules as for <literal>UNION</>
+   (see <xref linkend="typeconv-union-case">).
+  </para>
+
+  <para>
+   Within larger commands, <command>VALUES</> is syntactically allowed
+   anywhere that <command>SELECT</> is.  Because it is treated like a
+   <command>SELECT</> by the grammar, it is possible to use the <literal>ORDER
+   BY</>, <literal>LIMIT</>, and <literal>OFFSET</> clauses with a
+   <command>VALUES</> command.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><replaceable class="PARAMETER">expression</replaceable></term>
+    <listitem>
+     <para>
+      A constant or expression to compute and insert at the indicated place
+      in the resulting table (set of rows).  In a <command>VALUES</> list
+      appearing at the top level of an <command>INSERT</>, an
+      <replaceable class="PARAMETER">expression</replaceable> can be replaced
+      by <literal>DEFAULT</literal> to indicate that the destination column's
+      default value should be inserted.  <literal>DEFAULT</literal> cannot
+      be used when <command>VALUES</> appears in other contexts.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">sort_expression</replaceable></term>
+    <listitem>
+     <para>
+      An expression or integer constant indicating how to sort the result
+      rows.  This expression may refer to the columns of the
+      <command>VALUES</> result as <literal>column1</>, <literal>column2</>,
+      etc.  For more details see
+      <xref linkend="sql-orderby" endterm="sql-orderby-title">.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">operator</replaceable></term>
+    <listitem>
+     <para>
+      A sorting operator.  For details see
+      <xref linkend="sql-orderby" endterm="sql-orderby-title">.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">count</replaceable></term>
+    <listitem>
+     <para>
+      The maximum number of rows to return.  For details see
+      <xref linkend="sql-limit" endterm="sql-limit-title">.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">start</replaceable></term>
+    <listitem>
+     <para>
+      The number of rows to skip before starting to return rows.
+      For details see 
+      <xref linkend="sql-limit" endterm="sql-limit-title">.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   <command>VALUES</> lists with very large numbers of rows should be avoided,
+   as you may encounter out-of-memory failures or poor performance.
+   <command>VALUES</> appearing within <command>INSERT</> is a special case
+   (because the desired column types are known from the <command>INSERT</>'s
+   target table, and need not be inferred by scanning the <command>VALUES</>
+   list), so it can handle larger lists than are practical in other contexts.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   A bare <command>VALUES</> command:
+
+<programlisting>
+VALUES (1, 'one'), (2, 'two'), (3, 'three');
+</programlisting>
+
+   This will return a table of two columns and three rows.  It's effectively
+   equivalent to
+
+<programlisting>
+SELECT 1 AS column1, 'one' AS column2
+UNION ALL
+SELECT 2, 'two'
+UNION ALL
+SELECT 3, 'three';
+</programlisting>
+
+  </para>
+
+  <para>
+   More usually, <command>VALUES</> is used within a larger SQL command.
+   The most common use is in <command>INSERT</>:
+
+<programlisting>
+INSERT INTO films (code, title, did, date_prod, kind)
+    VALUES ('T_601', 'Yojimbo', 106, '1961-06-16', 'Drama');
+</programlisting>
+  </para>
+
+  <para>
+   In the context of <command>INSERT</>, entries of a <command>VALUES</> list
+   can be <literal>DEFAULT</literal> to indicate that the column default
+   should be used here instead of specifying a value:
+
+<programlisting>
+INSERT INTO films VALUES
+    ('UA502', 'Bananas', 105, DEFAULT, 'Comedy', '82 minutes'),
+    ('T_601', 'Yojimbo', 106, DEFAULT, 'Drama', DEFAULT);
+</programlisting>
+  </para>
+
+  <para>
+   <command>VALUES</> can also be used where a sub-<command>SELECT</> might
+   be written, for example in a <literal>FROM</> clause:
+
+<programlisting>
+SELECT f.*
+  FROM films f, (VALUES('MGM', 'Horror'), ('UA', 'Sci-Fi')) AS t (studio, kind)
+  WHERE f.studio = t.studio AND f.kind = t.kind;
+
+UPDATE employees SET salary = salary * v.increase
+  FROM (VALUES(1, 200000, 1.2), (2, 400000, 1.4)) AS v (depno, target, increase)
+  WHERE employees.depno = v.depno AND employees.sales &gt;= v.target;
+</programlisting>
+
+   Note that an <literal>AS</> clause is required when <command>VALUES</>
+   is used in a <literal>FROM</> clause, just as is true for
+   <command>SELECT</>.  It is not required that the <literal>AS</> clause
+   specify names for all the columns, but it's good practice to do so.
+   (The default column names for <command>VALUES</> are <literal>column1</>,
+   <literal>column2</>, etc in <productname>PostgreSQL</productname>, but
+   these names might be different in other database systems.)
+  </para>
+
+  <para>
+   When <command>VALUES</> is used in <command>INSERT</>, the values are all
+   automatically coerced to the datatype of the corresponding destination
+   column.  When it's used in other contexts, it may be necessary to specify
+   the correct datatype.  If the entries are all quoted literal constants,
+   coercing the first is sufficient to determine the assumed type for all:
+
+<programlisting>
+SELECT * FROM machines
+WHERE ip_address IN (VALUES('192.168.0.1'::inet), ('192.168.0.10'), ('192.168.1.43'));
+</programlisting>
+  </para>
+
+  <tip>
+   <para>
+    For simple <literal>IN</> tests, it's better to rely on the
+    list-of-scalars form of <literal>IN</> than to write a <command>VALUES</>
+    query as shown above.  The list of scalars method requires less writing
+    and is often more efficient.
+   </para>
+  </tip>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   <command>VALUES</command> conforms to the SQL standard, except that
+   <literal>LIMIT</literal> and <literal>OFFSET</literal> are
+   <productname>PostgreSQL</productname> extensions.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-insert" endterm="sql-insert-title"></member>
+   <member><xref linkend="sql-select" endterm="sql-select-title"></member>
+  </simplelist>
+ </refsect1>
+</refentry>

doc/src/sgml/reference.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.59 2006/09/16 00:30:15 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.60 2006/09/18 19:54:01 tgl Exp $ -->
 
 <part id="reference">
  <title>Reference</title>
@@ -144,6 +144,7 @@
    &unlisten;
    &update;
    &vacuum;
+   &values;
 
  </reference>
 

doc/src/sgml/typeconv.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.47 2006/09/16 00:30:16 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.48 2006/09/18 19:54:01 tgl Exp $ -->
 
 <chapter Id="typeconv">
 <title>Type Conversion</title>
@@ -798,6 +798,11 @@ padding spaces.
  <secondary>determination of result type</secondary>
 </indexterm>
 
+<indexterm zone="typeconv-union-case">
+ <primary>VALUES</primary>
+ <secondary>determination of result type</secondary>
+</indexterm>
+
 <indexterm zone="typeconv-union-case">
  <primary>GREATEST</primary>
  <secondary>determination of result type</secondary>
@@ -814,8 +819,8 @@ types to become a single result set.  The resolution algorithm is
 applied separately to each output column of a union query.  The
 <literal>INTERSECT</> and <literal>EXCEPT</> constructs resolve
 dissimilar types in the same way as <literal>UNION</>.  The
-<literal>CASE</>, <literal>ARRAY</>, <function>GREATEST</> and
-<function>LEAST</> constructs use the identical
+<literal>CASE</>, <literal>ARRAY</>, <literal>VALUES</>,
+<function>GREATEST</> and <function>LEAST</> constructs use the identical
 algorithm to match up their component expressions and select a result
 data type.
 </para>