begriffs open source - ai-pg/blob - full-docs/man7/ALTER_INDEX.7

   1 '\" t
   2 .\"     Title: ALTER INDEX
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "ALTER INDEX" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 ALTER_INDEX \- change the definition of an index
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER INDEX [ IF EXISTS ] \fIname\fR RENAME TO \fInew_name\fR
  36 ALTER INDEX [ IF EXISTS ] \fIname\fR SET TABLESPACE \fItablespace_name\fR
  37 ALTER INDEX \fIname\fR ATTACH PARTITION \fIindex_name\fR
  38 ALTER INDEX \fIname\fR [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR
  39 ALTER INDEX [ IF EXISTS ] \fIname\fR SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
  40 ALTER INDEX [ IF EXISTS ] \fIname\fR RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] )
  41 ALTER INDEX [ IF EXISTS ] \fIname\fR ALTER [ COLUMN ] \fIcolumn_number\fR
  42     SET STATISTICS \fIinteger\fR
  43 ALTER INDEX ALL IN TABLESPACE \fIname\fR [ OWNED BY \fIrole_name\fR [, \&.\&.\&. ] ]
  44     SET TABLESPACE \fInew_tablespace\fR [ NOWAIT ]
  45 .fi
  46 .SH "DESCRIPTION"
  47 .PP
  48 \fBALTER INDEX\fR
  49 changes the definition of an existing index\&. There are several subforms described below\&. Note that the lock level required may differ for each subform\&. An
  50 ACCESS EXCLUSIVE
  51 lock is held unless explicitly noted\&. When multiple subcommands are listed, the lock held will be the strictest one required from any subcommand\&.
  52 .PP
  53 RENAME
  54 .RS 4
  55 The
  56 RENAME
  57 form changes the name of the index\&. If the index is associated with a table constraint (either
  58 UNIQUE,
  59 PRIMARY KEY, or
  60 EXCLUDE), the constraint is renamed as well\&. There is no effect on the stored data\&.
  61 .sp
  62 Renaming an index acquires a
  63 SHARE UPDATE EXCLUSIVE
  64 lock\&.
  65 .RE
  66 .PP
  67 SET TABLESPACE
  68 .RS 4
  69 This form changes the index\*(Aqs tablespace to the specified tablespace and moves the data file(s) associated with the index to the new tablespace\&. To change the tablespace of an index, you must own the index and have
  70 CREATE
  71 privilege on the new tablespace\&. All indexes in the current database in a tablespace can be moved by using the
  72 ALL IN TABLESPACE
  73 form, which will lock all indexes to be moved and then move each one\&. This form also supports
  74 OWNED BY, which will only move indexes owned by the roles specified\&. If the
  75 NOWAIT
  76 option is specified then the command will fail if it is unable to acquire all of the locks required immediately\&. Note that system catalogs will not be moved by this command, use
  77 \fBALTER DATABASE\fR
  78 or explicit
  79 \fBALTER INDEX\fR
  80 invocations instead if desired\&. See also
  81 \fBCREATE TABLESPACE\fR\&.
  82 .RE
  83 .PP
  84 ATTACH PARTITION \fIindex_name\fR
  85 .RS 4
  86 Causes the named index (possibly schema\-qualified) to become attached to the altered index\&. The named index must be on a partition of the table containing the index being altered, and have an equivalent definition\&. An attached index cannot be dropped by itself, and will automatically be dropped if its parent index is dropped\&.
  87 .RE
  88 .PP
  89 DEPENDS ON EXTENSION \fIextension_name\fR
  90 .br
  91 NO DEPENDS ON EXTENSION \fIextension_name\fR
  92 .RS 4
  93 This form marks the index as dependent on the extension, or no longer dependent on that extension if
  94 NO
  95 is specified\&. An index that\*(Aqs marked as dependent on an extension is automatically dropped when the extension is dropped\&.
  96 .RE
  97 .PP
  98 SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
  99 .RS 4
 100 This form changes one or more index\-method\-specific storage parameters for the index\&. See
 101 \fBCREATE INDEX\fR
 102 for details on the available parameters\&. Note that the index contents will not be modified immediately by this command; depending on the parameter you might need to rebuild the index with
 103 \fBREINDEX\fR
 104 to get the desired effects\&.
 105 .RE
 106 .PP
 107 RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] )
 108 .RS 4
 109 This form resets one or more index\-method\-specific storage parameters to their defaults\&. As with
 110 SET, a
 111 REINDEX
 112 might be needed to update the index entirely\&.
 113 .RE
 114 .PP
 115 ALTER [ COLUMN ] \fIcolumn_number\fR SET STATISTICS \fIinteger\fR
 116 .RS 4
 117 This form sets the per\-column statistics\-gathering target for subsequent
 118 \fBANALYZE\fR
 119 operations, though can be used only on index columns that are defined as an expression\&. Since expressions lack a unique name, we refer to them using the ordinal number of the index column\&. The target can be set in the range 0 to 10000; alternatively, set it to \-1 to revert to using the system default statistics target (default_statistics_target)\&. For more information on the use of statistics by the
 120 PostgreSQL
 121 query planner, refer to
 122 Section\ \&14.2\&.
 123 .RE
 124 .SH "PARAMETERS"
 125 .PP
 126 IF EXISTS
 127 .RS 4
 128 Do not throw an error if the index does not exist\&. A notice is issued in this case\&.
 129 .RE
 130 .PP
 131 \fIcolumn_number\fR
 132 .RS 4
 133 The ordinal number refers to the ordinal (left\-to\-right) position of the index column\&.
 134 .RE
 135 .PP
 136 \fIname\fR
 137 .RS 4
 138 The name (possibly schema\-qualified) of an existing index to alter\&.
 139 .RE
 140 .PP
 141 \fInew_name\fR
 142 .RS 4
 143 The new name for the index\&.
 144 .RE
 145 .PP
 146 \fItablespace_name\fR
 147 .RS 4
 148 The tablespace to which the index will be moved\&.
 149 .RE
 150 .PP
 151 \fIextension_name\fR
 152 .RS 4
 153 The name of the extension that the index is to depend on\&.
 154 .RE
 155 .PP
 156 \fIstorage_parameter\fR
 157 .RS 4
 158 The name of an index\-method\-specific storage parameter\&.
 159 .RE
 160 .PP
 161 \fIvalue\fR
 162 .RS 4
 163 The new value for an index\-method\-specific storage parameter\&. This might be a number or a word depending on the parameter\&.
 164 .RE
 165 .SH "NOTES"
 166 .PP
 167 These operations are also possible using
 168 \fBALTER TABLE\fR\&.
 169 \fBALTER INDEX\fR
 170 is in fact just an alias for the forms of
 171 \fBALTER TABLE\fR
 172 that apply to indexes\&.
 173 .PP
 174 There was formerly an
 175 \fBALTER INDEX OWNER\fR
 176 variant, but this is now ignored (with a warning)\&. An index cannot have an owner different from its table\*(Aqs owner\&. Changing the table\*(Aqs owner automatically changes the index as well\&.
 177 .PP
 178 Changing any part of a system catalog index is not permitted\&.
 179 .SH "EXAMPLES"
 180 .PP
 181 To rename an existing index:
 182 .sp
 183 .if n \{\
 184 .RS 4
 185 .\}
 186 .nf
 187 ALTER INDEX distributors RENAME TO suppliers;
 188 .fi
 189 .if n \{\
 190 .RE
 191 .\}
 192 .PP
 193 To move an index to a different tablespace:
 194 .sp
 195 .if n \{\
 196 .RS 4
 197 .\}
 198 .nf
 199 ALTER INDEX distributors SET TABLESPACE fasttablespace;
 200 .fi
 201 .if n \{\
 202 .RE
 203 .\}
 204 .PP
 205 To change an index\*(Aqs fill factor (assuming that the index method supports it):
 206 .sp
 207 .if n \{\
 208 .RS 4
 209 .\}
 210 .nf
 211 ALTER INDEX distributors SET (fillfactor = 75);
 212 REINDEX INDEX distributors;
 213 .fi
 214 .if n \{\
 215 .RE
 216 .\}
 217 .PP
 218 Set the statistics\-gathering target for an expression index:
 219 .sp
 220 .if n \{\
 221 .RS 4
 222 .\}
 223 .nf
 224 CREATE INDEX coord_idx ON measured (x, y, (z + t));
 225 ALTER INDEX coord_idx ALTER COLUMN 3 SET STATISTICS 1000;
 226 .fi
 227 .if n \{\
 228 .RE
 229 .\}
 230 .SH "COMPATIBILITY"
 231 .PP
 232 \fBALTER INDEX\fR
 233 is a
 234 PostgreSQL
 235 extension\&.
 236 .SH "SEE ALSO"
 237 CREATE INDEX (\fBCREATE_INDEX\fR(7)), \fBREINDEX\fR(7)