← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/delete.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/delete.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.22 2005-01-09 05:57:45 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>Notes</title>
 
105
 
 
106
  <para>
 
107
   <productname>PostgreSQL</productname> lets you reference columns of
 
108
   other tables in the <literal>WHERE</> condition.  For example, to
 
109
   delete all films produced by a given producer, one might do
 
110
<programlisting>
 
111
DELETE FROM films
 
112
  WHERE producer_id = producers.id AND producers.name = 'foo';
 
113
</programlisting>
 
114
   What is essentially happening here is a join between <structname>films</>
 
115
   and <structname>producers</>, with all successfully joined
 
116
   <structname>films</> rows being marked for deletion.
 
117
   This syntax is not standard.  A more standard way to do it is
 
118
<programlisting>
 
119
DELETE FROM films
 
120
  WHERE producer_id IN (SELECT id FROM producers WHERE name = 'foo');
 
121
</programlisting>
 
122
   In some cases the join style is easier to write or faster to
 
123
   execute than the sub-select style.  One objection to the join style
 
124
   is that there is no explicit list of what tables are being used,
 
125
   which makes the style somewhat error-prone; also it cannot handle
 
126
   self-joins.
 
127
  </para>
 
128
 </refsect1>
 
129
 
 
130
 <refsect1>
 
131
  <title>Examples</title>
 
132
 
 
133
  <para>
 
134
   Delete all films but musicals:
 
135
<programlisting>
 
136
DELETE FROM films WHERE kind &lt;&gt; 'Musical';
 
137
</programlisting>
 
138
  </para>
 
139
 
 
140
  <para>
 
141
   Clear the table <literal>films</literal>:
 
142
<programlisting>
 
143
DELETE FROM films;
 
144
</programlisting>      
 
145
  </para>
 
146
 </refsect1>
 
147
 
 
148
 <refsect1>
 
149
  <title>Compatibility</title>
 
150
 
 
151
  <para>
 
152
   This command conforms to the SQL standard, except that the ability to
 
153
   reference other tables in the <literal>WHERE</> clause is a
 
154
   <productname>PostgreSQL</productname> extension.
 
155
  </para>
 
156
 </refsect1>
 
157
</refentry>
 
158
 
 
159
<!-- Keep this comment at the end of the file
 
160
Local variables:
 
161
mode: sgml
 
162
sgml-omittag:nil
 
163
sgml-shorttag:t
 
164
sgml-minimize-attributes:nil
 
165
sgml-always-quote-attributes:t
 
166
sgml-indent-step:1
 
167
sgml-indent-data:t
 
168
sgml-parent-document:nil
 
169
sgml-default-dtd-file:"../reference.ced"
 
170
sgml-exposed-tags:nil
 
171
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
172
sgml-local-ecat-files:nil
 
173
End:
 
174
-->