begriffs open source - ai-pg/blob - full-docs/man7/VALUES.7

   1 '\" t
   2 .\"     Title: VALUES
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "VALUES" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 VALUES \- compute a set of rows
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 VALUES ( \fIexpression\fR [, \&.\&.\&.] ) [, \&.\&.\&.]
  36     [ ORDER BY \fIsort_expression\fR [ ASC | DESC | USING \fIoperator\fR ] [, \&.\&.\&.] ]
  37     [ LIMIT { \fIcount\fR | ALL } ]
  38     [ OFFSET \fIstart\fR [ ROW | ROWS ] ]
  39     [ FETCH { FIRST | NEXT } [ \fIcount\fR ] { ROW | ROWS } ONLY ]
  40 .fi
  41 .SH "DESCRIPTION"
  42 .PP
  43 \fBVALUES\fR
  44 computes a row value or set of row values specified by value expressions\&. It is most commonly used to generate a
  45 \(lqconstant table\(rq
  46 within a larger command, but it can be used on its own\&.
  47 .PP
  48 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
  49 UNION
  50 (see
  51 Section\ \&10.5)\&.
  52 .PP
  53 Within larger commands,
  54 \fBVALUES\fR
  55 is syntactically allowed anywhere that
  56 \fBSELECT\fR
  57 is\&. Because it is treated like a
  58 \fBSELECT\fR
  59 by the grammar, it is possible to use the
  60 ORDER BY,
  61 LIMIT
  62 (or equivalently
  63 FETCH FIRST), and
  64 OFFSET
  65 clauses with a
  66 \fBVALUES\fR
  67 command\&.
  68 .SH "PARAMETERS"
  69 .PP
  70 \fIexpression\fR
  71 .RS 4
  72 A constant or expression to compute and insert at the indicated place in the resulting table (set of rows)\&. In a
  73 \fBVALUES\fR
  74 list appearing at the top level of an
  75 \fBINSERT\fR, an
  76 \fIexpression\fR
  77 can be replaced by
  78 DEFAULT
  79 to indicate that the destination column\*(Aqs default value should be inserted\&.
  80 DEFAULT
  81 cannot be used when
  82 \fBVALUES\fR
  83 appears in other contexts\&.
  84 .RE
  85 .PP
  86 \fIsort_expression\fR
  87 .RS 4
  88 An expression or integer constant indicating how to sort the result rows\&. This expression can refer to the columns of the
  89 \fBVALUES\fR
  90 result as
  91 column1,
  92 column2, etc\&. For more details see
  93 ORDER BY Clause
  94 in the
  95 \fBSELECT\fR(7)
  96 documentation\&.
  97 .RE
  98 .PP
  99 \fIoperator\fR
 100 .RS 4
 101 A sorting operator\&. For details see
 102 ORDER BY Clause
 103 in the
 104 \fBSELECT\fR(7)
 105 documentation\&.
 106 .RE
 107 .PP
 108 \fIcount\fR
 109 .RS 4
 110 The maximum number of rows to return\&. For details see
 111 LIMIT Clause
 112 in the
 113 \fBSELECT\fR(7)
 114 documentation\&.
 115 .RE
 116 .PP
 117 \fIstart\fR
 118 .RS 4
 119 The number of rows to skip before starting to return rows\&. For details see
 120 LIMIT Clause
 121 in the
 122 \fBSELECT\fR(7)
 123 documentation\&.
 124 .RE
 125 .SH "NOTES"
 126 .PP
 127 \fBVALUES\fR
 128 lists with very large numbers of rows should be avoided, as you might encounter out\-of\-memory failures or poor performance\&.
 129 \fBVALUES\fR
 130 appearing within
 131 \fBINSERT\fR
 132 is a special case (because the desired column types are known from the
 133 \fBINSERT\fR\*(Aqs target table, and need not be inferred by scanning the
 134 \fBVALUES\fR
 135 list), so it can handle larger lists than are practical in other contexts\&.
 136 .SH "EXAMPLES"
 137 .PP
 138 A bare
 139 \fBVALUES\fR
 140 command:
 141 .sp
 142 .if n \{\
 143 .RS 4
 144 .\}
 145 .nf
 146 VALUES (1, \*(Aqone\*(Aq), (2, \*(Aqtwo\*(Aq), (3, \*(Aqthree\*(Aq);
 147 .fi
 148 .if n \{\
 149 .RE
 150 .\}
 151 .sp
 152 This will return a table of two columns and three rows\&. It\*(Aqs effectively equivalent to:
 153 .sp
 154 .if n \{\
 155 .RS 4
 156 .\}
 157 .nf
 158 SELECT 1 AS column1, \*(Aqone\*(Aq AS column2
 159 UNION ALL
 160 SELECT 2, \*(Aqtwo\*(Aq
 161 UNION ALL
 162 SELECT 3, \*(Aqthree\*(Aq;
 163 .fi
 164 .if n \{\
 165 .RE
 166 .\}
 167 .PP
 168 More usually,
 169 \fBVALUES\fR
 170 is used within a larger SQL command\&. The most common use is in
 171 \fBINSERT\fR:
 172 .sp
 173 .if n \{\
 174 .RS 4
 175 .\}
 176 .nf
 177 INSERT INTO films (code, title, did, date_prod, kind)
 178     VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, \*(Aq1961\-06\-16\*(Aq, \*(AqDrama\*(Aq);
 179 .fi
 180 .if n \{\
 181 .RE
 182 .\}
 183 .PP
 184 In the context of
 185 \fBINSERT\fR, entries of a
 186 \fBVALUES\fR
 187 list can be
 188 DEFAULT
 189 to indicate that the column default should be used here instead of specifying a value:
 190 .sp
 191 .if n \{\
 192 .RS 4
 193 .\}
 194 .nf
 195 INSERT INTO films VALUES
 196     (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, DEFAULT, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq),
 197     (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, DEFAULT, \*(AqDrama\*(Aq, DEFAULT);
 198 .fi
 199 .if n \{\
 200 .RE
 201 .\}
 202 .PP
 203 \fBVALUES\fR
 204 can also be used where a sub\-\fBSELECT\fR
 205 might be written, for example in a
 206 FROM
 207 clause:
 208 .sp
 209 .if n \{\
 210 .RS 4
 211 .\}
 212 .nf
 213 SELECT f\&.*
 214   FROM films f, (VALUES(\*(AqMGM\*(Aq, \*(AqHorror\*(Aq), (\*(AqUA\*(Aq, \*(AqSci\-Fi\*(Aq)) AS t (studio, kind)
 215   WHERE f\&.studio = t\&.studio AND f\&.kind = t\&.kind;
 216
 217 UPDATE employees SET salary = salary * v\&.increase
 218   FROM (VALUES(1, 200000, 1\&.2), (2, 400000, 1\&.4)) AS v (depno, target, increase)
 219   WHERE employees\&.depno = v\&.depno AND employees\&.sales >= v\&.target;
 220 .fi
 221 .if n \{\
 222 .RE
 223 .\}
 224 .sp
 225 Note that an
 226 AS
 227 clause is required when
 228 \fBVALUES\fR
 229 is used in a
 230 FROM
 231 clause, just as is true for
 232 \fBSELECT\fR\&. It is not required that the
 233 AS
 234 clause specify names for all the columns, but it\*(Aqs good practice to do so\&. (The default column names for
 235 \fBVALUES\fR
 236 are
 237 column1,
 238 column2, etc\&. in
 239 PostgreSQL, but these names might be different in other database systems\&.)
 240 .PP
 241 When
 242 \fBVALUES\fR
 243 is used in
 244 \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:
 245 .sp
 246 .if n \{\
 247 .RS 4
 248 .\}
 249 .nf
 250 SELECT * FROM machines
 251 WHERE ip_address IN (VALUES(\*(Aq192\&.168\&.0\&.1\*(Aq::inet), (\*(Aq192\&.168\&.0\&.10\*(Aq), (\*(Aq192\&.168\&.1\&.43\*(Aq));
 252 .fi
 253 .if n \{\
 254 .RE
 255 .\}
 256 .if n \{\
 257 .sp
 258 .\}
 259 .RS 4
 260 .it 1 an-trap
 261 .nr an-no-space-flag 1
 262 .nr an-break-flag 1
 263 .br
 264 .ps +1
 265 \fBTip\fR
 266 .ps -1
 267 .br
 268 .PP
 269 For simple
 270 IN
 271 tests, it\*(Aqs better to rely on the
 272 list\-of\-scalars
 273 form of
 274 IN
 275 than to write a
 276 \fBVALUES\fR
 277 query as shown above\&. The list of scalars method requires less writing and is often more efficient\&.
 278 .sp .5v
 279 .RE
 280 .SH "COMPATIBILITY"
 281 .PP
 282 \fBVALUES\fR
 283 conforms to the SQL standard\&.
 284 LIMIT
 285 and
 286 OFFSET
 287 are
 288 PostgreSQL
 289 extensions; see also under
 290 \fBSELECT\fR(7)\&.
 291 .SH "SEE ALSO"
 292 \fBINSERT\fR(7), \fBSELECT\fR(7)