mirror of https://github.com/postgres/postgres
Tom Lane
19 years ago
parent
5f04ce3126
commit
b5b1eb80b7
@ -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> |
||||
Loading…
Reference in new issue