head	1.75;
access;
symbols
	REL9_0_0:1.74.2.1
	REL9_1_ALPHA1:1.75
	REL9_0_RC1:1.74.2.1
	REL9_0_BETA4:1.74.2.1
	REL9_0_STABLE:1.74.0.2
	REL9_0_BETA3:1.74
	REL9_0_BETA2:1.74
	REL7_4_29:1.43
	REL8_0_25:1.51
	REL8_1_21:1.51
	REL8_2_17:1.58
	REL8_3_11:1.66
	REL8_4_4:1.71.2.1
	REL9_0_BETA1:1.74
	REL9_0_ALPHA5_BRANCH:1.73.0.2
	REL9_0_ALPHA5:1.73
	REL7_4_28:1.43
	REL8_0_24:1.51
	REL8_1_20:1.51
	REL8_2_16:1.58
	REL8_3_10:1.66
	REL8_4_3:1.71
	REL9_0_ALPHA4:1.72
	REL9_0_ALPHA4_BRANCH:1.72.0.2
	REL8_5_ALPHA3:1.71
	REL8_5_ALPHA3_BRANCH:1.71.0.8
	REL7_4_27:1.43
	REL8_0_23:1.51
	REL8_1_19:1.51
	REL8_2_15:1.58
	REL8_3_9:1.66
	REL8_4_2:1.71
	REL8_5_ALPHA2:1.71
	REL8_5_ALPHA2_BRANCH:1.71.0.6
	REL7_4_26:1.43
	REL8_0_22:1.51
	REL8_1_18:1.51
	REL8_2_14:1.58
	REL8_3_8:1.66
	REL8_4_1:1.71
	REL8_5_ALPHA1:1.71
	REL8_5_ALPHA1_BRANCH:1.71.0.4
	REL8_4_STABLE:1.71.0.2
	REL8_4_0:1.71
	REL8_4_RC2:1.71
	REL8_4_RC1:1.71
	REL8_4_BETA2:1.71
	REL8_4_BETA1:1.71
	REL7_4_25:1.43
	REL8_0_21:1.51
	REL8_1_17:1.51
	REL8_2_13:1.58
	REL8_3_7:1.66
	REL7_4_24:1.43
	REL8_0_20:1.51
	REL8_1_16:1.51
	REL8_2_12:1.58
	REL8_3_6:1.66
	REL7_4_23:1.43
	REL8_0_19:1.51
	REL8_1_15:1.51
	REL8_2_11:1.58
	REL8_3_5:1.66
	REL7_4_22:1.43
	REL8_0_18:1.51
	REL8_1_14:1.51
	REL8_2_10:1.58
	REL8_3_4:1.66
	REL7_4_21:1.43
	REL8_0_17:1.51
	REL8_1_13:1.51
	REL8_2_9:1.58
	REL8_3_3:1.66
	REL7_4_20:1.43
	REL8_0_16:1.51
	REL8_1_12:1.51
	REL8_2_8:1.58
	REL8_3_2:1.66
	REL8_2_7:1.58
	REL8_3_1:1.66
	REL8_3_STABLE:1.66.0.2
	REL8_3_0:1.66
	REL8_3_RC2:1.66
	REL7_3_21:1.37
	REL7_4_19:1.43
	REL8_0_15:1.51
	REL8_1_11:1.51
	REL8_2_6:1.58
	REL8_3_RC1:1.66
	REL8_3_BETA4:1.66
	REL8_3_BETA3:1.65
	REL8_3_BETA2:1.65
	REL8_3_BETA1:1.65
	REL7_3_20:1.37
	REL7_4_18:1.43
	REL8_0_14:1.51
	REL8_1_10:1.51
	REL8_2_5:1.58
	REL7_3_19:1.37
	REL7_4_17:1.43
	REL8_0_13:1.51
	REL8_1_9:1.51
	REL8_2_4:1.58
	REL8_0_12:1.51
	REL8_1_8:1.51
	REL8_2_3:1.58
	REL7_3_18:1.37
	REL7_4_16:1.43
	REL8_0_11:1.51
	REL8_1_7:1.51
	REL8_2_2:1.58
	REL8_0_10:1.51
	REL8_1_6:1.51
	REL8_2_1:1.58
	REL7_4_15:1.43
	REL7_3_17:1.37
	REL8_2_STABLE:1.58.0.2
	REL8_2_0:1.58
	REL8_2_RC1:1.58
	REL8_2_BETA3:1.58
	REL8_2_BETA2:1.58
	REL8_1_5:1.51
	REL8_0_9:1.51
	REL7_4_14:1.43
	REL7_3_16:1.37
	REL8_2_BETA1:1.58
	REL7_3_15:1.37
	REL7_4_13:1.43
	REL8_0_8:1.51
	REL8_1_4:1.51
	REL7_3_14:1.37
	REL7_4_12:1.43
	REL8_0_7:1.51
	REL8_1_3:1.51
	REL7_3_13:1.37
	REL7_4_11:1.43
	REL8_0_6:1.51
	REL8_1_2:1.51
	REL7_3_12:1.37
	REL7_4_10:1.43
	REL8_0_5:1.51
	REL8_1_1:1.51
	REL8_1_STABLE:1.51.0.6
	REL8_1_0:1.51
	REL8_1_0RC1:1.51
	REL8_1_0BETA4:1.51
	REL8_1_0BETA3:1.51
	REL7_3_11:1.37
	REL7_4_9:1.43
	REL8_0_4:1.51
	REL8_1_0BETA2:1.51
	REL8_1_0BETA1:1.51
	REL7_2_8:1.26
	REL7_3_10:1.37
	REL7_4_8:1.43
	REL8_0_3:1.51
	REL8_0_2:1.51
	REL7_2_7:1.26
	REL7_3_9:1.37
	REL7_4_7:1.43
	REL8_0_1:1.51
	REL8_0_STABLE:1.51.0.4
	REL8_0_0:1.51.0.2
	REL8_0_0RC5:1.51
	REL8_0_0RC4:1.51
	REL8_0_0RC3:1.50
	REL8_0_0RC2:1.50
	REL8_0_0RC1:1.50
	REL8_0_0BETA5:1.50
	REL8_0_0BETA4:1.49
	REL7_4_6:1.43
	REL7_3_8:1.37
	REL7_2_6:1.26
	REL8_0_0BETA3:1.49
	REL8_0_0BETA2:1.49
	REL7_2_5:1.26
	REL7_4_5:1.43
	REL7_3_7:1.37
	REL7_4_4:1.43
	REL8_0_0BETA1:1.49
	REL7_4_3:1.43
	REL7_4_2:1.43
	REL7_3_6:1.37
	REL7_4_1:1.43
	REL7_3_5:1.37
	REL7_4:1.43
	REL7_4_RC2:1.43
	REL7_4_STABLE:1.43.0.2
	REL7_4_RC1:1.43
	REL7_4_BETA5:1.43
	REL7_4_BETA4:1.43
	REL7_4_BETA3:1.42
	REL7_4_BETA2:1.39
	WIN32_DEV:1.39.0.2
	REL7_4_BETA1:1.39
	REL7_3_4:1.37
	REL7_3_2:1.37
	REL7_2_4:1.26
	REL7_3_STABLE:1.37.0.2
	REL7_2_3:1.26
	REL7_2_STABLE:1.26.0.2
	REL7_2:1.26
	REL7_2_RC2:1.26
	REL7_2_RC1:1.26
	REL7_2_BETA5:1.25
	REL7_2_BETA4:1.25
	REL7_2_BETA3:1.24
	REL7_2_BETA2:1.24
	REL7_2_BETA1:1.24
	REL7_1_2:1.18
	REL7_1_STABLE:1.18.0.2
	REL7_1_BETA:1.16
	REL7_1_BETA3:1.17
	REL7_1_BETA2:1.17
	REL7_1:1.18
	REL7_0_PATCHES:1.13.0.2
	REL7_0:1.13
	REL6_5_PATCHES:1.8.0.2
	REL6_5:1.8
	REL6_4:1.6.0.2;
locks; strict;
comment	@# @;


1.75
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.74;

1.74
date	2010.04.03.07.22.58;	author petere;	state Exp;
branches
	1.74.2.1;
next	1.73;

1.73
date	2010.03.17.15.55.50;	author tgl;	state Exp;
branches;
next	1.72;

1.72
date	2009.12.23.17.41.43;	author tgl;	state Exp;
branches;
next	1.71;

1.71
date	2009.03.24.20.17.08;	author tgl;	state Exp;
branches
	1.71.2.1;
next	1.70;

1.70
date	2009.02.02.19.31.38;	author alvherre;	state Exp;
branches;
next	1.69;

1.69
date	2008.11.14.10.22.46;	author petere;	state Exp;
branches;
next	1.68;

1.68
date	2008.07.11.21.06.29;	author tgl;	state Exp;
branches;
next	1.67;

1.67
date	2008.03.16.23.57.51;	author tgl;	state Exp;
branches;
next	1.66;

1.66
date	2007.11.26.21.36.33;	author petere;	state Exp;
branches;
next	1.65;

1.65
date	2007.09.20.17.56.30;	author tgl;	state Exp;
branches;
next	1.64;

1.64
date	2007.09.07.00.58.56;	author tgl;	state Exp;
branches;
next	1.63;

1.63
date	2007.06.03.17.05.53;	author tgl;	state Exp;
branches;
next	1.62;

1.62
date	2007.04.06.22.33.41;	author tgl;	state Exp;
branches;
next	1.61;

1.61
date	2007.04.03.22.38.35;	author momjian;	state Exp;
branches;
next	1.60;

1.60
date	2007.01.31.23.26.03;	author momjian;	state Exp;
branches;
next	1.59;

1.59
date	2007.01.09.02.14.10;	author tgl;	state Exp;
branches;
next	1.58;

1.58
date	2006.09.16.00.30.17;	author momjian;	state Exp;
branches;
next	1.57;

1.57
date	2006.09.13.23.42.26;	author tgl;	state Exp;
branches;
next	1.56;

1.56
date	2006.08.25.04.06.45;	author tgl;	state Exp;
branches;
next	1.55;

1.55
date	2006.07.11.21.05.57;	author tgl;	state Exp;
branches;
next	1.54;

1.54
date	2006.07.04.18.07.24;	author tgl;	state Exp;
branches;
next	1.53;

1.53
date	2006.07.02.02.23.17;	author momjian;	state Exp;
branches;
next	1.52;

1.52
date	2005.11.07.17.36.44;	author tgl;	state Exp;
branches;
next	1.51;

1.51
date	2005.01.04.00.39.53;	author tgl;	state Exp;
branches;
next	1.50;

1.50
date	2004.11.05.19.15.51;	author tgl;	state Exp;
branches;
next	1.49;

1.49
date	2004.07.12.01.22.53;	author momjian;	state Exp;
branches;
next	1.48;

1.48
date	2004.06.18.06.13.05;	author tgl;	state Exp;
branches;
next	1.47;

1.47
date	2004.04.20.12.53.28;	author momjian;	state Exp;
branches;
next	1.46;

1.46
date	2004.04.20.04.25.47;	author momjian;	state Exp;
branches;
next	1.45;

1.45
date	2004.04.20.01.00.26;	author momjian;	state Exp;
branches;
next	1.44;

1.44
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.43;

1.43
date	2003.09.22.00.16.57;	author petere;	state Exp;
branches;
next	1.42;

1.42
date	2003.09.11.21.42.20;	author momjian;	state Exp;
branches;
next	1.41;

1.41
date	2003.09.09.18.28.52;	author tgl;	state Exp;
branches;
next	1.40;

1.40
date	2003.08.31.17.32.22;	author petere;	state Exp;
branches;
next	1.39;

1.39
date	2003.05.28.16.03.55;	author tgl;	state Exp;
branches
	1.39.2.1;
next	1.38;

1.38
date	2003.04.22.10.08.08;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2002.09.21.18.32.54;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2002.08.13.20.40.43;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	2002.07.30.17.34.37;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2002.06.21.19.06.44;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2002.06.21.16.52.00;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2002.06.21.03.25.53;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2002.05.18.15.44.47;	author petere;	state Exp;
branches;
next	1.30;

1.30
date	2002.04.23.02.07.15;	author tgl;	state Exp;
branches;
next	1.29;

1.29
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.28;

1.28
date	2002.04.11.23.20.04;	author momjian;	state Exp;
branches;
next	1.27;

1.27
date	2002.03.22.19.20.38;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2002.01.20.22.19.56;	author petere;	state Exp;
branches;
next	1.25;

1.25
date	2001.12.08.03.24.34;	author thomas;	state Exp;
branches;
next	1.24;

1.24
date	2001.09.14.08.05.55;	author ishii;	state Exp;
branches;
next	1.23;

1.23
date	2001.09.03.12.57.49;	author petere;	state Exp;
branches;
next	1.22;

1.22
date	2001.08.21.16.35.59;	author tgl;	state Exp;
branches;
next	1.21;

1.21
date	2001.08.06.18.09.45;	author tgl;	state Exp;
branches;
next	1.20;

1.20
date	2001.07.16.05.06.57;	author tgl;	state Exp;
branches;
next	1.19;

1.19
date	2001.05.17.21.50.18;	author petere;	state Exp;
branches;
next	1.18;

1.18
date	2001.01.13.23.58.55;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2000.10.05.19.48.17;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	2000.09.12.20.52.08;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2000.06.19.03.54.15;	author tgl;	state Exp;
branches;
next	1.13;

1.13
date	2000.05.02.20.02.03;	author thomas;	state Exp;
branches;
next	1.12;

1.12
date	2000.04.23.02.08.33;	author tgl;	state Exp;
branches;
next	1.11;

1.11
date	2000.04.11.05.39.15;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	2000.03.16.14.39.30;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	99.07.22.15.09.07;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	99.07.06.17.16.34;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	98.12.29.02.24.34;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	98.10.30.19.33.44;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	98.10.14.16.30.17;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.09.22.15.47.39;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.09.16.14.43.03;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.09.07.15.58.11;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.05.13.05.34.00;	author thomas;	state Exp;
branches;
next	;

1.39.2.1
date	2003.09.07.04.36.45;	author momjian;	state Exp;
branches;
next	;

1.71.2.1
date	2010.03.17.15.55.55;	author tgl;	state Exp;
branches;
next	;

1.74.2.1
date	2010.07.29.19.34.37;	author petere;	state Exp;
branches;
next	;


desc
@@


1.75
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.74 2010/04/03 07:22:58 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATEINDEX">
 <refmeta>
  <refentrytitle>CREATE INDEX</refentrytitle>
  <manvolnum>7</manvolnum>
  <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
   on the specified column(s) of 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.  If the name is omitted, <productname>PostgreSQL</> chooses a
        suitable name based on the parent table's name and the indexed column
        name(s).
       </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
        <xref linkend="sql-createindex-storage-parameters" endterm="sql-createindex-storage-parameters-title">
        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 optional <literal>WITH</> clause specifies <firstterm>storage
    parameters</> for the index.  Each index method has its own set of allowed
    storage parameters.  The B-tree, hash and GiST index methods all accept a
    single parameter:
   </para>

   <variablelist>

   <varlistentry>
    <term><literal>FILLFACTOR</></term>
    <listitem>
     <para>
      The fillfactor for an index is a percentage that determines how full
      the index method will try to pack index pages.  For B-trees, leaf pages
      are filled to this percentage during initial index build, and also
      when extending the index at the right (adding new largest key values).
      If pages
      subsequently become completely full, they will be split, leading to
      gradual degradation in the index's efficiency.  B-trees use a default
      fillfactor of 90, but any integer value from 10 to 100 can be selected.
      If the table is static then fillfactor 100 is best to minimize the
      index's physical size, but for heavily updated tables a smaller
      fillfactor is better to minimize the need for page splits.  The
      other index methods use fillfactor in different but roughly analogous
      ways; the default fillfactor varies between methods.
     </para>
    </listitem>
   </varlistentry>

   </variablelist>

   <para>
    GIN indexes accept a different parameter:
   </para>

   <variablelist>

   <varlistentry>
    <term><literal>FASTUPDATE</></term>
    <listitem>
    <para>
     This setting controls usage of the fast update technique described in
     <xref linkend="gin-fast-update">.  It is a Boolean parameter:
     <literal>ON</> enables fast update, <literal>OFF</> disables it.
     (Alternative spellings of <literal>ON</> and <literal>OFF</> are
     allowed as described in <xref linkend="config-setting">.)  The
     default is <literal>ON</>.
    </para>

    <note>
     <para>
      Turning <literal>FASTUPDATE</> off via <command>ALTER INDEX</> prevents
      future insertions from going into the list of pending index entries,
      but does not in itself flush previous entries.  You might want to
      <command>VACUUM</> the table afterward to ensure the pending list is
      emptied.
     </para>
    </note>
    </listitem>
   </varlistentry>

   </variablelist>
  </refsect2>

  <refsect2 id="SQL-CREATEINDEX-CONCURRENTLY">
   <title id="SQL-CREATEINDEX-CONCURRENTLY-title">Building Indexes Concurrently</title>

   <indexterm zone="SQL-CREATEINDEX-CONCURRENTLY">
   <primary>index</primary>
   <secondary>building concurrently</secondary>
   </indexterm>

   <para>
    Creating an index can interfere with regular operation of a database.
    Normally <productname>PostgreSQL</> locks the table to be indexed against
    writes and performs the entire index build with a single scan of the
    table. Other transactions can still read the table, but if they try to
    insert, update, or delete rows in the table they will block until the
    index build is finished. This could have a severe effect if the system is
    a live production database.  Very large tables can take many hours to be
    indexed, and even for smaller tables, an index build can lock out writers
    for periods that are unacceptably long for a production system.
   </para>

   <para>
    <productname>PostgreSQL</> supports building indexes without locking
    out writes.  This method is invoked by specifying the
    <literal>CONCURRENTLY</> option of <command>CREATE INDEX</>.
    When this option is used,
    <productname>PostgreSQL</> must perform two scans of the table, and in
    addition it must wait for all existing transactions that could potentially
    use the index to terminate.  Thus
    this method requires more total work than a standard index build and takes
    significantly longer to complete.  However, since it allows normal
    operations to continue while the index is built, this method is useful for
    adding new indexes in a production environment.  Of course, the extra CPU
    and I/O load imposed by the index creation might slow other operations.
   </para>

   <para>
    In a concurrent index build, the index is actually entered into the
    system catalogs in one transaction, then the two table scans occur in a
    second and third transaction.
    If a problem arises while scanning the table, such as a
    uniqueness violation in a unique index, the <command>CREATE INDEX</>
    command will fail but leave behind an <quote>invalid</> index. This index
    will be ignored for querying purposes because it might be incomplete;
    however it will still consume update overhead. The <application>psql</>
    <command>\d</> command will report such an index as <literal>INVALID</>:

<programlisting>
postgres=# \d tab
       Table "public.tab"
 Column |  Type   | Modifiers 
--------+---------+-----------
 col    | integer | 
Indexes:
    "idx" btree (col) INVALID
</programlisting>

    The recommended recovery
    method in such cases is to drop the index and try again to perform
    <command>CREATE INDEX CONCURRENTLY</>.  (Another possibility is to rebuild
    the index with <command>REINDEX</>.  However, since <command>REINDEX</>
    does not support concurrent builds, this option is unlikely to seem
    attractive.)
   </para>

   <para>
    Another caveat when building a unique index concurrently is that the
    uniqueness constraint is already being enforced against other transactions
    when the second table scan begins.  This means that constraint violations
    could be reported in other queries prior to the index becoming available
    for use, or even in cases where the index build eventually fails.  Also,
    if a failure does occur in the second scan, the <quote>invalid</> index
    continues to enforce its uniqueness constraint afterwards.
   </para>

   <para>
    Concurrent builds of expression indexes and partial indexes are supported.
    Errors occurring in the evaluation of these expressions could cause
    behavior similar to that described above for unique constraint violations.
   </para>

   <para>
    Regular index builds permit other regular index builds on the
    same table to occur in parallel, but only one concurrent index build
    can occur on a table at a time.  In both cases, no other types of schema
    modification on the table are allowed meanwhile.  Another difference
    is that a regular <command>CREATE INDEX</> command can be performed within
    a transaction block, but <command>CREATE INDEX CONCURRENTLY</> cannot.
   </para>
  </refsect2>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   See <xref linkend="indexes"> for information about when indexes can
   be used, when they are not used, and in which particular situations
   they can be useful.
  </para>

  <para>
   Currently, only the B-tree, GiST and GIN index methods support
   multicolumn indexes. Up to 32 fields can be specified by default.
   (This limit can be altered when building
   <productname>PostgreSQL</productname>.)  Only B-tree currently
   supports unique indexes.
  </para>

  <para>
   An <firstterm>operator class</firstterm> can be specified for each
   column of an index. The operator class identifies the operators to be
   used by the index for that column. For example, a B-tree index on
   four-byte integers would use the <literal>int4_ops</literal> class;
   this operator class includes comparison functions for four-byte
   integers. In practice the default operator class for the column's data
   type is usually sufficient. The main point of having operator classes
   is that for some data types, there could be more than one meaningful
   ordering. For example, we might want to sort a complex-number data
   type either by absolute value or by real part. We could do this by
   defining two operator classes for the data type and then selecting
   the proper class when making an index.  More information about
   operator classes is in <xref linkend="indexes-opclass"> and in <xref
   linkend="xindex">.
  </para>

  <para>
   For index methods that support ordered scans (currently, only B-tree),
   the optional clauses <literal>ASC</>, <literal>DESC</>, <literal>NULLS
   FIRST</>, and/or <literal>NULLS LAST</> can be specified to modify
   the sort ordering of the index.  Since an ordered index can be
   scanned either forward or backward, it is not normally useful to create a
   single-column <literal>DESC</> index &mdash; that sort ordering is already
   available with a regular index.  The value of these options is that
   multicolumn indexes can be created that match the sort ordering requested
   by a mixed-ordering query, such as <literal>SELECT ... ORDER BY x ASC, y
   DESC</>.  The <literal>NULLS</> options are useful if you need to support
   <quote>nulls sort low</> behavior, rather than the default <quote>nulls
   sort high</>, in queries that depend on indexes to avoid sorting steps.
  </para>

  <para>
   For most index methods, the speed of creating an index is
   dependent on the setting of <xref linkend="guc-maintenance-work-mem">.
   Larger values will reduce the time needed for index creation, so long
   as you don't make it larger than the amount of memory really available,
   which would drive the machine into swapping.  For hash indexes, the
   value of <xref linkend="guc-effective-cache-size"> is also relevant to
   index creation time: <productname>PostgreSQL</productname> will use one
   of two different hash index creation methods depending on whether the
   estimated index size is more or less than <varname>effective_cache_size</>.
   For best results, make sure that this parameter is also set to something
   reflective of available memory, and be careful that the sum of
   <varname>maintenance_work_mem</> and <varname>effective_cache_size</> is
   less than the machine's RAM less whatever space is needed by other
   programs.
  </para>

  <para>
   Use <xref linkend="sql-dropindex">
   to remove an index.
  </para>

  <para>
   Prior releases of <productname>PostgreSQL</productname> also had an
   R-tree index method.  This method has been removed because
   it had no significant advantages over the GiST method.
   If <literal>USING rtree</> is specified, <command>CREATE INDEX</>
   will interpret it as <literal>USING gist</>, to simplify conversion
   of old databases to GiST.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   To create a B-tree index on the column <literal>title</literal> in
   the table <literal>films</literal>:
<programlisting>
CREATE UNIQUE INDEX title_idx ON films (title);
</programlisting>
  </para>

  <para>
   To create an index on the expression <literal>lower(title)</>,
   allowing efficient case-insensitive searches:
<programlisting>
CREATE INDEX ON films ((lower(title)));
</programlisting>
   (In this example we have chosen to omit the index name, so the system
   will choose a name, typically <literal>films_lower_idx</>.)
  </para>

  <para>
   To create an index with non-default sort ordering of nulls:
<programlisting>
CREATE INDEX title_idx_nulls_low ON films (title NULLS FIRST);
</programlisting>
  </para>

  <para>
   To create an index with non-default fill factor:
<programlisting>
CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70);
</programlisting>
  </para>

  <para>
   To create a <acronym>GIN</> index with fast updates disabled:
<programlisting>
CREATE INDEX gin_idx ON documents_table USING gin (locations) WITH (fastupdate = off);
</programlisting>
  </para>

  <para>
   To create an index on the column <literal>code</> in the table
   <literal>films</> and have the index reside in the tablespace
   <literal>indexspace</>:
<programlisting>
CREATE INDEX code_idx ON films (code) TABLESPACE indexspace;
</programlisting>
  </para>

  <para>
   To create a GiST index on a point attribute so that we
   can efficiently use box operators on the result of the
   conversion function:
<programlisting>
CREATE INDEX pointloc
    ON points USING gist (box(location,location));
SELECT * FROM points
    WHERE box(location,location) &amp;&amp; '(0,0),(1,1)'::box;
</programlisting>
  </para>

  <para>
   To create an index without locking out writes to the table:
<programlisting>
CREATE INDEX CONCURRENTLY sales_quantity_index ON sales_table (quantity);
</programlisting>
  </para>

 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   <command>CREATE INDEX</command> is a
   <productname>PostgreSQL</productname> language extension.  There
   are no provisions for indexes in the SQL standard.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-alterindex"></member>
   <member><xref linkend="sql-dropindex"></member>
  </simplelist>
 </refsect1>
</refentry>
@


1.74
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.73 2010/03/17 15:55:50 tgl Exp $
d560 1
a560 1
  <programlisting>
d565 1
a565 1
  </programlisting>
@


1.74.2.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.74 2010/04/03 07:22:58 petere Exp $
d560 1
a560 1
<programlisting>
d565 1
a565 1
</programlisting>
@


1.73
log
@Fix incorrect example in CREATE INDEX reference page, per Josh Kupershmidt.
Also fix and uncomment an old example of creating a GIST index, and make
a couple of other minor editorial adjustments.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.72 2009/12/23 17:41:43 tgl Exp $
d8 1
a8 1
  <refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
d491 1
a491 1
   Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
d591 2
a592 2
   <member><xref linkend="sql-alterindex" endterm="sql-alterindex-title"></member>
   <member><xref linkend="sql-dropindex" endterm="sql-dropindex-title"></member>
@


1.72
log
@Allow the index name to be omitted in CREATE INDEX, causing the system to
choose an index name the same as it would do for an unnamed index constraint.
(My recent changes to the index naming logic have helped to ensure that this
will be a reasonable choice.)  Per a suggestion from Peter.

A necessary side-effect is to promote CONCURRENTLY to type_func_name_keyword
status, ie, it can't be a table/column/index name anymore unless quoted.
This is not all bad, since we have heard more than once of people typing
CREATE INDEX CONCURRENTLY ON foo (...) and getting a normal index build of
an index named "concurrently", which was not what they wanted.  Now this
syntax will result in a concurrent build of an index with system-chosen
name; which they can rename afterwards if they want something else.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.71 2009/03/24 20:17:08 tgl Exp $
d269 4
a272 4
    The <literal>WITH</> clause can specify <firstterm>storage parameters</>
    for indexes.  Each index method can have its own set of allowed storage
    parameters.  The <literal>B-tree</literal>, <literal>hash</literal> and
    <literal>GiST</literal> built-in index methods all accept a single parameter:
d284 2
a285 1
      when extending the index at the right (largest key values).  If pages
d288 1
a288 1
      fillfactor of 90, but any value from 10 to 100 can be selected.
d301 1
a301 1
    <literal>GIN</literal> indexes accept a different parameter:
d377 1
a377 1
    <command>\d</> command will mark such an index as <literal>INVALID</>:
d461 2
a462 2
   FIRST</>, and/or <literal>NULLS LAST</> can be specified to reverse
   the normal sort direction of the index.  Since an ordered index can be
d543 1
a543 1
CREATE INDEX gin_idx ON documents_table (locations) WITH (fastupdate = off);
a555 4
<!--
<comment>
Is this example correct?
</comment>
d562 1
a562 1
    ON points USING GIST (point2box(location) box_ops);
d564 1
a564 1
    WHERE point2box(points.pointloc) = boxes.box;
a566 1
-->
@


1.71
log
@Implement "fastupdate" support for GIN indexes, in which we try to accumulate
multiple index entries in a holding area before adding them to the main index
structure.  This helps because bulk insert is (usually) significantly faster
than retail insert for GIN.

This patch also removes GIN support for amgettuple-style index scans.  The
API defined for amgettuple is difficult to support with fastupdate, and
the previously committed partial-match feature didn't really work with
it either.  We might eventually figure a way to put back amgettuple
support, but it won't happen for 8.4.

catversion bumped because of change in GIN's pg_am entry, and because
the format of GIN indexes changed on-disk (there's a metapage now,
and possibly a pending list).

Teodor Sigaev
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.70 2009/02/02 19:31:38 alvherre Exp $
d24 1
a24 1
CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">method</replaceable> ]
d36 2
a37 2
   <command>CREATE INDEX</command> constructs an index named <replaceable
   class="parameter">name</replaceable> on the specified table.
d135 3
a137 1
        table.
d519 1
a519 1
CREATE INDEX lower_title_idx ON films ((lower(title)));
d521 2
d551 1
a551 1
CREATE INDEX code_idx ON films(code) TABLESPACE indexspace;
@


1.71.2.1
log
@Fix incorrect example in CREATE INDEX reference page, per Josh Kupershmidt.
Also fix and uncomment an old example of creating a GIST index, and make
a couple of other minor editorial adjustments.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.71 2009/03/24 20:17:08 tgl Exp $
d267 4
a270 4
    The optional <literal>WITH</> clause specifies <firstterm>storage
    parameters</> for the index.  Each index method has its own set of allowed
    storage parameters.  The B-tree, hash and GiST index methods all accept a
    single parameter:
d282 1
a282 2
      when extending the index at the right (adding new largest key values).
      If pages
d285 1
a285 1
      fillfactor of 90, but any integer value from 10 to 100 can be selected.
d298 1
a298 1
    GIN indexes accept a different parameter:
d374 1
a374 1
    <command>\d</> command will report such an index as <literal>INVALID</>:
d458 2
a459 2
   FIRST</>, and/or <literal>NULLS LAST</> can be specified to modify
   the sort ordering of the index.  Since an ordered index can be
d538 1
a538 1
CREATE INDEX gin_idx ON documents_table USING gin (locations) WITH (fastupdate = off);
d551 4
d561 1
a561 1
    ON points USING gist (box(location,location));
d563 1
a563 1
    WHERE box(location,location) &amp;&amp; '(0,0),(1,1)'::box;
d566 1
@


1.70
log
@Allow reloption names to have qualifiers, initially supporting a TOAST
qualifier, and add support for this in pg_dump.

This allows TOAST tables to have user-defined fillfactor, and will also
enable us to move the autovacuum parameters to reloptions without taking
away the possibility of setting values for TOAST tables.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.69 2008/11/14 10:22:46 petere Exp $
d297 31
d536 7
@


1.69
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.68 2008/07/11 21:06:29 tgl Exp $
d234 2
a235 1
        below for details.
d269 2
a270 1
    parameters.  The built-in index methods all accept a single parameter:
@


1.68
log
@Multi-column GIN indexes.  Teodor Sigaev
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.67 2008/03/16 23:57:51 tgl Exp $
d9 1
@


1.67
log
@Add a note to the CREATE INDEX reference page about the impact of
maintenance_work_mem and effective_cache_size on index creation speed.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.66 2007/11/26 21:36:33 petere Exp $
d397 1
a397 1
   Currently, only the B-tree and GiST index methods support
d426 1
a426 1
   scanned either forward or backward, it is not normally useful to create a 
@


1.66
log
@Change index_name to name for consistency.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.65 2007/09/20 17:56:30 tgl Exp $
d35 1
a35 1
   <command>CREATE INDEX</command> constructs an index <replaceable
d437 17
@


1.65
log
@HOT updates.  When we update a tuple without changing any of its indexed
columns, and the new version can be stored on the same heap page, we no longer
generate extra index entries for the new version.  Instead, index searches
follow the HOT-chain links to ensure they find the correct tuple version.

In addition, this patch introduces the ability to "prune" dead tuples on a
per-page basis, without having to do a complete VACUUM pass to recover space.
VACUUM is still needed to clean up dead index entries, however.

Pavan Deolasee, with help from a bunch of other people.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.64 2007/09/07 00:58:56 tgl Exp $
d36 1
a36 1
   class="parameter">index_name</replaceable> on the specified table.
@


1.64
log
@Allow CREATE INDEX CONCURRENTLY to disregard transactions in other
databases, per gripe from hubert depesz lubaczewski.  Patch from
Simon Riggs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.63 2007/06/03 17:05:53 tgl Exp $
d332 4
a335 1
    If a problem arises during the second scan of the table, such as a
@


1.63
log
@Create a GUC parameter temp_tablespaces that allows selection of the
tablespace(s) in which to store temp tables and temporary files.  This is a
list to allow spreading the load across multiple tablespaces (a random list
element is chosen each time a temp object is to be created).  Temp files are
not stored in per-database pgsql_tmp/ directories anymore, but per-tablespace
directories.

Jaime Casanova and Albert Cervera, with review by Bernd Helmle and Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.62 2007/04/06 22:33:41 tgl Exp $
d311 1
a311 1
    a live production database. Large tables can take many hours to be
d322 2
a323 1
    addition it must wait for all existing transactions to terminate.  Thus
@


1.62
log
@Make 'col IS NULL' clauses be indexable conditions.

Teodor Sigaev, with some kibitzing from Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.61 2007/04/03 22:38:35 momjian Exp $
d243 3
a245 3
        <xref linkend="guc-default-tablespace"> is used, or the database's
        default tablespace if <varname>default_tablespace</> is an empty
        string.
@


1.61
log
@Document how to identify an invalid index after a failed CREATE INDEX
CONCURRENTLY.

Gregory Stark
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.60 2007/01/31 23:26:03 momjian Exp $
a437 6
   Indexes are not used for <literal>IS NULL</> clauses by default.
   The best way to use indexes in such cases is to create a partial index
   using an <literal>IS NULL</> predicate.
  </para>

  <para>
@


1.60
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.59 2007/01/09 02:14:10 tgl Exp $
d335 14
a348 1
    however it will still consume update overhead.  The recommended recovery
@


1.59
log
@Support ORDER BY ... NULLS FIRST/LAST, and add ASC/DESC/NULLS FIRST/NULLS LAST
per-column options for btree indexes.  The planner's support for this is still
pretty rudimentary; it does not yet know how to plan mergejoins with
nondefault ordering options.  The documentation is pretty rudimentary, too.
I'll work on improving that stuff later.

Note incompatible change from prior behavior: ORDER BY ... USING will now be
rejected if the operator is not a less-than or greater-than member of some
btree opclass.  This prevents less-than-sane behavior if an operator that
doesn't actually define a proper sort ordering is selected.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.58 2006/09/16 00:30:17 momjian Exp $
d78 1
a78 1
    The expression used in the <literal>WHERE</literal> clause may refer
d175 1
a175 1
        as shown in the syntax.  However, the parentheses may be omitted
d327 1
a327 1
    and I/O load imposed by the index creation may slow other operations.
d334 1
a334 1
    will be ignored for querying purposes because it may be incomplete;
d381 1
a381 1
   multicolumn indexes. Up to 32 fields may be specified by default.
@


1.58
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.57 2006/09/13 23:42:26 tgl Exp $
d24 1
a24 1
    ( { <replaceable class="parameter">column</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] )
d191 38
d405 15
d460 7
@


1.57
log
@Some small editorialization on the description of CREATE INDEX
CONCURRENTLY.  Greg Stark, some further tweaks by me.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.56 2006/08/25 04:06:45 tgl Exp $
a466 17

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
@


1.56
log
@Add the ability to create indexes 'concurrently', that is, without
blocking concurrent writes to the table.  Greg Stark, with a little help
from Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.55 2006/07/11 21:05:57 tgl Exp $
d267 1
a267 7
    Creating an index for a large table can be a long operation. In large data
    warehousing applications it can easily take hours or even days to build
    indexes. It's important to understand the impact creating indexes has on a
    system.
   </para>

   <para>
d272 4
a275 1
    index build is finished.
d279 1
a279 1
    <productname>PostgreSQL</> also supports building indexes without locking
@


1.55
log
@Tweak fillfactor code as per my recent proposal.  Fix nbtsort.c so that
it can handle small fillfactors for ordinary-sized index entries without
failing on large ones; fix nbtinsert.c to distinguish leaf and nonleaf
pages; change the minimum fillfactor to 10% for all index types.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.54 2006/07/04 18:07:24 tgl Exp $
d23 1
a23 1
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">method</replaceable> ]
d114 15
d257 76
a432 1
  </para>
d439 1
d442 7
@


1.54
log
@Documentation fixes for FILLFACTOR patch.  Minor other editorialization.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.53 2006/07/02 02:23:17 momjian Exp $
d224 1
a224 1
      the index method will try to pack index pages.  For B-trees, pages
d229 1
a229 1
      fillfactor of 90, but any value from 70 to 100 can be selected.
d234 1
a234 1
      ways; the default fillfactor and allowed range varies.
@


1.53
log
@Add FILLFACTOR to CREATE INDEX.

ITAGAKI Takahiro
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.52 2005/11/07 17:36:44 tgl Exp $
d25 1
a25 1
    [ WITH (FILLFACTOR = <replaceable>fillfactor</replaceable>) ]
d59 1
a59 1
   B-tree, hash, and GiST.  Users can also define their own index
d139 1
a139 1
        and <literal>gist</literal>.  The
d176 1
a176 1
      <term><replaceable class="parameter">fillfactor</replaceable></term>
d179 2
a180 1
        The index's fillfactor in percentage.
d207 35
d311 15
@


1.52
log
@R-tree is dead ... long live GiST.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.51 2005/01/04 00:39:53 tgl Exp $
d25 1
d176 9
@


1.51
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.50 2004/11/05 19:15:51 tgl Exp $
d37 1
a37 1
   inappropriate use will result in slower performance).
d58 1
a58 5
   B-tree, R-tree, hash, and GiST. The B-tree index method is an
   implementation of Lehman-Yao high-concurrency B-trees. The R-tree
   index method implements standard R-trees using Guttman's quadratic
   split algorithm. The hash index method is an implementation of
   Litwin's linear hashing.  Users can also define their own index
d136 1
a136 1
        The name of the method to be used for the index.  Choices are
d138 1
a138 1
        <literal>rtree</literal>, and <literal>gist</literal>.  The
d242 9
d278 1
a278 1
   To create a R-tree index on a point attribute so that we
d284 1
a284 1
    ON points USING RTREE (point2box(location) box_ops);
@


1.50
log
@Create 'default_tablespace' GUC variable that supplies a TABLESPACE
clause implicitly whenever one is not given explicitly.  Remove concept
of a schema having an associated tablespace, and simplify the rules for
selecting a default tablespace for a table or index.  It's now just
(a) explicit TABLESPACE clause; (b) default_tablespace if that's not an
empty string; (c) database's default.  This will allow pg_dump to use
SET commands instead of tablespace clauses to determine object locations
(but I didn't actually make it do so).  All per recent discussions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.49 2004/07/12 01:22:53 momjian Exp $
d77 1
a77 7
    table.
  </para>

  <para>
   Indexes are not used for <literal>IS NULL</> clauses by default.
   The best way to use indexes in such cases is to create a partial index
   using an <literal>IS NULL</> comparison.
d208 1
a208 1
   can be useful.
d240 6
d296 9
@


1.49
log
@Tablespace examples for CREATE TABLE/INDEX/SCHEMA/DATABASE as well as
some other examples for CREATE DATABASE.

Gavin Sherry
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.48 2004/06/18 06:13:05 tgl Exp $
d189 3
a191 1
        the tablespace of the parent table is used.
@


1.48
log
@Tablespaces.  Alternate database locations are dead, long live tablespaces.

There are various things left to do: contrib dbsize and oid2name modules
need work, and so does the documentation.  Also someone should think about
COMMENT ON TABLESPACE and maybe RENAME TABLESPACE.  Also initlocation is
dead, it just doesn't know it yet.

Gavin Sherry and Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.47 2004/04/20 12:53:28 momjian Exp $
d254 9
@


1.47
log
@Improve IS NULL partial index wording.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.46 2004/04/20 04:25:47 momjian Exp $
d25 1
d82 1
a82 1
   The best way to use indexes in such cases is to create a partial index 
d113 5
a117 5
	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.
d126 3
a128 3
	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.
d137 1
a137 1
	The name (possibly schema-qualified) of the table to be indexed.
d158 1
a158 1
	The name of a column of the table.
d167 4
a170 4
	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 may be omitted
	if the expression has the form of a function call.
d179 11
a189 1
	The name of an operator class. See below for details.
d198 1
a198 1
	The constraint expression for a partial index.
d202 1
d275 1
a275 1
 
@


1.46
log
@Document partial indexes for IS NULL lookups.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.45 2004/04/20 01:00:26 momjian Exp $
d80 1
a80 1
   Indexes can not be used with <literal>IS NULL</> clauses by default.
@


1.45
log
@> >> My question is whether postgres can index null values, and if not, do I
> >> have to accept a full table scan when locating records.
> >
> > It indexes them, but "is null" is not an indexable operator, so you
> > can't directly solve the above with a 3-column index.  What you can do
> > instead is use a partial index, for instance
> >
> > create index i on CUSTOMER.WCCustOrderStatusLog (WCOrderStatusID)
> > where Acknowledged is null and Processing is null;
>
> That's a very nifty trick and exactly the sort of answer I was after!

Add CREATE INDEX doc mention of using partial indexes for IS NULL
indexing;  idea from Tom.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.44 2003/11/29 19:51:38 pgsql Exp $
d80 3
a82 5
   <literal>NULL</> values are not indexed by default.  The best way
   to index <literal>NULL</> values is to create a partial index using
   an <literal>IS NULL</> comparison.  <literal>IS NULL</> is more
   of a function call than a value comparison, and this is why a partial
   index works.
@


1.44
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.43 2003/09/22 00:16:57 petere Exp $
d69 1
a69 1
    a table, usually a portion that is somehow more interesting than the
d80 8
d89 2
a90 2
    only to columns of the underlying table (but it can use all columns,
    not only the one(s) being indexed).  Presently, subqueries and
@


1.43
log
@Make the SQL command synopses appear less random.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.42 2003/09/11 21:42:20 momjian Exp $
@


1.42
log
@This patch fixes a few missed GUC variables that were still upper case,
makes a few more small improvements to runtime.sgml, and makes some SGML
conventions more consistent.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.41 2003/09/09 18:28:52 tgl Exp $
d23 1
a23 1
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">method</replaceable> ]
d116 1
a116 1
      <term><replaceable class="parameter">index_name</replaceable></term>
@


1.41
log
@Remove a bunch of content-free Diagnostics sections, as per previous
discussion.  (Still have some work to do editing the remainder.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.40 2003/08/31 17:32:22 petere Exp $
d56 1
a56 1
   <application>PostgreSQL</application> provides the index methods
d201 1
a201 1
   <application>PostgreSQL</application>.)  Only B-tree currently
@


1.40
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.39 2003/05/28 16:03:55 tgl Exp $
a185 15
 </refsect1>

 <refsect1>
  <title>Diagnostics</title>

  <variablelist>
   <varlistentry>
    <term><computeroutput>CREATE INDEX</computeroutput></term>
    <listitem>
     <para>
      Message returned if the index was successfully created.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
@


1.39
log
@Replace functional-index facility with expressional indexes.  Any column
of an index can now be a computed expression instead of a simple variable.
Restrictions on expressions are the same as for predicates (only immutable
functions, no sub-selects).  This fixes problems recently introduced with
inlining SQL functions, because the inlining transformation is applied to
both expression trees so the planner can still match them up.  Along the
way, improve efficiency of handling index predicates (both predicates and
index expressions are now cached by the relcache) and fix 7.3 oversight
that didn't record dependencies of predicate expressions.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.38 2003/04/22 10:08:08 petere Exp $
d16 4
@


1.39.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.40 2003/08/31 17:32:22 petere Exp $
a15 4

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


1.38
log
@More editing of reference pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.37 2002/09/21 18:32:54 petere Exp $
d19 2
a20 6
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
    [ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
    [ WHERE <replaceable class="parameter">predicate</replaceable> ]

CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
    [ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
d31 2
a32 2
   Indexes are primarily used to enhance database performance.  But
   inappropriate use will result in slower performance.
d36 2
a37 2
   In the first syntax shown above, the key field(s) for the
   index are specified as column names.
d43 4
a46 7
   In the second syntax shown above, an index is defined on the result
   of a user-specified function <replaceable
   class="parameter">func_name</replaceable> applied to one or more
   columns of a single table. These <firstterm>functional
   indexes</firstterm> can be used to obtain fast access to data based
   on operators that would normally require some transformation to apply
   them to the base data. For example, a functional index on
d80 1
d89 2
a90 2
   user-defined function in an index, remember to mark the function immutable
   when you create it.
d153 1
a153 1
      <term><replaceable class="parameter">ops_name</replaceable></term>
d156 4
a159 1
	An associated operator class. See below for details.
d165 1
a165 1
      <term><replaceable class="parameter">func_name</replaceable></term>
d168 1
a168 1
	A function, which returns a value that can be indexed.
d177 1
a177 1
	Defines the constraint expression for a partial index.
@


1.37
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.36 2002/08/13 20:40:43 momjian Exp $
d11 1
d13 2
a14 6
  <refname>
   CREATE INDEX
  </refname>
  <refpurpose>
   define a new index
  </refpurpose>
d16 1
d18 1
a18 4
  <refsynopsisdivinfo>
   <date>2001-07-15</date>
  </refsynopsisdivinfo>
  <synopsis>
d20 1
a20 1
    [ USING <replaceable class="parameter">acc_method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
d22 1
d24 1
a24 1
    [ USING <replaceable class="parameter">acc_method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
d26 31
a56 1
  </synopsis>
d58 44
a101 8
  <refsect2 id="R2-SQL-CREATEINDEX-1">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
d105 1
a105 1
      <term>UNIQUE</term>
d138 1
a138 1
      <term><replaceable class="parameter">acc_method</replaceable></term>
d141 4
a144 43
	The name of the access method to be used for the index. The
	default access method is <literal>BTREE</literal>.
	<application>PostgreSQL</application> provides four access
	methods for indexes:

	<variablelist>
	 <varlistentry>
	  <term><literal>BTREE</></term>
	  <listitem>
	   <para>
	    an implementation of Lehman-Yao
	    high-concurrency B-trees.
	   </para>
	  </listitem>
	 </varlistentry>

	 <varlistentry>
	  <term><literal>RTREE</></term>
	  <listitem>
	   <para>implements standard R-trees using Guttman's
	    quadratic split algorithm.
	   </para>
	  </listitem>
	 </varlistentry>

	 <varlistentry>
	  <term><literal>HASH</></term>
	  <listitem>
	   <para>
	    an implementation of Litwin's linear hashing.
	   </para>
	  </listitem>
	 </varlistentry>

	 <varlistentry>
	  <term><literal>GIST</></term>
	  <listitem>
	   <para>
	    Generalized Index Search Trees.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
d185 1
a185 2
   </para>
  </refsect2>
d187 2
a188 8
  <refsect2 id="R2-SQL-CREATEINDEX-2">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
d190 11
a200 11
    <variablelist>
     <varlistentry>
      <term><computeroutput>
CREATE INDEX
       </computeroutput></term>
      <listitem>
       <para>
	The message returned if the index is successfully created.
       </para>
      </listitem>
     </varlistentry>
d202 2
a203 86
     <varlistentry>
      <term><computeroutput>
ERROR: Cannot create index: 'index_name' already exists.
       </computeroutput></term>
      <listitem>
       <para>
	This error occurs if it is impossible to create the index.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-CREATEINDEX-1">
  <refsect1info>
   <date>1998-09-09</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>CREATE INDEX</command> constructs an index 
   <replaceable class="parameter">index_name</replaceable>
   on the specified <replaceable class="parameter">table</replaceable>.

   <tip>
    <para>
     Indexes are primarily used to enhance database performance.
     But inappropriate use will result in slower performance.
    </para>
   </tip>
  </para>

  <para>
   In the first syntax shown above, the key field(s) for the
   index are specified as column names.
   Multiple fields can be specified if the index access method supports
   multicolumn indexes.
  </para>

  <para>
   In the second syntax shown above, an index is defined on the result
   of a user-specified function <replaceable
   class="parameter">func_name</replaceable> applied to one or more
   columns of a single table. These <firstterm>functional
   indexes</firstterm> can be used to obtain fast access to data based
   on operators that would normally require some transformation to apply
   them to the base data. For example, a functional index on
   <literal>upper(col)</> would allow the clause
   <literal>WHERE upper(col) = 'JIM'</> to use an index.
  </para>

  <para>
   <application>PostgreSQL</application> provides B-tree, R-tree, hash,
   and GiST access methods for indexes. The B-tree access method is an
   implementation of Lehman-Yao high-concurrency B-trees. The R-tree
   access method implements standard R-trees using Guttman's quadratic
   split algorithm. The hash access method is an implementation of
   Litwin's linear hashing. We mention the algorithms used solely to
   indicate that all of these access methods are fully dynamic and do
   not have to be optimized periodically (as is the case with, for
   example, static hash access methods).
  </para>

  <para>
    When the <command>WHERE</command> 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 somehow more interesting 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 <command>WHERE</command> with
    <command>UNIQUE</command> to enforce uniqueness over a subset of a
    table.
  </para>

  <para>
    The expression used in the <command>WHERE</command> clause may refer
    only to columns of the underlying table (but it can use all columns,
    not only the one(s) being indexed).  Presently, subqueries and
    aggregate expressions are also forbidden in <command>WHERE</command>.
  </para>
d206 3
a208 7
   All functions and operators used in an index definition must be
   <firstterm>immutable</>, that is, their results must depend only on
   their input 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, remember to mark the function immutable
   when you create it.
d212 5
a216 2
   Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
   to remove an index.
a218 60
  <refsect2 id="R2-SQL-CREATEINDEX-3">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    Notes
   </title>

   <para>
    The <productname>PostgreSQL</productname>
    query optimizer will consider using a B-tree index whenever
    an indexed attribute is involved in a comparison using one of:

    <simplelist type="inline">
     <member>&lt;</member>
     <member>&lt;=</member>
     <member>=</member>
     <member>&gt;=</member>
     <member>&gt;</member>
    </simplelist>
   </para>

   <para>
    The <productname>PostgreSQL</productname>
    query optimizer will consider using an R-tree index whenever
    an indexed attribute is involved in a comparison using one of:

    <simplelist type="inline">
     <member>&lt;&lt;</member>
     <member>&amp;&lt;</member>
     <member>&amp;&gt;</member>
     <member>&gt;&gt;</member>
     <member>@@</member>
     <member>~=</member>
     <member>&amp;&amp;</member>
    </simplelist>
   </para>

   <para>
    The <productname>PostgreSQL</productname>
    query optimizer will consider using a hash index whenever
    an indexed attribute is involved in a comparison using
    the <literal>=</literal> operator.
   </para>
   <para>
     Testing has shown PostgreSQL's hash indexes to be similar or slower
     than B-tree indexes, and the index size and build time for hash
     indexes is much worse. Hash indexes also suffer poor performance
     under high concurrency. For these reasons, hash index use is
     discouraged.
   </para>

   <para>
    Currently, only the B-tree and gist access methods support multicolumn
    indexes. Up to 32 keys may be specified by default (this limit
    can be altered when building
    <application>PostgreSQL</application>).  Only B-tree currently supports
    unique indexes.
   </para>

d225 1
a225 1
   integers. In practice the default operator class for the field's data
d231 4
a234 2
   the proper class when making an index. There are also some operator
   classes with special purposes:
d236 3
a238 15
   <itemizedlist>
    <listitem>
     <para>
      The operator classes <literal>box_ops</literal> and
      <literal>bigbox_ops</literal> both support R-tree indexes on the
      <literal>box</literal> data type.
      The difference between them is that <literal>bigbox_ops</literal>
      scales box coordinates down, to avoid floating-point exceptions from
      doing multiplication, addition, and subtraction on very large
      floating-point coordinates.  (Note: this was true some time ago,
      but currently the two operator classes both use floating point
      and are effectively identical.)
     </para>
    </listitem>
   </itemizedlist>
d240 1
d242 2
a243 2
   <para>
    The following query shows all defined operator classes:
d245 6
a250 17
    <programlisting>
SELECT am.amname AS acc_method,
       opc.opcname AS ops_name
    FROM pg_am am, pg_opclass opc
    WHERE opc.opcamid = am.oid
    ORDER BY acc_method, ops_name;
    </programlisting>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-CREATEINDEX-2">
  <title>
   Usage
  </title>
  <para>To create a B-tree index on the field <literal>title</literal>
   in the table <literal>films</literal>:
a251 4
  <programlisting>
CREATE UNIQUE INDEX title_idx
    ON films (title);
  </programlisting>
d272 8
a279 19
 <refsect1 id="R1-SQL-CREATEINDEX-3">
  <title>
   Compatibility
  </title>
  
  <refsect2 id="R2-SQL-CREATEINDEX-4">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    CREATE INDEX is a <productname>PostgreSQL</productname> language extension.
   </para>
   <para>
    There is no <command>CREATE INDEX</command> command in SQL92.
   </para>
  </refsect2>
@


1.36
log
@Change NAMEDATALEN to 64,  INDEX_MAX_KEYS/MAX_FUNC_ARGS to 32, per discussion on hackers.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_index.sgml,v 1.35 2002/07/30 17:34:37 tgl Exp $
d269 1
a269 1
    not only the one(s) being indexed).  Presently, sub-SELECTs and
d334 1
a334 1
     than btree indexes, and the index size and build time for hash
@


1.35
log
@Replace ad-hoc insertions into pg_opclass and friends with CREATE
OPERATOR CLASS commands.  Further tweaking of documentation for same.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.34 2002/06/21 19:06:44 momjian Exp $
d342 1
a342 1
    indexes. Up to 16 keys may be specified by default (this limit
@


1.34
log
@Mention "PostgreSQL"'s hashes as slower/similar to btree.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.33 2002/06/21 16:52:00 momjian Exp $
d385 4
a388 7
       opc.opcname AS ops_name,
       opr.oprname AS ops_comp
    FROM pg_am am, pg_opclass opc, pg_amop amop, pg_operator opr
    WHERE opc.opcamid = am.oid AND
          amop.amopclaid = opc.oid AND
          amop.amopopr = opr.oid
    ORDER BY acc_method, ops_name, ops_comp;
@


1.33
log
@Update hash warning in manual.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.32 2002/06/21 03:25:53 momjian Exp $
d333 5
a337 4
     Testing has shown hash indexes to be similar or slower than btree
     indexes, and the index size and build time for hash indexes is much
     worse. Hash indexes also suffer poor performance under high
     concurrency. For these reasons, hash index use is discouraged.
@


1.32
log
@Document problems with hash indexes compared to btree.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.31 2002/05/18 15:44:47 petere Exp $
d333 4
a336 3
     Testing has shown that hash indexes are slower than btree indexes,
     and the size and build time for hash indexes is much worse. For
     these reasons, hash index use is discouraged.
@


1.31
log
@Revise command completion tags as per hackers message on 20 March.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.30 2002/04/23 02:07:15 tgl Exp $
d331 5
@


1.30
log
@Update SQL-command reference pages for schema features.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.29 2002/04/21 19:02:39 thomas Exp $
d177 1
a177 1
CREATE
@


1.29
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.28 2002/04/11 23:20:04 momjian Exp $
d59 3
a61 1
	The name of the index to be created.
d70 1
a70 1
	The name of the table to be indexed.
d275 1
a275 1
   <firstterm>cacheable</>, that is, their results must depend only on
d279 1
a279 1
   user-defined function in an index, remember to mark the function cacheable
@


1.28
log
@Add mention of function CREATE INDEX usage.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.27 2002/03/22 19:20:38 petere Exp $
d8 1
a8 3
  <refentrytitle id="sql-createindex-title">
   CREATE INDEX
  </refentrytitle>
@


1.27
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.26 2002/01/20 22:19:56 petere Exp $
d79 4
a82 3
	The name of the access method to be used for
	the index. The default access method is <literal>BTREE</literal>.
	<application>PostgreSQL</application> provides four access methods for indexes:
d229 9
a237 8
   In the second syntax shown above, an index is defined
   on the result of a user-specified function
   <replaceable class="parameter">func_name</replaceable> applied
   to one or more columns of a single table.
   These <firstterm>functional indexes</firstterm>
   can be used to obtain fast access to data
   based on operators that would normally require some
   transformation to apply them to the base data.
d241 9
a249 9
   <application>PostgreSQL</application> provides B-tree, R-tree, hash, and GiST access methods for
   indexes.  The B-tree access method is an implementation of
   Lehman-Yao high-concurrency B-trees.  The R-tree access method
   implements standard R-trees using Guttman's quadratic split algorithm.
   The hash access method is an implementation of Litwin's linear
   hashing.  We mention the algorithms used solely to indicate that all
   of these access methods are fully dynamic and do not have to be
   optimized periodically (as is the case with, for example, static hash
   access methods).
d343 2
a344 2
   column of an index.  The operator class identifies the operators to
   be used by the index for that column.  For example, a B-tree index on
d347 2
a348 2
   integers.  In practice the default operator class for the field's
   data type is usually sufficient.  The main point of having operator classes
d350 5
a354 5
   ordering.  For example, we might want to sort a complex-number data type
   either by absolute value or by real part.  We could do this by defining
   two operator classes for the data type and then selecting the proper
   class when making an index.  There are also some operator classes with
   special purposes:
@


1.26
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.25 2001/12/08 03:24:34 thomas Exp $
d85 1
a85 1
	  <term>BTREE</term>
d95 1
a95 1
	  <term>RTREE</term>
d104 1
a104 1
	  <term>HASH</term>
d113 1
a113 1
	  <term>GIST</term>
d273 1
a273 1
   <firstterm>cachable</>, that is, their results must depend only on
d277 1
a277 1
   user-defined function in an index, remember to mark the function cachable
d332 1
a332 1
    Currently, only the B-tree and gist access methods support multi-column
@


1.25
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.24 2001/09/14 08:05:55 ishii Exp $
d80 1
a80 1
	the index. The default access method is BTREE.
d89 1
a89 1
	    high-concurrency btrees.
d97 1
a97 1
	   <para>implements standard rtrees using Guttman's
d224 1
a224 1
   multi-column indexes.
d239 4
a242 4
   <application>PostgreSQL</application> provides btree, rtree, hash, and GiST access methods for
   indexes.  The btree access method is an implementation of
   Lehman-Yao high-concurrency btrees.  The rtree access method
   implements standard rtrees using Guttman's quadratic split algorithm.
d296 1
a296 1
    query optimizer will consider using a btree index whenever
d310 1
a310 1
    query optimizer will consider using an rtree index whenever
d332 1
a332 1
    Currently, only the btree and gist access methods support multi-column
d335 1
a335 1
    <application>PostgreSQL</application>).  Only btree currently supports
d342 1
a342 1
   be used by the index for that column.  For example, a btree index on
d358 1
a358 1
      <literal>bigbox_ops</literal> both support rtree indexes on the
d392 1
a392 1
  <para>To create a btree index on the field <literal>title</literal>
d405 1
a405 1
   To create a rtree index on a point attribute so that we
@


1.24
log
@Add semicolon
@
text
@d2 2
a3 2
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.23 2001/09/03 12:57:49 petere Exp $
Postgres documentation
d81 1
a81 1
	Postgres provides four access methods for indexes:
d239 1
a239 1
   Postgres provides btree, rtree, hash, and GiST access methods for
d295 1
a295 1
    The <productname>Postgres</productname>
d309 1
a309 1
    The <productname>Postgres</productname>
d325 1
a325 1
    The <productname>Postgres</productname>
d334 2
a335 1
    can be altered when building Postgres).  Only btree currently supports
d432 1
a432 1
    CREATE INDEX is a <productname>Postgres</productname> language extension.
@


1.23
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.22 2001/08/21 16:35:59 tgl Exp $
d381 1
a381 1
    ORDER BY acc_method, ops_name, ops_comp
@


1.22
log
@Restructure pg_opclass, pg_amop, and pg_amproc per previous discussions in
pgsql-hackers.  pg_opclass now has a row for each opclass supported by each
index AM, not a row for each opclass name.  This allows pg_opclass to show
directly whether an AM supports an opclass, and furthermore makes it possible
to store additional information about an opclass that might be AM-dependent.
pg_opclass and pg_amop now store "lossy" and "haskeytype" information that we
previously expected the user to remember to provide in CREATE INDEX commands.
Lossiness is no longer an index-level property, but is associated with the
use of a particular operator in a particular index opclass.

Along the way, IndexSupportInitialize now uses the syscaches to retrieve
pg_amop and pg_amproc entries.  I find this reduces backend launch time by
about ten percent, at the cost of a couple more special cases in catcache.c's
IndexScanOK.

Initial work by Oleg Bartunov and Teodor Sigaev, further hacking by Tom Lane.

initdb forced.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.21 2001/08/06 18:09:45 tgl Exp $
d18 1
a18 1
   Constructs a secondary index
@


1.21
log
@Modify partial-index-predicate applicability tester to test whether
clauses are equal(), before trying to match them up using btree opclass
inference rules.  This allows it to recognize many simple cases involving
non-btree operations, for example 'x IS NULL'.  Clean up code a little.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.20 2001/07/16 05:06:57 tgl Exp $
d377 2
a378 3
    FROM pg_am am, pg_amop amop,
         pg_opclass opc, pg_operator opr
    WHERE amop.amopid = am.oid AND
@


1.20
log
@Partial indexes work again, courtesy of Martijn van Oosterhout.
Note: I didn't force an initdb, figuring that one today was enough.
However, there is a new function in pg_proc.h, and pg_dump won't be
able to dump partial indexes until you add that function.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.19 2001/05/17 21:50:18 petere Exp $
d259 3
d267 12
a278 10
    not only the one(s) being indexed).  Currently, the
    <productname>PostgreSQL</productname> planner can only devise query
    plans that make use of a partial index when the predicate is built from
    <command>AND</command> and <command>OR</command> combinations of
    elements of the form
    <firstterm>column</firstterm>
    <firstterm>operator</firstterm>
    <firstterm>constant</firstterm>.
    However, more general predicates may still be useful in conjunction
    with UNIQUE indexes, to enforce uniqueness over a subset of a table.
@


1.19
log
@Change "indices" to "indexes", per OED.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.18 2001/01/13 23:58:55 petere Exp $
d23 1
a23 1
   <date>1999-07-20</date>
d27 2
a28 1
    [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
d30 2
a31 1
    [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
d76 1
a76 1
      <term><replaceable class="parameter">acc_name</replaceable></term>
d81 1
a81 1
	Postgres provides three access methods for indexes:
d111 9
d151 9
d239 1
a239 1
   Postgres provides btree, rtree and hash access methods for
d251 26
d327 1
a327 1
    Currently, only the btree access method supports multi-column
d329 2
a330 1
    can be altered when building Postgres).
d357 3
a359 3
      floating-point coordinates.  If the field on which your rectangles lie
      is about 20,000 units square or larger, you should use
      <literal>bigbox_ops</literal>.
d369 1
a369 1
SELECT am.amname AS acc_name,
d377 1
a377 1
    ORDER BY acc_name, ops_name, ops_comp
@


1.18
log
@Terminology cleanup: class -> table, instance -> row, attribute -> column,
etc.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.17 2000/12/25 23:15:26 petere Exp $
d212 1
a212 1
   These <firstterm>functional indices</firstterm>
d220 1
a220 1
   indices.  The btree access method is an implementation of
d305 1
a305 1
      <literal>bigbox_ops</literal> both support rtree indices on the
@


1.17
log
@Refine some things to create better looking man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.16 2000/10/05 19:48:17 momjian Exp $
d211 1
a211 1
   to one or more attributes of a single class.
@


1.16
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.15 2000/09/12 20:52:08 momjian Exp $
d231 1
a231 1
   Use <xref linkend="sql-dropindex-title" endterm="sql-dropindex-title">
@


1.15
log
@datatype -> data type.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.14 2000/06/19 03:54:15 tgl Exp $
d308 1
a308 1
      scales box coordinates down, to avoid floating point exceptions from
@


1.14
log
@Clean up bogosities in pg_opclass, pg_amop, pg_amproc.  There are amproc
entries now for int8 and network hash indexes.  int24_ops and int42_ops
are gone.  pg_opclass no longer contains multiple entries claiming to be
the default opclass for the same datatype.  opr_sanity regress test
extended to catch errors like these in the future.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.13 2000/05/02 20:02:03 thomas Exp $
d293 3
a295 3
   datatype is usually sufficient.  The main point of having operator classes
   is that for some datatypes, there could be more than one meaningful
   ordering.  For example, we might want to sort a complex-number datatype
d297 1
a297 1
   two operator classes for the datatype and then selecting the proper
d306 1
a306 1
      <literal>box</literal> datatype.
@


1.13
log
@Fixups in content and markup for 7.0 release.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.12 2000/04/23 02:08:33 tgl Exp $
a312 11
     </para>
    </listitem>

    <listitem>
     <para>
      The <literal>int24_ops</literal>
      operator class is useful for constructing indices on int2 data, and
      doing comparisons against int4 data in query qualifications.
      Similarly, <literal>int42_ops</literal>
      support indices on int4 data that is to be compared against int2 data
      in queries.
@


1.12
log
@Update obsolete info in CREATE INDEX ref page.  (I had fixed the text
description in indices.sgml, but missed the near-duplicate prose in
the reference page...)
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.11 2000/04/11 05:39:15 thomas Exp $
d230 5
a345 5

   <para>
    Use <xref linkend="sql-dropindex-title" endterm="sql-dropindex-title">
    to remove an index.
   </para>
@


1.11
log
@Update porting list.
Fix markup to get clean compile.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.10 2000/03/16 14:39:30 thomas Exp $
d27 1
a27 1
    [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable>] [, ...] )
d29 1
a29 1
    [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">col</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
d77 1
a77 1
	the name of the access method which is to be used for
d79 1
a79 1
	Postgres provides three access methods for secondary indexes:
d86 1
a86 1
	    an implementation of the Lehman-Yao
d136 1
a136 2
	A user-defined function, which returns a value that can
	be indexed.
d201 4
a204 10
   In the first syntax shown above, the key fields for the
   index are specified as column names; a column may also have
   an associated operator class. An operator class is used
   to specify the operators to be used for a particular
   index. For example, a btree index on four-byte integers
   would use the <literal>int4_ops</literal> class;
   this operator class includes
   comparison functions for four-byte integers. The default
   operator class is the appropriate operator class for that
   field type.
d209 1
a209 1
   on the result of a user-defined function
d220 2
a221 2
   secondary indices.  The btree access method is an implementation of
   the Lehman-Yao high-concurrency btrees.  The rtree access method
d239 3
a241 2
    The Postgres query optimizer will consider using btree indices in a scan
    whenever an indexed attribute is involved in a comparison using one of:
a252 13
    Both box classes support indices on the <literal>box</literal> data 
    type in <productname>Postgres</productname>.
    The difference between them is that <literal>bigbox_ops</literal>
    scales box coordinates down, to avoid floating point exceptions from
    doing multiplication, addition, and subtraction on very large
    floating-point coordinates.  If the field on which your rectangles lie
    is about 20,000 units square or larger, you should use
    <literal>bigbox_ops</literal>.
    The <literal>poly_ops</literal> operator class supports rtree
    indices on <literal>polygon</literal> data.
   </para>

   <para>
d276 3
a278 2
    Currently, only the BTREE access method supports multi-column
    indexes. Up to 7 keys may be specified.
d281 42
a322 4
   <para>
    Use <xref linkend="sql-dropindex-title" endterm="sql-dropindex-title">
    to remove an index.
   </para>
d325 1
a325 10
    The <literal>int24_ops</literal>
    operator class is useful for constructing indices on int2 data, and
    doing comparisons against int4 data in query qualifications.
    Similarly, <literal>int42_ops</literal>
    support indices on int4 data that is to be compared against int2 data
    in queries.
   </para>

   <para>
    The following select list returns all ops_names:
d341 5
@


1.10
log
@Fix typo (introduced by xemacs markup normalization) in the syntax summary.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $
d49 2
a50 2
	insert or update non-duplicate data will generate an
	error.
@


1.9
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d29 1
a29 1
    [ USING <replaceable class="parameter">acc_name</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">r">col</replaceable>le> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
@


1.8
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 5
d8 1
a8 1
  <refentrytitle>
d23 1
a23 1
   <date>1998-09-09</date>
d26 4
a29 6
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
    ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ]
    ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable>] [, ...] )
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
    ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">acc_name</replaceable> ]
    ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">r">col</replaceable>le> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
d54 1
d63 1
d72 1
d80 1
d91 1
d100 1
a109 1

d122 1
d127 1
a127 14
	An associated operator class.
	The following select list returns all ops_names:

	<programlisting>
SELECT am.amname AS acc_name,
       opc.opcname AS ops_name,
       opr.oprname AS ops_comp
    FROM pg_am am, pg_amop amop,
         pg_opclass opc, pg_operator opr
    WHERE amop.amopid = am.oid AND
          amop.amopclaid = opc.oid AND
          amop.amopopr = opr.oid
    ORDER BY acc_name, ops_name, ops_comp
	</programlisting>
d131 1
d190 2
a191 3
   <replaceable class="parameter">index_name</replaceable>.
   on the specified
   <replaceable class="parameter">table</replaceable>.
d200 1
d213 1
d215 1
a215 1
   In the second syntax, an index is defined
d218 3
a220 2
   to one or more attributes of a single class. These functional
   indexes can be used to obtain fast access to data
d225 12
d244 50
d298 1
d300 1
a300 1
    Use <command>DROP INDEX</command>
d303 25
a365 2
  <para>
  </para>
@


1.7
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d1 3
a3 3
<REFENTRY ID="SQL-CREATEINDEX">
 <REFMETA>
  <REFENTRYTITLE>
d5 5
a9 5
  </REFENTRYTITLE>
  <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
d11 2
a12 2
  </REFNAME>
  <REFPURPOSE>
d14 1
a14 1
  </REFPURPOSE>
d16 5
a20 5
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-09</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
d26 8
a33 8
    ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
  </SYNOPSIS>
  
  <REFSECT2 ID="R2-SQL-CREATEINDEX-1">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d35 87
a121 96
   </TITLE>
   <PARA>
       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	  UNIQUE
	 </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 non-duplicate data will generate an
	   error.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	  <replaceable class="parameter">index_name</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   The name of the index to be created.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	  <replaceable class="parameter">table</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   The name of the table to be indexed.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	  <replaceable class="parameter">acc_name</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   the name of the access method which is to be used for
	   the index. The default access method is BTREE.
	   Postgres provides three access methods for secondary indexes:
	   <variablelist>
	    <varlistentry>
	     <term>BTREE</term>
	     <listitem>
	      <para>
	       an implementation of the Lehman-Yao
	       high-concurrency btrees.
	      </para>
	     </listitem>
	    </varlistentry>
	    <varlistentry>
	     <term>RTREE</term>
	     <listitem>
	      <para>implements standard rtrees using Guttman's
	       quadratic split algorithm.
	      </para>
	     </listitem>
	    </varlistentry>
	    <varlistentry>
	     <term>HASH</term>
	     <listitem>
	      <para>
	       an implementation of Litwin's linear hashing.
	      </para>
	     </listitem>
	    </varlistentry>
	   </variablelist>
	  </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">ops_name</replaceable> 
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   An associated operator class.
	   The following select list returns all ops_names:
	   
<programlisting>
d131 8
a138 11
</programlisting>

	  </PARA>
      </LISTITEM>
     </VARLISTENTRY>
     <VARLISTENTRY>
      <TERM>
       <replaceable class="parameter">func_name</replaceable> 
      </TERM>
      <LISTITEM>
       <PARA>
d141 3
a143 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d146 7
a152 7
  </REFSECT2>
  
  <REFSECT2 ID="R2-SQL-CREATEINDEX-2">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d154 14
a167 2
   </TITLE>
   <PARA>
d169 6
a174 18
       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	  <ReturnValue>CREATE</ReturnValue>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   The message returned if the index is successfully created.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>

	<VARLISTENTRY>
      <TERM>
       <ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
      </TERM>
      <LISTITEM>
       <PARA>
d181 8
a188 8
  </REFSECT2>
 </REFSYNOPSISDIV>
 
 <REFSECT1 ID="R1-SQL-CREATEINDEX-1">
  <REFSECT1INFO>
   <DATE>1998-09-09</DATE>
  </REFSECT1INFO>
  <TITLE>
d190 2
a191 2
  </TITLE>
  <PARA>
d196 1
a196 1
   
d216 17
a233 17
    In the second syntax, an index is defined
    on the result of a user-defined function
    <replaceable class="parameter">func_name</replaceable> applied
    to one or more attributes of a single class. These functional
    indexes can be used to obtain fast access to data
    based on operators that would normally require some
    transformation to apply them to the base data.
   </para>
  
  <REFSECT2 ID="R2-SQL-CREATEINDEX-3">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
    Notes
   </TITLE>
   <PARA>
d236 1
a236 1
   </PARA>
d241 1
a241 1
  </REFSECT2>
d244 2
a245 2
 <REFSECT1 ID="R1-SQL-CREATEINDEX-2">
  <TITLE>
d247 2
a248 2
  </TITLE>
  <PARA>To create a btree index on the field <literal>title</literal>
d250 2
a251 2
  </PARA>
  <ProgramListing>
d254 1
a254 1
  </ProgramListing>
d273 1
a273 1
 </REFSECT1>
d275 2
a276 2
 <REFSECT1 ID="R1-SQL-CREATEINDEX-3">
  <TITLE>
d278 3
a280 3
  </TITLE>
  <PARA>
  </PARA>
d282 5
a286 5
  <REFSECT2 ID="R2-SQL-CREATEINDEX-4">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d288 2
a289 2
   </TITLE>
   <PARA>
d291 1
a291 1
   </PARA>
d297 1
a297 2
</REFENTRY>

d302 1
a302 1
sgml-omittag:t
@


1.6
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d15 1
d143 15
a157 15
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	  <replaceable class="parameter">func_name</replaceable> 
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   A user-defined function, which returns a value that can
	   be indexed.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
       </variablelist>

d182 11
a192 9
	 <TERM>
	  <ReturnValue>ERROR: Cannot create index: 'index_name' already exists.</ReturnValue>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   This error occurs if it is impossible to create the index.

   </VARIABLELIST>

d204 12
a215 11
  <command>CREATE INDEX</command> constructs an index 
 <replaceable class="parameter">index_name</replaceable>.
on the specified
<replaceable class="parameter">table</replaceable>.

<tip>
<para>
Indexes are primarily used to enhance database performance.
But inappropriate use will result in slower performance.
</tip>

d254 2
a255 1
  
@


1.5
log
@Minor markup adjustment.
@
text
@a167 7
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
<replaceable>status</replaceable>
     </TERM>
     <LISTITEM>
      <PARA>
d187 1
a187 6
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
       </variablelist>
     </LISTITEM>
    </VARLISTENTRY>
@


1.4
log
@Editing and markup cleanup.
@
text
@d167 1
a167 1
   </PARA>
d186 1
d201 1
@


1.3
log
@Markup and editing adjustments...
@
text
@d44 1
a44 1
	   duplicate values when the index is created (if data
d79 1
a79 1
	   Postgres provides three access methods for secondary indices:
d211 1
a211 1
   This command constructs an index 
d218 1
a218 1
Indices are primarily used to enhance database performance.
d239 1
a239 1
    indices can be used to obtain fast access to data
d253 1
a253 1
    indices. Up to 7 keys may be specified.
@


1.2
log
@Very minor formatting fixup in the refentry id field to remove
 the trailing "-1". This makes a cleaner html output file name.
Clean up a few refpurpose fields.
@
text
@d17 1
a17 1
   <DATE>1998-04-15</DATE>
d20 6
a25 7
   CREATE [UNIQUE] INDEX <replaceable class="parameter">index_name</replaceable>
          ON <replaceable class="parameter">table</replaceable> [USING <replaceable class="parameter">acc_name</replaceable> ]
          ( <replaceable class="parameter">column</replaceable> [<replaceable class="parameter">ops_name</replaceable>] [, ...] )
        
   CREATE [UNIQUE] INDEX <replaceable class="parameter">index_name</replaceable>
          ON <replaceable class="parameter">table</replaceable> [USING <replaceable class="parameter">acc_name</replaceable> ]
          ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) <replaceable class="parameter">ops_name</replaceable> )
d30 1
a30 1
    <DATE>1998-04-15</DATE>
a35 7
   </PARA>
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
     </TERM>
     <LISTITEM>
      <PARA>
d39 1
a39 1
	  <function>UNIQUE</function>
d43 1
a43 1
	   <function>UNIQUE</function> causes the system to check for
d129 12
a140 11
	   <programlisting>
       SELECT am.amname AS acc_name,
              opc.opcname AS ops_name,
              opr.oprname AS ops_comp
         FROM pg_am am, pg_amop amop,
              pg_opclass opc, pg_operator opr
         WHERE amop.amopid = am.oid AND
               amop.amopclaid = opc.oid AND
               amop.amopopr = opr.oid
         ORDER BY acc_name, ops_name, ops_comp
	   </programlisting>
d156 1
a156 3
     </LISTITEM>
    </VARLISTENTRY>
   </VARIABLELIST>
d161 1
a161 1
    <DATE>1998-04-15</DATE>
d171 1
d205 1
a205 1
   <DATE>1998-04-15</DATE>
d211 11
a221 2
   This command constructs an index called <replaceable class="parameter">index_name</replaceable>.
  </PARA>
d246 1
a246 1
    <DATE>1998-04-15</DATE>
d256 2
a257 4
    Use the <citerefentry>
     <refentrytitle>DROP INDEX</refentrytitle>
    </citerefentry>
    statement to remove indexes.
d269 2
a270 2
   CREATE UNIQUE INDEX title_idx
          ON films (title);
d272 5
d283 6
a288 2
   CREATE INDEX pointloc
          ON points USING RTREE (point2box(location) box_ops);
a289 6
   SELECT * FROM points
          WHERE point2box(points.pointloc) = boxes.box;
<comment>
Is this example correct?
</comment>
  </programlisting>
d301 1
a301 1
    <DATE>1998-04-15</DATE>
d307 1
a307 1
    CREATE INDEX is a PostgreSQL language extension.
d310 1
a310 1
    There is no CREATE INDEX command in SQL92.
@


1.1
log
@First files for reference pages.
@
text
@d1 1
a1 1
<REFENTRY ID="SQL-CREATEINDEX-1">
@
