begriffs open source - ai-pg/blob - full-docs/txt/sql-delete.txt

   1
   2 DELETE
   3
   4    DELETE — delete rows of a table
   5
   6 Synopsis
   7
   8 [ WITH [ RECURSIVE ] with_query [, ...] ]
   9 DELETE FROM [ ONLY ] table_name [ * ] [ [ AS ] alias ]
  10     [ USING from_item [, ...] ]
  11     [ WHERE condition | WHERE CURRENT OF cursor_name ]
  12     [ RETURNING [ WITH ( { OLD | NEW } AS output_alias [, ...] ) ]
  13                 { * | output_expression [ [ AS ] output_name ] } [, ...] ]
  14
  15 Description
  16
  17    DELETE deletes rows that satisfy the WHERE clause from the specified
  18    table. If the WHERE clause is absent, the effect is to delete all rows
  19    in the table. The result is a valid, but empty table.
  20
  21 Tip
  22
  23    TRUNCATE provides a faster mechanism to remove all rows from a table.
  24
  25    There are two ways to delete rows in a table using information
  26    contained in other tables in the database: using sub-selects, or
  27    specifying additional tables in the USING clause. Which technique is
  28    more appropriate depends on the specific circumstances.
  29
  30    The optional RETURNING clause causes DELETE to compute and return
  31    value(s) based on each row actually deleted. Any expression using the
  32    table's columns, and/or columns of other tables mentioned in USING, can
  33    be computed. The syntax of the RETURNING list is identical to that of
  34    the output list of SELECT.
  35
  36    You must have the DELETE privilege on the table to delete from it, as
  37    well as the SELECT privilege for any table in the USING clause or whose
  38    values are read in the condition.
  39
  40 Parameters
  41
  42    with_query
  43           The WITH clause allows you to specify one or more subqueries
  44           that can be referenced by name in the DELETE query. See
  45           Section 7.8 and SELECT for details.
  46
  47    table_name
  48           The name (optionally schema-qualified) of the table to delete
  49           rows from. If ONLY is specified before the table name, matching
  50           rows are deleted from the named table only. If ONLY is not
  51           specified, matching rows are also deleted from any tables
  52           inheriting from the named table. Optionally, * can be specified
  53           after the table name to explicitly indicate that descendant
  54           tables are included.
  55
  56    alias
  57           A substitute name for the target table. When an alias is
  58           provided, it completely hides the actual name of the table. For
  59           example, given DELETE FROM foo AS f, the remainder of the DELETE
  60           statement must refer to this table as f not foo.
  61
  62    from_item
  63           A table expression allowing columns from other tables to appear
  64           in the WHERE condition. This uses the same syntax as the FROM
  65           clause of a SELECT statement; for example, an alias for the
  66           table name can be specified. Do not repeat the target table as a
  67           from_item unless you wish to set up a self-join (in which case
  68           it must appear with an alias in the from_item).
  69
  70    condition
  71           An expression that returns a value of type boolean. Only rows
  72           for which this expression returns true will be deleted.
  73
  74    cursor_name
  75           The name of the cursor to use in a WHERE CURRENT OF condition.
  76           The row to be deleted is the one most recently fetched from this
  77           cursor. The cursor must be a non-grouping query on the DELETE's
  78           target table. Note that WHERE CURRENT OF cannot be specified
  79           together with a Boolean condition. See DECLARE for more
  80           information about using cursors with WHERE CURRENT OF.
  81
  82    output_alias
  83           An optional substitute name for OLD or NEW rows in the RETURNING
  84           list.
  85
  86           By default, old values from the target table can be returned by
  87           writing OLD.column_name or OLD.*, and new values can be returned
  88           by writing NEW.column_name or NEW.*. When an alias is provided,
  89           these names are hidden and the old or new rows must be referred
  90           to using the alias. For example RETURNING WITH (OLD AS o, NEW AS
  91           n) o.*, n.*.
  92
  93    output_expression
  94           An expression to be computed and returned by the DELETE command
  95           after each row is deleted. The expression can use any column
  96           names of the table named by table_name or table(s) listed in
  97           USING. Write * to return all columns.
  98
  99           A column name or * may be qualified using OLD or NEW, or the
 100           corresponding output_alias for OLD or NEW, to cause old or new
 101           values to be returned. An unqualified column name, or *, or a
 102           column name or * qualified using the target table name or alias
 103           will return old values.
 104
 105           For a simple DELETE, all new values will be NULL. However, if an
 106           ON DELETE rule causes an INSERT or UPDATE to be executed
 107           instead, the new values may be non-NULL.
 108
 109    output_name
 110           A name to use for a returned column.
 111
 112 Outputs
 113
 114    On successful completion, a DELETE command returns a command tag of the
 115    form
 116 DELETE count
 117
 118    The count is the number of rows deleted. Note that the number may be
 119    less than the number of rows that matched the condition when deletes
 120    were suppressed by a BEFORE DELETE trigger. If count is 0, no rows were
 121    deleted by the query (this is not considered an error).
 122
 123    If the DELETE command contains a RETURNING clause, the result will be
 124    similar to that of a SELECT statement containing the columns and values
 125    defined in the RETURNING list, computed over the row(s) deleted by the
 126    command.
 127
 128 Notes
 129
 130    PostgreSQL lets you reference columns of other tables in the WHERE
 131    condition by specifying the other tables in the USING clause. For
 132    example, to delete all films produced by a given producer, one can do:
 133 DELETE FROM films USING producers
 134   WHERE producer_id = producers.id AND producers.name = 'foo';
 135
 136    What is essentially happening here is a join between films and
 137    producers, with all successfully joined films rows being marked for
 138    deletion. This syntax is not standard. A more standard way to do it is:
 139 DELETE FROM films
 140   WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo');
 141
 142    In some cases the join style is easier to write or faster to execute
 143    than the sub-select style.
 144
 145 Examples
 146
 147    Delete all films but musicals:
 148 DELETE FROM films WHERE kind <> 'Musical';
 149
 150    Clear the table films:
 151 DELETE FROM films;
 152
 153    Delete completed tasks, returning full details of the deleted rows:
 154 DELETE FROM tasks WHERE status = 'DONE' RETURNING *;
 155
 156    Delete the row of tasks on which the cursor c_tasks is currently
 157    positioned:
 158 DELETE FROM tasks WHERE CURRENT OF c_tasks;
 159
 160    While there is no LIMIT clause for DELETE, it is possible to get a
 161    similar effect using the same method described in the documentation of
 162    UPDATE:
 163 WITH delete_batch AS (
 164   SELECT l.ctid FROM user_logs AS l
 165     WHERE l.status = 'archived'
 166     ORDER BY l.creation_date
 167     FOR UPDATE
 168     LIMIT 10000
 169 )
 170 DELETE FROM user_logs AS dl
 171   USING delete_batch AS del
 172   WHERE dl.ctid = del.ctid;
 173
 174 Compatibility
 175
 176    This command conforms to the SQL standard, except that the USING and
 177    RETURNING clauses are PostgreSQL extensions, as is the ability to use
 178    WITH with DELETE.
 179
 180 See Also
 181
 182    TRUNCATE