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

   1 <!--
   2 doc/src/sgml/ref/alter_index.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERINDEX">
   7  <indexterm zone="sql-alterindex">
   8   <primary>ALTER INDEX</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle>ALTER INDEX</refentrytitle>
  13   <manvolnum>7</manvolnum>
  14   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>ALTER INDEX</refname>
  19   <refpurpose>change the definition of an index</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 ALTER INDEX [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
  25 ALTER INDEX [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> SET TABLESPACE <replaceable class="PARAMETER">tablespace_name</replaceable>
  26 ALTER INDEX <replaceable class="PARAMETER">name</replaceable> DEPENDS ON EXTENSION <replaceable class="PARAMETER">extension_name</replaceable>
  27 ALTER INDEX [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )
  28 ALTER INDEX [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )
  29 ALTER INDEX ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable> [ OWNED BY <replaceable class="PARAMETER">role_name</replaceable> [, ... ] ]
  30     SET TABLESPACE <replaceable class="PARAMETER">new_tablespace</replaceable> [ NOWAIT ]
  31 </synopsis>
  32  </refsynopsisdiv>
  33
  34  <refsect1>
  35   <title>Description</title>
  36
  37   <para>
  38    <command>ALTER INDEX</command> changes the definition of an existing index.
  39    There are several subforms:
  40
  41   <variablelist>
  42
  43    <varlistentry>
  44     <term><literal>RENAME</literal></term>
  45     <listitem>
  46      <para>
  47       The <literal>RENAME</literal> form changes the name of the index.
  48       There is no effect on the stored data.
  49      </para>
  50     </listitem>
  51    </varlistentry>
  52
  53    <varlistentry>
  54     <term><literal>SET TABLESPACE</literal></term>
  55     <listitem>
  56      <para>
  57       This form changes the index's tablespace to the specified tablespace and
  58       moves the data file(s) associated with the index to the new tablespace.
  59       To change the tablespace of an index, you must own the index and have
  60       <literal>CREATE</literal> privilege on the new tablespace.
  61       All indexes in the current database in a tablespace can be moved by using
  62       the <literal>ALL IN TABLESPACE</literal> form, which will lock all
  63       indexes to be moved and then move each one.  This form also supports
  64       <literal>OWNED BY</literal>, which will only move indexes owned by the
  65       roles specified.  If the <literal>NOWAIT</literal> option is specified
  66       then the command will fail if it is unable to acquire all of the locks
  67       required immediately.  Note that system catalogs will not be moved by
  68       this command, use <command>ALTER DATABASE</command> or explicit
  69       <command>ALTER INDEX</command> invocations instead if desired.
  70       See also
  71       <xref linkend="SQL-CREATETABLESPACE">.
  72      </para>
  73     </listitem>
  74    </varlistentry>
  75
  76    <varlistentry>
  77     <term><literal>DEPENDS ON EXTENSION</literal></term>
  78     <listitem>
  79      <para>
  80       This form marks the index as dependent on the extension, such that if the
  81       extension is dropped, the index will automatically be dropped as well.
  82      </para>
  83     </listitem>
  84    </varlistentry>
  85
  86    <varlistentry>
  87     <term><literal>SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )</literal></term>
  88     <listitem>
  89      <para>
  90       This form changes one or more index-method-specific storage parameters
  91       for the index.  See
  92       <xref linkend="SQL-CREATEINDEX">
  93       for details on the available parameters.  Note that the index contents
  94       will not be modified immediately by this command; depending on the
  95       parameter you might need to rebuild the index with
  96       <xref linkend="SQL-REINDEX">
  97       to get the desired effects.
  98      </para>
  99     </listitem>
 100    </varlistentry>
 101
 102    <varlistentry>
 103     <term><literal>RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )</literal></term>
 104     <listitem>
 105      <para>
 106       This form resets one or more index-method-specific storage parameters to
 107       their defaults.  As with <literal>SET</>, a <literal>REINDEX</literal>
 108       might be needed to update the index entirely.
 109      </para>
 110     </listitem>
 111    </varlistentry>
 112
 113   </variablelist>
 114   </para>
 115
 116  </refsect1>
 117
 118  <refsect1>
 119   <title>Parameters</title>
 120
 121     <variablelist>
 122
 123      <varlistentry>
 124       <term><literal>IF EXISTS</literal></term>
 125       <listitem>
 126        <para>
 127         Do not throw an error if the index does not exist. A notice is issued
 128         in this case.
 129        </para>
 130       </listitem>
 131      </varlistentry>
 132
 133      <varlistentry>
 134       <term><replaceable class="PARAMETER">name</replaceable></term>
 135       <listitem>
 136        <para>
 137         The name (possibly schema-qualified) of an existing index to
 138         alter.
 139        </para>
 140       </listitem>
 141      </varlistentry>
 142
 143      <varlistentry>
 144       <term><replaceable class="PARAMETER">new_name</replaceable></term>
 145       <listitem>
 146        <para>
 147         The new name for the index.
 148        </para>
 149       </listitem>
 150      </varlistentry>
 151
 152      <varlistentry>
 153       <term><replaceable class="PARAMETER">tablespace_name</replaceable></term>
 154       <listitem>
 155        <para>
 156         The tablespace to which the index will be moved.
 157        </para>
 158       </listitem>
 159      </varlistentry>
 160
 161      <varlistentry>
 162       <term><replaceable class="PARAMETER">extension_name</replaceable></term>
 163       <listitem>
 164        <para>
 165         The name of the extension that the index is to depend on.
 166        </para>
 167       </listitem>
 168      </varlistentry>
 169
 170      <varlistentry>
 171       <term><replaceable class="PARAMETER">storage_parameter</replaceable></term>
 172       <listitem>
 173        <para>
 174         The name of an index-method-specific storage parameter.
 175        </para>
 176       </listitem>
 177      </varlistentry>
 178
 179      <varlistentry>
 180       <term><replaceable class="PARAMETER">value</replaceable></term>
 181       <listitem>
 182        <para>
 183         The new value for an index-method-specific storage parameter.
 184         This might be a number or a word depending on the parameter.
 185        </para>
 186       </listitem>
 187      </varlistentry>
 188
 189     </variablelist>
 190  </refsect1>
 191
 192  <refsect1>
 193   <title>Notes</title>
 194
 195    <para>
 196     These operations are also possible using
 197     <xref linkend="SQL-ALTERTABLE">.
 198     <command>ALTER INDEX</> is in fact just an alias for the forms
 199     of <command>ALTER TABLE</> that apply to indexes.
 200    </para>
 201
 202    <para>
 203     There was formerly an <command>ALTER INDEX OWNER</> variant, but
 204     this is now ignored (with a warning).  An index cannot have an owner
 205     different from its table's owner.  Changing the table's owner
 206     automatically changes the index as well.
 207    </para>
 208
 209    <para>
 210     Changing any part of a system catalog index is not permitted.
 211    </para>
 212  </refsect1>
 213
 214  <refsect1>
 215   <title>Examples</title>
 216   <para>
 217    To rename an existing index:
 218 <programlisting>
 219 ALTER INDEX distributors RENAME TO suppliers;
 220 </programlisting>
 221   </para>
 222
 223   <para>
 224    To move an index to a different tablespace:
 225 <programlisting>
 226 ALTER INDEX distributors SET TABLESPACE fasttablespace;
 227 </programlisting>
 228   </para>
 229
 230   <para>
 231    To change an index's fill factor (assuming that the index method
 232    supports it):
 233 <programlisting>
 234 ALTER INDEX distributors SET (fillfactor = 75);
 235 REINDEX INDEX distributors;
 236 </programlisting></para>
 237
 238  </refsect1>
 239
 240  <refsect1>
 241   <title>Compatibility</title>
 242
 243   <para>
 244    <command>ALTER INDEX</> is a <productname>PostgreSQL</productname>
 245    extension.
 246   </para>
 247  </refsect1>
 248
 249
 250  <refsect1>
 251   <title>See Also</title>
 252
 253   <simplelist type="inline">
 254    <member><xref linkend="sql-createindex"></member>
 255    <member><xref linkend="sql-reindex"></member>
 256   </simplelist>
 257  </refsect1>
 258 </refentry>