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

   1 '\" t
   2 .\"     Title: DELETE
   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 "DELETE" "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 DELETE \- delete rows of a table
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 [ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ]
  36 DELETE FROM [ ONLY ] \fItable_name\fR [ * ] [ [ AS ] \fIalias\fR ]
  37     [ USING \fIfrom_item\fR [, \&.\&.\&.] ]
  38     [ WHERE \fIcondition\fR | WHERE CURRENT OF \fIcursor_name\fR ]
  39     [ RETURNING [ WITH ( { OLD | NEW } AS \fIoutput_alias\fR [, \&.\&.\&.] ) ]
  40                 { * | \fIoutput_expression\fR [ [ AS ] \fIoutput_name\fR ] } [, \&.\&.\&.] ]
  41 .fi
  42 .SH "DESCRIPTION"
  43 .PP
  44 \fBDELETE\fR
  45 deletes rows that satisfy the
  46 WHERE
  47 clause from the specified table\&. If the
  48 WHERE
  49 clause is absent, the effect is to delete all rows in the table\&. The result is a valid, but empty table\&.
  50 .if n \{\
  51 .sp
  52 .\}
  53 .RS 4
  54 .it 1 an-trap
  55 .nr an-no-space-flag 1
  56 .nr an-break-flag 1
  57 .br
  58 .ps +1
  59 \fBTip\fR
  60 .ps -1
  61 .br
  62 .PP
  63 \fBTRUNCATE\fR
  64 provides a faster mechanism to remove all rows from a table\&.
  65 .sp .5v
  66 .RE
  67 .PP
  68 There are two ways to delete rows in a table using information contained in other tables in the database: using sub\-selects, or specifying additional tables in the
  69 USING
  70 clause\&. Which technique is more appropriate depends on the specific circumstances\&.
  71 .PP
  72 The optional
  73 RETURNING
  74 clause causes
  75 \fBDELETE\fR
  76 to compute and return value(s) based on each row actually deleted\&. Any expression using the table\*(Aqs columns, and/or columns of other tables mentioned in
  77 USING, can be computed\&. The syntax of the
  78 RETURNING
  79 list is identical to that of the output list of
  80 \fBSELECT\fR\&.
  81 .PP
  82 You must have the
  83 DELETE
  84 privilege on the table to delete from it, as well as the
  85 SELECT
  86 privilege for any table in the
  87 USING
  88 clause or whose values are read in the
  89 \fIcondition\fR\&.
  90 .SH "PARAMETERS"
  91 .PP
  92 \fIwith_query\fR
  93 .RS 4
  94 The
  95 WITH
  96 clause allows you to specify one or more subqueries that can be referenced by name in the
  97 \fBDELETE\fR
  98 query\&. See
  99 Section\ \&7.8
 100 and
 101 \fBSELECT\fR(7)
 102 for details\&.
 103 .RE
 104 .PP
 105 \fItable_name\fR
 106 .RS 4
 107 The name (optionally schema\-qualified) of the table to delete rows from\&. If
 108 ONLY
 109 is specified before the table name, matching rows are deleted from the named table only\&. If
 110 ONLY
 111 is not specified, matching rows are also deleted from any tables inheriting from the named table\&. Optionally,
 112 *
 113 can be specified after the table name to explicitly indicate that descendant tables are included\&.
 114 .RE
 115 .PP
 116 \fIalias\fR
 117 .RS 4
 118 A substitute name for the target table\&. When an alias is provided, it completely hides the actual name of the table\&. For example, given
 119 DELETE FROM foo AS f, the remainder of the
 120 \fBDELETE\fR
 121 statement must refer to this table as
 122 f
 123 not
 124 foo\&.
 125 .RE
 126 .PP
 127 \fIfrom_item\fR
 128 .RS 4
 129 A table expression allowing columns from other tables to appear in the
 130 WHERE
 131 condition\&. This uses the same syntax as the
 132 FROM
 133 clause of a
 134 \fBSELECT\fR
 135 statement; for example, an alias for the table name can be specified\&. Do not repeat the target table as a
 136 \fIfrom_item\fR
 137 unless you wish to set up a self\-join (in which case it must appear with an alias in the
 138 \fIfrom_item\fR)\&.
 139 .RE
 140 .PP
 141 \fIcondition\fR
 142 .RS 4
 143 An expression that returns a value of type
 144 boolean\&. Only rows for which this expression returns
 145 true
 146 will be deleted\&.
 147 .RE
 148 .PP
 149 \fIcursor_name\fR
 150 .RS 4
 151 The name of the cursor to use in a
 152 WHERE CURRENT OF
 153 condition\&. The row to be deleted is the one most recently fetched from this cursor\&. The cursor must be a non\-grouping query on the
 154 \fBDELETE\fR\*(Aqs target table\&. Note that
 155 WHERE CURRENT OF
 156 cannot be specified together with a Boolean condition\&. See
 157 \fBDECLARE\fR(7)
 158 for more information about using cursors with
 159 WHERE CURRENT OF\&.
 160 .RE
 161 .PP
 162 \fIoutput_alias\fR
 163 .RS 4
 164 An optional substitute name for
 165 OLD
 166 or
 167 NEW
 168 rows in the
 169 RETURNING
 170 list\&.
 171 .sp
 172 By default, old values from the target table can be returned by writing
 173 OLD\&.\fIcolumn_name\fR
 174 or
 175 OLD\&.*, and new values can be returned by writing
 176 NEW\&.\fIcolumn_name\fR
 177 or
 178 NEW\&.*\&. When an alias is provided, these names are hidden and the old or new rows must be referred to using the alias\&. For example
 179 RETURNING WITH (OLD AS o, NEW AS n) o\&.*, n\&.*\&.
 180 .RE
 181 .PP
 182 \fIoutput_expression\fR
 183 .RS 4
 184 An expression to be computed and returned by the
 185 \fBDELETE\fR
 186 command after each row is deleted\&. The expression can use any column names of the table named by
 187 \fItable_name\fR
 188 or table(s) listed in
 189 USING\&. Write
 190 *
 191 to return all columns\&.
 192 .sp
 193 A column name or
 194 *
 195 may be qualified using
 196 OLD
 197 or
 198 NEW, or the corresponding
 199 \fIoutput_alias\fR
 200 for
 201 OLD
 202 or
 203 NEW, to cause old or new values to be returned\&. An unqualified column name, or
 204 *, or a column name or
 205 *
 206 qualified using the target table name or alias will return old values\&.
 207 .sp
 208 For a simple
 209 \fBDELETE\fR, all new values will be
 210 NULL\&. However, if an
 211 ON DELETE
 212 rule causes an
 213 \fBINSERT\fR
 214 or
 215 \fBUPDATE\fR
 216 to be executed instead, the new values may be non\-NULL\&.
 217 .RE
 218 .PP
 219 \fIoutput_name\fR
 220 .RS 4
 221 A name to use for a returned column\&.
 222 .RE
 223 .SH "OUTPUTS"
 224 .PP
 225 On successful completion, a
 226 \fBDELETE\fR
 227 command returns a command tag of the form
 228 .sp
 229 .if n \{\
 230 .RS 4
 231 .\}
 232 .nf
 233 DELETE \fIcount\fR
 234 .fi
 235 .if n \{\
 236 .RE
 237 .\}
 238 .sp
 239 The
 240 \fIcount\fR
 241 is the number of rows deleted\&. Note that the number may be less than the number of rows that matched the
 242 \fIcondition\fR
 243 when deletes were suppressed by a
 244 BEFORE DELETE
 245 trigger\&. If
 246 \fIcount\fR
 247 is 0, no rows were deleted by the query (this is not considered an error)\&.
 248 .PP
 249 If the
 250 \fBDELETE\fR
 251 command contains a
 252 RETURNING
 253 clause, the result will be similar to that of a
 254 \fBSELECT\fR
 255 statement containing the columns and values defined in the
 256 RETURNING
 257 list, computed over the row(s) deleted by the command\&.
 258 .SH "NOTES"
 259 .PP
 260 PostgreSQL
 261 lets you reference columns of other tables in the
 262 WHERE
 263 condition by specifying the other tables in the
 264 USING
 265 clause\&. For example, to delete all films produced by a given producer, one can do:
 266 .sp
 267 .if n \{\
 268 .RS 4
 269 .\}
 270 .nf
 271 DELETE FROM films USING producers
 272   WHERE producer_id = producers\&.id AND producers\&.name = \*(Aqfoo\*(Aq;
 273 .fi
 274 .if n \{\
 275 .RE
 276 .\}
 277 .sp
 278 What is essentially happening here is a join between
 279 films
 280 and
 281 producers, with all successfully joined
 282 films
 283 rows being marked for deletion\&. This syntax is not standard\&. A more standard way to do it is:
 284 .sp
 285 .if n \{\
 286 .RS 4
 287 .\}
 288 .nf
 289 DELETE FROM films
 290   WHERE producer_id IN (SELECT id FROM producers WHERE name = \*(Aqfoo\*(Aq);
 291 .fi
 292 .if n \{\
 293 .RE
 294 .\}
 295 .sp
 296 In some cases the join style is easier to write or faster to execute than the sub\-select style\&.
 297 .SH "EXAMPLES"
 298 .PP
 299 Delete all films but musicals:
 300 .sp
 301 .if n \{\
 302 .RS 4
 303 .\}
 304 .nf
 305 DELETE FROM films WHERE kind <> \*(AqMusical\*(Aq;
 306 .fi
 307 .if n \{\
 308 .RE
 309 .\}
 310 .PP
 311 Clear the table
 312 films:
 313 .sp
 314 .if n \{\
 315 .RS 4
 316 .\}
 317 .nf
 318 DELETE FROM films;
 319 .fi
 320 .if n \{\
 321 .RE
 322 .\}
 323 .PP
 324 Delete completed tasks, returning full details of the deleted rows:
 325 .sp
 326 .if n \{\
 327 .RS 4
 328 .\}
 329 .nf
 330 DELETE FROM tasks WHERE status = \*(AqDONE\*(Aq RETURNING *;
 331 .fi
 332 .if n \{\
 333 .RE
 334 .\}
 335 .PP
 336 Delete the row of
 337 tasks
 338 on which the cursor
 339 c_tasks
 340 is currently positioned:
 341 .sp
 342 .if n \{\
 343 .RS 4
 344 .\}
 345 .nf
 346 DELETE FROM tasks WHERE CURRENT OF c_tasks;
 347 .fi
 348 .if n \{\
 349 .RE
 350 .\}
 351 .PP
 352 While there is no
 353 LIMIT
 354 clause for
 355 \fBDELETE\fR, it is possible to get a similar effect using the same method described in
 356 the documentation of \fBUPDATE\fR:
 357 .sp
 358 .if n \{\
 359 .RS 4
 360 .\}
 361 .nf
 362 WITH delete_batch AS (
 363   SELECT l\&.ctid FROM user_logs AS l
 364     WHERE l\&.status = \*(Aqarchived\*(Aq
 365     ORDER BY l\&.creation_date
 366     FOR UPDATE
 367     LIMIT 10000
 368 )
 369 DELETE FROM user_logs AS dl
 370   USING delete_batch AS del
 371   WHERE dl\&.ctid = del\&.ctid;
 372 .fi
 373 .if n \{\
 374 .RE
 375 .\}
 376 .sp
 377 .SH "COMPATIBILITY"
 378 .PP
 379 This command conforms to the
 380 SQL
 381 standard, except that the
 382 USING
 383 and
 384 RETURNING
 385 clauses are
 386 PostgreSQL
 387 extensions, as is the ability to use
 388 WITH
 389 with
 390 \fBDELETE\fR\&.
 391 .SH "SEE ALSO"
 392 \fBTRUNCATE\fR(7)