1 files changed, 292 insertions, 0 deletions
diff --git a/doc/src/sgml/man7/VALUES.7 b/doc/src/sgml/man7/VALUES.7
new file mode 100644
index 0000000..1c8bd9e
--- /dev/null
+++ b/doc/src/sgml/man7/VALUES.7
@@ -0,0 +1,292 @@
+'\" t
+.\"     Title: VALUES
+.\"    Author: The PostgreSQL Global Development Group
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 2024
+.\"    Manual: PostgreSQL 16.2 Documentation
+.\"    Source: PostgreSQL 16.2
+.\"  Language: English
+.\"
+.TH "VALUES" "7" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+VALUES \- compute a set of rows
+.SH "SYNOPSIS"
+.sp
+.nf
+VALUES ( \fIexpression\fR [, \&.\&.\&.] ) [, \&.\&.\&.]
+    [ ORDER BY \fIsort_expression\fR [ ASC | DESC | USING \fIoperator\fR ] [, \&.\&.\&.] ]
+    [ LIMIT { \fIcount\fR | ALL } ]
+    [ OFFSET \fIstart\fR [ ROW | ROWS ] ]
+    [ FETCH { FIRST | NEXT } [ \fIcount\fR ] { ROW | ROWS } ONLY ]
+.fi
+.SH "DESCRIPTION"
+.PP
+\fBVALUES\fR
+computes a row value or set of row values specified by value expressions\&. It is most commonly used to generate a
+\(lqconstant table\(rq
+within a larger command, but it can be used on its own\&.
+.PP
+When more than one row is specified, all the rows must have the same number of elements\&. The data types of the resulting table\*(Aqs columns are determined by combining the explicit or inferred types of the expressions appearing in that column, using the same rules as for
+UNION
+(see
+Section\ \&10.5)\&.
+.PP
+Within larger commands,
+\fBVALUES\fR
+is syntactically allowed anywhere that
+\fBSELECT\fR
+is\&. Because it is treated like a
+\fBSELECT\fR
+by the grammar, it is possible to use the
+ORDER BY,
+LIMIT
+(or equivalently
+FETCH FIRST), and
+OFFSET
+clauses with a
+\fBVALUES\fR
+command\&.
+.SH "PARAMETERS"
+.PP
+\fIexpression\fR
+.RS 4
+A constant or expression to compute and insert at the indicated place in the resulting table (set of rows)\&. In a
+\fBVALUES\fR
+list appearing at the top level of an
+\fBINSERT\fR, an
+\fIexpression\fR
+can be replaced by
+DEFAULT
+to indicate that the destination column\*(Aqs default value should be inserted\&.
+DEFAULT
+cannot be used when
+\fBVALUES\fR
+appears in other contexts\&.
+.RE
+.PP
+\fIsort_expression\fR
+.RS 4
+An expression or integer constant indicating how to sort the result rows\&. This expression can refer to the columns of the
+\fBVALUES\fR
+result as
+column1,
+column2, etc\&. For more details see
+ORDER BY Clause
+in the
+\fBSELECT\fR(7)
+documentation\&.
+.RE
+.PP
+\fIoperator\fR
+.RS 4
+A sorting operator\&. For details see
+ORDER BY Clause
+in the
+\fBSELECT\fR(7)
+documentation\&.
+.RE
+.PP
+\fIcount\fR
+.RS 4
+The maximum number of rows to return\&. For details see
+LIMIT Clause
+in the
+\fBSELECT\fR(7)
+documentation\&.
+.RE
+.PP
+\fIstart\fR
+.RS 4
+The number of rows to skip before starting to return rows\&. For details see
+LIMIT Clause
+in the
+\fBSELECT\fR(7)
+documentation\&.
+.RE
+.SH "NOTES"
+.PP
+\fBVALUES\fR
+lists with very large numbers of rows should be avoided, as you might encounter out\-of\-memory failures or poor performance\&.
+\fBVALUES\fR
+appearing within
+\fBINSERT\fR
+is a special case (because the desired column types are known from the
+\fBINSERT\fR\*(Aqs target table, and need not be inferred by scanning the
+\fBVALUES\fR
+list), so it can handle larger lists than are practical in other contexts\&.
+.SH "EXAMPLES"
+.PP
+A bare
+\fBVALUES\fR
+command:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+VALUES (1, \*(Aqone\*(Aq), (2, \*(Aqtwo\*(Aq), (3, \*(Aqthree\*(Aq);
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+This will return a table of two columns and three rows\&. It\*(Aqs effectively equivalent to:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+SELECT 1 AS column1, \*(Aqone\*(Aq AS column2
+UNION ALL
+SELECT 2, \*(Aqtwo\*(Aq
+UNION ALL
+SELECT 3, \*(Aqthree\*(Aq;
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+More usually,
+\fBVALUES\fR
+is used within a larger SQL command\&. The most common use is in
+\fBINSERT\fR:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+INSERT INTO films (code, title, did, date_prod, kind)
+    VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, \*(Aq1961\-06\-16\*(Aq, \*(AqDrama\*(Aq);
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+In the context of
+\fBINSERT\fR, entries of a
+\fBVALUES\fR
+list can be
+DEFAULT
+to indicate that the column default should be used here instead of specifying a value:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+INSERT INTO films VALUES
+    (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, DEFAULT, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq),
+    (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, DEFAULT, \*(AqDrama\*(Aq, DEFAULT);
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBVALUES\fR
+can also be used where a sub\-\fBSELECT\fR
+might be written, for example in a
+FROM
+clause:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+SELECT f\&.*
+  FROM films f, (VALUES(\*(AqMGM\*(Aq, \*(AqHorror\*(Aq), (\*(AqUA\*(Aq, \*(AqSci\-Fi\*(Aq)) 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;
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Note that an
+AS
+clause is required when
+\fBVALUES\fR
+is used in a
+FROM
+clause, just as is true for
+\fBSELECT\fR\&. It is not required that the
+AS
+clause specify names for all the columns, but it\*(Aqs good practice to do so\&. (The default column names for
+\fBVALUES\fR
+are
+column1,
+column2, etc\&. in
+PostgreSQL, but these names might be different in other database systems\&.)
+.PP
+When
+\fBVALUES\fR
+is used in
+\fBINSERT\fR, the values are all automatically coerced to the data type of the corresponding destination column\&. When it\*(Aqs used in other contexts, it might be necessary to specify the correct data type\&. If the entries are all quoted literal constants, coercing the first is sufficient to determine the assumed type for all:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+SELECT * FROM machines
+WHERE ip_address IN (VALUES(\*(Aq192\&.168\&.0\&.1\*(Aq::inet), (\*(Aq192\&.168\&.0\&.10\*(Aq), (\*(Aq192\&.168\&.1\&.43\*(Aq));
+.fi
+.if n \{\
+.RE
+.\}
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBTip\fR
+.ps -1
+.br
+.PP
+For simple
+IN
+tests, it\*(Aqs better to rely on the
+list\-of\-scalars
+form of
+IN
+than to write a
+\fBVALUES\fR
+query as shown above\&. The list of scalars method requires less writing and is often more efficient\&.
+.sp .5v
+.RE
+.SH "COMPATIBILITY"
+.PP
+\fBVALUES\fR
+conforms to the SQL standard\&.
+LIMIT
+and
+OFFSET
+are
+PostgreSQL
+extensions; see also under
+\fBSELECT\fR(7)\&.
+.SH "SEE ALSO"
+\fBINSERT\fR(7), \fBSELECT\fR(7)