create_index.sgml

postgresql8.3.4源码,开源数据库

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.66 2007/11/26 21:36:33 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATEINDEX">
 <refmeta>
  <refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE INDEX</refname>
  <refpurpose>define a new index</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createindex">
  <primary>CREATE INDEX</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">method</replaceable> ]
    ( { <replaceable class="parameter">column</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] )
    [ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ]
    [ TABLESPACE <replaceable class="parameter">tablespace</replaceable> ]
    [ WHERE <replaceable class="parameter">predicate</replaceable> ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE INDEX</command> constructs an index <replaceable
   class="parameter">name</replaceable> on the specified table.
   Indexes are primarily used to enhance database performance (though
   inappropriate use can result in slower performance).
  </para>

  <para>
   The key field(s) for the index are specified as column names,
   or alternatively as expressions written in parentheses.
   Multiple fields can be specified if the index method supports
   multicolumn indexes.
  </para>

  <para>
   An index field can be an expression computed from the values of
   one or more columns of the table row.  This feature can be used
   to obtain fast access to data based on some transformation of
   the basic data. For example, an index computed on
   <literal>upper(col)</> would allow the clause
   <literal>WHERE upper(col) = 'JIM'</> to use an index.
  </para>

  <para>
   <productname>PostgreSQL</productname> provides the index methods
   B-tree, hash, GiST, and GIN.  Users can also define their own index
   methods, but that is fairly complicated.
  </para>

  <para>
    When the <literal>WHERE</literal> clause is present, a
    <firstterm>partial index</firstterm> is created.
    A partial index is an index that contains entries for only a portion of
    a table, usually a portion that is more useful for indexing than the
    rest of the table. For example, if you have a table that contains both
    billed and unbilled orders where the unbilled orders take up a small
    fraction of the total table and yet that is an often used section, you
    can improve performance by creating an index on just that portion.
    Another possible application is to use <literal>WHERE</literal> with
    <literal>UNIQUE</literal> to enforce uniqueness over a subset of a
    table.  See <xref linkend="indexes-partial"> for more discussion.
  </para>

  <para>
    The expression used in the <literal>WHERE</literal> clause can refer
    only to columns of the underlying table, but it can use all columns,
    not just the ones being indexed.  Presently, subqueries and
    aggregate expressions are also forbidden in <literal>WHERE</literal>.
    The same restrictions apply to index fields that are expressions.
  </para>

  <para>
   All functions and operators used in an index definition must be
   <quote>immutable</>, that is, their results must depend only on
   their arguments and never on any outside influence (such as
   the contents of another table or the current time).  This restriction
   ensures that the behavior of the index is well-defined.  To use a
   user-defined function in an index expression or <literal>WHERE</literal>
   clause, remember to mark the function immutable when you create it.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

    <variablelist>
     <varlistentry>
      <term><literal>UNIQUE</literal></term>
      <listitem>
       <para>
        Causes the system to check for
        duplicate values in the table when the index is created (if data
        already exist) and each time data is added. Attempts to
        insert or update data which would result in duplicate entries
        will generate an error.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>CONCURRENTLY</literal></term>
      <listitem>
       <para>
        When this option is used, <productname>PostgreSQL</> will build the
        index without taking any locks that prevent concurrent inserts,
        updates, or deletes on the table; whereas a standard index build
        locks out writes (but not reads) on the table until it's done.
        There are several caveats to be aware of when using this option
        &mdash; see <xref linkend="SQL-CREATEINDEX-CONCURRENTLY"
        endterm="SQL-CREATEINDEX-CONCURRENTLY-title">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">name</replaceable></term>
      <listitem>
       <para>
        The name of the index to be created.  No schema name can be included
        here; the index is always created in the same schema as its parent
        table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">table</replaceable></term>
      <listitem>
       <para>
        The name (possibly schema-qualified) of the table to be indexed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">method</replaceable></term>
      <listitem>
       <para>
        The name of the index method to be used.  Choices are
        <literal>btree</literal>, <literal>hash</literal>,
        <literal>gist</literal>, and <literal>gin</>.  The
        default method is <literal>btree</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">column</replaceable></term>
      <listitem>
       <para>
        The name of a column of the table.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">expression</replaceable></term>
      <listitem>
       <para>
        An expression based on one or more columns of the table.  The
        expression usually must be written with surrounding parentheses,
        as shown in the syntax.  However, the parentheses can be omitted
        if the expression has the form of a function call.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">opclass</replaceable></term>
      <listitem>
       <para>
        The name of an operator class. See below for details.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ASC</></term>
      <listitem>
       <para>
        Specifies ascending sort order (which is the default).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>DESC</></term>
      <listitem>
       <para>
        Specifies descending sort order.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NULLS FIRST</></term>
      <listitem>
       <para>
        Specifies that nulls sort before non-nulls.  This is the default
        when <literal>DESC</> is specified.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NULLS LAST</></term>
      <listitem>
       <para>
        Specifies that nulls sort after non-nulls.  This is the default
        when <literal>DESC</> is not specified.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">storage_parameter</replaceable></term>
      <listitem>
       <para>
        The name of an index-method-specific storage parameter.  See
        below for details.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">tablespace</replaceable></term>
      <listitem>
       <para>
        The tablespace in which to create the index.  If not specified,
        <xref linkend="guc-default-tablespace"> is consulted, or
        <xref linkend="guc-temp-tablespaces"> for indexes on temporary
        tables.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">predicate</replaceable></term>
      <listitem>
       <para>
        The constraint expression for a partial index.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>

  <refsect2 id="SQL-CREATEINDEX-storage-parameters">
   <title id="SQL-CREATEINDEX-storage-parameters-title">Index Storage Parameters</title>

   <para>
    The <literal>WITH</> clause can specify <firstterm>storage parameters</>
    for indexes.  Each index method can have its own set of allowed storage
    parameters.  The built-in index methods all accept a single parameter:
   </para>