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

   1 <REFENTRY ID="SQL-CREATEINDEX">
   2  <REFMETA>
   3   <REFENTRYTITLE>
   4    CREATE INDEX
   5   </REFENTRYTITLE>
   6   <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
   7  </REFMETA>
   8  <REFNAMEDIV>
   9   <REFNAME>
  10    CREATE INDEX
  11   </REFNAME>
  12   <REFPURPOSE>
  13    Constructs a secondary index
  14   </REFPURPOSE>
  15  </refnamediv>
  16  <REFSYNOPSISDIV>
  17   <REFSYNOPSISDIVINFO>
  18    <DATE>1998-09-09</DATE>
  19   </REFSYNOPSISDIVINFO>
  20   <SYNOPSIS>
  21 CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
  22     ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ]
  23     ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable>] [, ...] )
  24 CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
  25     ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ]
  26     ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
  27   </SYNOPSIS>
  28
  29   <REFSECT2 ID="R2-SQL-CREATEINDEX-1">
  30    <REFSECT2INFO>
  31     <DATE>1998-09-09</DATE>
  32    </REFSECT2INFO>
  33    <TITLE>
  34     Inputs
  35    </TITLE>
  36    <PARA>
  37        <VARIABLELIST>
  38         <VARLISTENTRY>
  39          <TERM>
  40           UNIQUE
  41          </TERM>
  42          <LISTITEM>
  43           <PARA>
  44            Causes the system to check for
  45            duplicate values in the table when the index is created (if data
  46            already exist) and each time data is added. Attempts to
  47            insert or update non-duplicate data will generate an
  48            error.
  49           </PARA>
  50          </LISTITEM>
  51         </VARLISTENTRY>
  52         <VARLISTENTRY>
  53          <TERM>
  54           <replaceable class="parameter">index_name</replaceable>
  55          </TERM>
  56          <LISTITEM>
  57           <PARA>
  58            The name of the index to be created.
  59           </PARA>
  60          </LISTITEM>
  61         </VARLISTENTRY>
  62         <VARLISTENTRY>
  63          <TERM>
  64           <replaceable class="parameter">table</replaceable>
  65          </TERM>
  66          <LISTITEM>
  67           <PARA>
  68            The name of the table to be indexed.
  69           </PARA>
  70          </LISTITEM>
  71         </VARLISTENTRY>
  72         <VARLISTENTRY>
  73          <TERM>
  74           <replaceable class="parameter">acc_name</replaceable>
  75          </TERM>
  76          <LISTITEM>
  77           <PARA>
  78            the name of the access method which is to be used for
  79            the index. The default access method is BTREE.
  80            Postgres provides three access methods for secondary indexes:
  81            <variablelist>
  82             <varlistentry>
  83              <term>BTREE</term>
  84              <listitem>
  85               <para>
  86                an implementation of the Lehman-Yao
  87                high-concurrency btrees.
  88               </para>
  89              </listitem>
  90             </varlistentry>
  91             <varlistentry>
  92              <term>RTREE</term>
  93              <listitem>
  94               <para>implements standard rtrees using Guttman's
  95                quadratic split algorithm.
  96               </para>
  97              </listitem>
  98             </varlistentry>
  99             <varlistentry>
 100              <term>HASH</term>
 101              <listitem>
 102               <para>
 103                an implementation of Litwin's linear hashing.
 104               </para>
 105              </listitem>
 106             </varlistentry>
 107            </variablelist>
 108           </PARA>
 109          </LISTITEM>
 110         </VARLISTENTRY>
 111         <VARLISTENTRY>
 112          <TERM>
 113           <replaceable class="parameter">column</replaceable>
 114          </TERM>
 115          <LISTITEM>
 116           <PARA>
 117            The name of a column of the table.
 118           </PARA>
 119          </LISTITEM>
 120         </VARLISTENTRY>
 121         <VARLISTENTRY>
 122          <TERM>
 123           <replaceable class="parameter">ops_name</replaceable>
 124          </TERM>
 125          <LISTITEM>
 126           <PARA>
 127            An associated operator class.
 128            The following select list returns all ops_names:
 129
 130 <programlisting>
 131 SELECT am.amname AS acc_name,
 132        opc.opcname AS ops_name,
 133        opr.oprname AS ops_comp
 134     FROM pg_am am, pg_amop amop,
 135          pg_opclass opc, pg_operator opr
 136     WHERE amop.amopid = am.oid AND
 137           amop.amopclaid = opc.oid AND
 138           amop.amopopr = opr.oid
 139     ORDER BY acc_name, ops_name, ops_comp
 140 </programlisting>
 141
 142           </PARA>
 143       </LISTITEM>
 144      </VARLISTENTRY>
 145      <VARLISTENTRY>
 146       <TERM>
 147        <replaceable class="parameter">func_name</replaceable>
 148       </TERM>
 149       <LISTITEM>
 150        <PARA>
 151         A user-defined function, which returns a value that can
 152         be indexed.
 153        </PARA>
 154       </LISTITEM>
 155      </VARLISTENTRY>
 156     </variablelist>
 157    </para>
 158   </REFSECT2>
 159
 160   <REFSECT2 ID="R2-SQL-CREATEINDEX-2">
 161    <REFSECT2INFO>
 162     <DATE>1998-09-09</DATE>
 163    </REFSECT2INFO>
 164    <TITLE>
 165     Outputs
 166    </TITLE>
 167    <PARA>
 168
 169        <VARIABLELIST>
 170         <VARLISTENTRY>
 171          <TERM>
 172           <ReturnValue>CREATE</ReturnValue>
 173          </TERM>
 174          <LISTITEM>
 175           <PARA>
 176            The message returned if the index is successfully created.
 177           </PARA>
 178          </LISTITEM>
 179         </VARLISTENTRY>
 180
 181         <VARLISTENTRY>
 182       <TERM>
 183        <ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
 184       </TERM>
 185       <LISTITEM>
 186        <PARA>
 187         This error occurs if it is impossible to create the index.
 188        </para>
 189       </listitem>
 190      </varlistentry>
 191     </variablelist>
 192    </para>
 193   </REFSECT2>
 194  </REFSYNOPSISDIV>
 195
 196  <REFSECT1 ID="R1-SQL-CREATEINDEX-1">
 197   <REFSECT1INFO>
 198    <DATE>1998-09-09</DATE>
 199   </REFSECT1INFO>
 200   <TITLE>
 201    Description
 202   </TITLE>
 203   <PARA>
 204    <command>CREATE INDEX</command> constructs an index
 205    <replaceable class="parameter">index_name</replaceable>.
 206    on the specified
 207    <replaceable class="parameter">table</replaceable>.
 208
 209    <tip>
 210     <para>
 211      Indexes are primarily used to enhance database performance.
 212      But inappropriate use will result in slower performance.
 213     </para>
 214    </tip>
 215   </para>
 216   <para>
 217    In the first syntax shown above, the key fields for the
 218    index are specified as column names; a column may also have
 219    an associated operator class. An operator class is used
 220    to specify the operators to be used for a particular
 221    index. For example, a btree index on four-byte integers
 222    would use the <literal>int4_ops</literal> class;
 223    this operator class includes
 224    comparison functions for four-byte integers. The default
 225    operator class is the appropriate operator class for that
 226    field type.
 227   </para>
 228    <para>
 229     In the second syntax, an index is defined
 230     on the result of a user-defined function
 231     <replaceable class="parameter">func_name</replaceable> applied
 232     to one or more attributes of a single class. These functional
 233     indexes can be used to obtain fast access to data
 234     based on operators that would normally require some
 235     transformation to apply them to the base data.
 236    </para>
 237
 238   <REFSECT2 ID="R2-SQL-CREATEINDEX-3">
 239    <REFSECT2INFO>
 240     <DATE>1998-09-09</DATE>
 241    </REFSECT2INFO>
 242    <TITLE>
 243     Notes
 244    </TITLE>
 245    <PARA>
 246     Currently, only the BTREE access method supports multi-column
 247     indexes. Up to 7 keys may be specified.
 248    </PARA>
 249    <para>
 250     Use <command>DROP INDEX</command>
 251     to remove an index.
 252    </para>
 253   </REFSECT2>
 254  </refsect1>
 255
 256  <REFSECT1 ID="R1-SQL-CREATEINDEX-2">
 257   <TITLE>
 258    Usage
 259   </TITLE>
 260   <PARA>To create a btree index on the field <literal>title</literal>
 261    in the table <literal>films</literal>:
 262   </PARA>
 263   <ProgramListing>
 264 CREATE UNIQUE INDEX title_idx
 265     ON films (title);
 266   </ProgramListing>
 267
 268 <!--
 269 <comment>
 270 Is this example correct?
 271 </comment>
 272   <para>
 273    To create a rtree index on a point attribute so that we
 274    can efficiently use box operators on the result of the
 275    conversion function:
 276   </para>
 277   <programlisting>
 278 CREATE INDEX pointloc
 279     ON points USING RTREE (point2box(location) box_ops);
 280 SELECT * FROM points
 281     WHERE point2box(points.pointloc) = boxes.box;
 282   </programlisting>
 283 -->
 284
 285  </REFSECT1>
 286
 287  <REFSECT1 ID="R1-SQL-CREATEINDEX-3">
 288   <TITLE>
 289    Compatibility
 290   </TITLE>
 291   <PARA>
 292   </PARA>
 293
 294   <REFSECT2 ID="R2-SQL-CREATEINDEX-4">
 295    <REFSECT2INFO>
 296     <DATE>1998-09-09</DATE>
 297    </REFSECT2INFO>
 298    <TITLE>
 299     SQL92
 300    </TITLE>
 301    <PARA>
 302     CREATE INDEX is a <productname>Postgres</productname> language extension.
 303    </PARA>
 304    <para>
 305     There is no <command>CREATE INDEX</command> command in SQL92.
 306    </para>
 307   </refsect2>
 308  </refsect1>
 309 </REFENTRY>
 310
 311
 312 <!-- Keep this comment at the end of the file
 313 Local variables:
 314 mode: sgml
 315 sgml-omittag:t
 316 sgml-shorttag:t
 317 sgml-minimize-attributes:nil
 318 sgml-always-quote-attributes:t
 319 sgml-indent-step:1
 320 sgml-indent-data:t
 321 sgml-parent-document:nil
 322 sgml-default-dtd-file:"../reference.ced"
 323 sgml-exposed-tags:nil
 324 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 325 sgml-local-ecat-files:nil
 326 End:
 327 -->