Documentation for VALUES lists. Joe Conway and Tom Lane

2025-12-15 02:22:24 +03:00 · 2006-09-18 19:54:01 +00:00
parent 5f04ce3126
commit b5b1eb80b7
14 changed files with 414 additions and 61 deletions
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
 <!--
-$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">
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/create_table_as.sgml
+++ b/doc/src/sgml/ref/create_table_as.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
 
--- a/doc/src/sgml/ref/create_view.sgml
+++ b/doc/src/sgml/ref/create_view.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/declare.sgml
+++ b/doc/src/sgml/ref/declare.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/prepare.sgml
+++ b/doc/src/sgml/ref/prepare.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
 <!--
-$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>
--- a/doc/src/sgml/ref/values.sgml
+++ b/doc/src/sgml/ref/values.sgml
@@ -0,0 +1,244 @@
+<!--
+$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>