<!--
doc/src/sgml/ref/delete.sgml
PostgreSQL documentation
-->

<refentry id="sql-delete">
 <indexterm zone="sql-delete">
  <primary>DELETE</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>DELETE</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>DELETE</refname>
  <refpurpose>delete rows of a table</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
    [ USING <replaceable class="parameter">from_item</replaceable> [, ...] ]
    [ WHERE <replaceable class="parameter">condition</replaceable> | WHERE CURRENT OF <replaceable class="parameter">cursor_name</replaceable> ]
    [ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
                { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>DELETE</command> deletes rows that satisfy the
   <literal>WHERE</literal> clause from the specified table.  If the
   <literal>WHERE</literal> clause is absent, the effect is to delete
   all rows in the table.  The result is a valid, but empty table.
  </para>

   <tip>
    <para>
     <link linkend="sql-truncate"><command>TRUNCATE</command></link> provides a
     faster mechanism to remove all rows from a table.
    </para>
   </tip>

  <para>
   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 <literal>USING</literal> clause.
   Which technique is more appropriate depends on the specific
   circumstances.
  </para>

  <para>
   The optional <literal>RETURNING</literal> clause causes <command>DELETE</command>
   to compute and return value(s) based on each row actually deleted.
   Any expression using the table's columns, and/or columns of other
   tables mentioned in <literal>USING</literal>, can be computed.
   The syntax of the <literal>RETURNING</literal> list is identical to that of the
   output list of <command>SELECT</command>.
  </para>

  <para>
   You must have the <literal>DELETE</literal> privilege on the table
   to delete from it, as well as the <literal>SELECT</literal>
   privilege for any table in the <literal>USING</literal> clause or
   whose values are read in the <replaceable
   class="parameter">condition</replaceable>.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="parameter">with_query</replaceable></term>
    <listitem>
     <para>
      The <literal>WITH</literal> clause allows you to specify one or more
      subqueries that can be referenced by name in the <command>DELETE</command>
      query. See <xref linkend="queries-with"/> and <xref linkend="sql-select"/>
      for details.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">table_name</replaceable></term>
    <listitem>
     <para>
      The name (optionally schema-qualified) of the table to delete rows
      from.  If <literal>ONLY</literal> is specified before the table name,
      matching rows are deleted from the named table only.  If
      <literal>ONLY</literal> is not specified, matching rows are also deleted
      from any tables inheriting from the named table.  Optionally,
      <literal>*</literal> can be specified after the table name to explicitly
      indicate that descendant tables are included.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">alias</replaceable></term>