diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml
index fcea6ad65fe8fa35a4a9023deec5819fb1adfeff..aed0a60a020e5738c7f4def50adcc444136a7f21 100644
--- a/doc/src/sgml/dml.sgml
+++ b/doc/src/sgml/dml.sgml
@@ -1,4 +1,4 @@
-<!-- $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
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index cb8f2a1e5ac2aa99943b66a6bfa9fb9703effc93..8cf0268fd9f1e63f5d11ad4d987f4bb29221b649 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1,4 +1,4 @@
-<!-- $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>
@@ -104,7 +104,7 @@ SELECT random();
produce a virtual table that provides the rows that are passed to
the select list to compute the output rows of the query.
</para>
-
+
<sect2 id="queries-from">
<title>The <literal>FROM</literal> Clause</title>
@@ -253,12 +253,12 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para>
<indexterm>
- <primary>join</primary>
- <secondary>natural</secondary>
- </indexterm>
+ <primary>join</primary>
+ <secondary>natural</secondary>
+ </indexterm>
<indexterm>
- <primary>natural join</primary>
- </indexterm>
+ <primary>natural join</primary>
+ </indexterm>
Finally, <literal>NATURAL</> is a shorthand form of
<literal>USING</>: it forms a <literal>USING</> list
consisting of exactly those column names that appear in both
@@ -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 > 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 > 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">
@@ -814,7 +828,7 @@ SELECT <replaceable>select_list</replaceable>
(3 rows)
</screen>
</para>
-
+
<para>
In the second query, we could not have written <literal>SELECT *
FROM test1 GROUP BY x</literal>, because there is no single value
@@ -1194,7 +1208,7 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
<indexterm zone="queries-order">
<primary>ORDER BY</primary>
</indexterm>
-
+
<para>
After a query has produced an output table (after the select list
has been processed) it can optionally be sorted. If sorting is not
@@ -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>
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 07dd0b0ee7453e8b6963480d2fed100450e4ff26..a481500525a49fa609fee03bab81a8636bdf6b64 100644
--- 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">
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 042ec818f0717c623c5beb3eac5ea77eff30bb10..6eab13705fbc8276bc5f4763cd53e1f4aa3336ac 100644
--- 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>
diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml
index 05cc38cf332b868b7f7df631f3f0635056f54902..36348c8ad49fc69fae5a87b0c3920ff6c2974023 100644
--- 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>
diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml
index 6bccbb681f2721f9622c3f343fc920409c79a43d..f6e75ce3e2a0ef9bebaaa2e3bb03bfec0480ef59 100644
--- 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>
diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml
index 475db0d02279873463adde0dbdc946d443f0b9d0..30f924268c56d35ee336a826d2ab554b9d1bccb1 100644
--- 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>
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 2853f6c79f97f7975139989266a7906ce678b804..b232fb578f7227eef373728a797fc0205416f322 100644
--- 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>
diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index 82b3260668c30ca134cf28198dba1218957b2eec..140ec7745f2c2cf5b5542524d9407bb2a84c285f 100644
--- 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>
diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml
index e916fee1d2d4ba6db3ae99b1bb22b912a9bb3c5c..b4d9ab64dc22d05b5afd6cc2f9ffba461af7ea82 100644
--- 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>
diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index c73e0a1db208a3160ed2ff7fbad070320bce4c3e..282a7872ad91218b9bc0409a93dc17a95c241d77 100644
--- 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>
diff --git a/doc/src/sgml/ref/values.sgml b/doc/src/sgml/ref/values.sgml
new file mode 100644
index 0000000000000000000000000000000000000000..9af66c387db6c884b886cc380b3147a3864d51f9
--- /dev/null
+++ 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 >= 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>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index e90c45d16232c35c44bad285bfadfb388317e85b..64330928c4e677bb9ff32f22cc466984f1c7f458 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,4 +1,4 @@
-<!-- $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>
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 1e9a407ac6e64009634b6502ba3fab80b698abcc..f4c521025d9daec9377a2618364c4a22c7a44f94 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -1,4 +1,4 @@
-<!-- $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>