Skip to content
Snippets Groups Projects
Commit b5b1eb80 authored by Tom Lane's avatar Tom Lane
Browse files

Documentation for VALUES lists. Joe Conway and Tom Lane

parent 5f04ce31
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 414 additions and 61 deletions
doc/src/sgml/dml.sgml
+ 11
− 1
View file @ b5b1eb80
<!-- $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
+ 102
− 18
View file @ b5b1eb80
<!-- $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 &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">
......@@ -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>
doc/src/sgml/ref/allfiles.sgml
+ 2
− 1
View file @ b5b1eb80
<!--
$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
+ 4
− 2
View file @ b5b1eb80
<!--
$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
+ 8
− 10
View file @ b5b1eb80
<!--
$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
+ 4
− 8
View file @ b5b1eb80
<!--
$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
+ 4
− 5
View file @ b5b1eb80
<!--
$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
+ 3
− 3
View file @ b5b1eb80
<!--
$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
+ 16
− 5
View file @ b5b1eb80
<!--
$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
+ 2
− 2
View file @ b5b1eb80
<!--
$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
+ 4
− 2
View file @ b5b1eb80
<!--
$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 0 → 100644
+ 244
− 0
View file @ b5b1eb80
<!--
$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
+ 2
− 1
View file @ b5b1eb80
<!-- $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
+ 8
− 3
View file @ b5b1eb80
<!-- $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>
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment