granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/delete.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-DELETE">
   7  <refmeta>
   8   <refentrytitle id="SQL-DELETE-TITLE">DELETE</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>DELETE</refname>
  14   <refpurpose>delete rows of a table</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-delete">
  18   <primary>DELETE</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
  24 </synopsis>
  25  </refsynopsisdiv>
  26
  27  <refsect1>
  28   <title>Description</title>
  29
  30   <para>
  31    <command>DELETE</command> deletes rows that satisfy the
  32    <literal>WHERE</literal> clause from the specified table.  If the
  33    <literal>WHERE</literal> clause is absent, the effect is to delete
  34    all rows in the table.  The result is a valid, but empty table.
  35   </para>
  36
  37    <tip>
  38     <para>
  39      <xref linkend="sql-truncate" endterm="sql-truncate-title"> is a
  40      <productname>PostgreSQL</productname> extension that provides a
  41      faster mechanism to remove all rows from a table.
  42     </para>
  43    </tip>
  44
  45   <para>
  46    By default, <command>DELETE</command> will delete rows in the
  47    specified table and all its subtables. If you wish to delete only
  48    from the specific table mentioned, you must use the
  49    <literal>ONLY</literal> clause.
  50   </para>
  51
  52   <para>
  53    You must have the <literal>DELETE</literal> privilege on the table
  54    to delete from it, as well as the <literal>SELECT</literal>
  55    privilege for any table whose values are read in the <replaceable
  56    class="parameter">condition</replaceable>.
  57   </para>
  58  </refsect1>
  59
  60  <refsect1>
  61   <title>Parameters</title>
  62
  63   <variablelist>
  64    <varlistentry>
  65     <term><replaceable class="parameter">table</replaceable></term>
  66     <listitem>
  67      <para>
  68       The name (optionally schema-qualified) of an existing table.
  69      </para>
  70     </listitem>
  71    </varlistentry>
  72
  73    <varlistentry>
  74     <term><replaceable class="parameter">condition</replaceable></term>
  75     <listitem>
  76      <para>
  77       A value expression that returns a value of type
  78       <type>boolean</type> that determines the rows which are to be
  79       deleted.
  80      </para>
  81     </listitem>
  82    </varlistentry>
  83   </variablelist>
  84  </refsect1>
  85
  86  <refsect1>
  87   <title>Outputs</title>
  88
  89   <para>
  90    On successful completion, a <command>DELETE</> command returns a command
  91    tag of the form
  92 <screen>
  93 DELETE <replaceable class="parameter">count</replaceable>
  94 </screen>
  95    The <replaceable class="parameter">count</replaceable> is the number
  96    of rows deleted.  If <replaceable class="parameter">count</replaceable> is
  97    0, no rows matched the <replaceable
  98    class="parameter">condition</replaceable> (this is not considered
  99    an error).
 100   </para>
 101  </refsect1>
 102
 103  <refsect1>
 104   <title>Examples</title>
 105
 106   <para>
 107    Delete all films but musicals:
 108 <programlisting>
 109 DELETE FROM films WHERE kind &lt;&gt; 'Musical';
 110 </programlisting>
 111   </para>
 112
 113   <para>
 114    Clear the table <literal>films</literal>:
 115 <programlisting>
 116 DELETE FROM films;
 117 </programlisting>
 118   </para>
 119  </refsect1>
 120
 121  <refsect1>
 122   <title>Compatibility</title>
 123
 124   <para>
 125    This command conforms to the SQL standard.
 126   </para>
 127  </refsect1>
 128 </refentry>
 129
 130 <!-- Keep this comment at the end of the file
 131 Local variables:
 132 mode: sgml
 133 sgml-omittag:nil
 134 sgml-shorttag:t
 135 sgml-minimize-attributes:nil
 136 sgml-always-quote-attributes:t
 137 sgml-indent-step:1
 138 sgml-indent-data:t
 139 sgml-parent-document:nil
 140 sgml-default-dtd-file:"../reference.ced"
 141 sgml-exposed-tags:nil
 142 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 143 sgml-local-ecat-files:nil
 144 End:
 145 -->