mirror of
https://github.com/postgres/postgres.git
synced 2025-07-28 23:42:10 +03:00
Documentation for VALUES lists. Joe Conway and Tom Lane
This commit is contained in:
Tom Lane
@ -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
|
||||
|
||||
@ -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>
|
||||
@ -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">
|
||||
@ -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>
|
||||
|
||||
@ -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">
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
244
doc/src/sgml/ref/values.sgml
Normal file
244
doc/src/sgml/ref/values.sgml
Normal file
@ -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>
|
||||
@ -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>
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
Reference in New Issue
Block a user