1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2003-04-22 12:08:08 +02:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.38 2003/04/22 10:08:08 petere Exp $
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refentry id="SQL-CREATEINDEX">
|
|
|
|
<refmeta>
|
2002-04-21 21:02:39 +02:00
|
|
|
<refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<refname>CREATE INDEX</refname>
|
|
|
|
<refpurpose>define a new index</refpurpose>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<synopsis>
|
1999-07-22 17:09:15 +02:00
|
|
|
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
|
2003-04-22 12:08:08 +02:00
|
|
|
[ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
|
2001-07-16 07:07:00 +02:00
|
|
|
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-22 17:09:15 +02:00
|
|
|
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
|
2003-04-22 12:08:08 +02:00
|
|
|
[ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
|
2001-07-16 07:07:00 +02:00
|
|
|
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
|
2003-04-22 12:08:08 +02:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE INDEX</command> constructs an index <replaceable
|
|
|
|
class="parameter">index_name</replaceable> on the specified table.
|
|
|
|
Indexes are primarily used to enhance database performance. But
|
|
|
|
inappropriate use will result in slower performance.
|
|
|
|
</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 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 the index methods
|
|
|
|
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
|
|
|
|
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 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 <literal>WHERE</literal> with
|
|
|
|
<literal>UNIQUE</literal> to enforce uniqueness over a subset of a
|
|
|
|
table.
|
|
|
|
</para>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
The expression used in the <literal>WHERE</literal> 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 <literal>WHERE</literal>.
|
|
|
|
</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, remember to mark the function immutable
|
|
|
|
when you create it.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal>UNIQUE</literal></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<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
|
2000-04-11 07:39:15 +02:00
|
|
|
insert or update data which would result in duplicate entries
|
|
|
|
will generate an error.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">index_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-04-23 04:07:16 +02:00
|
|
|
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.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">table</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2002-04-23 04:07:16 +02:00
|
|
|
The name (possibly schema-qualified) of the table to be indexed.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><replaceable class="parameter">method</replaceable></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The name of the method to be used for the index. Choices are
|
|
|
|
<literal>btree</literal>, <literal>hash</literal>,
|
|
|
|
<literal>rtree</literal>, and <literal>gist</literal>. The
|
|
|
|
default method is <literal>btree</literal>.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">column</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of a column of the table.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">ops_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
1999-07-22 17:09:15 +02:00
|
|
|
An associated operator class. See below for details.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">func_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2000-04-23 04:08:33 +02:00
|
|
|
A function, which returns a value that can be indexed.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2001-07-16 07:07:00 +02:00
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">predicate</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Defines the constraint expression for a partial index.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1998-12-29 03:24:47 +01:00
|
|
|
</variablelist>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Diagnostics</title>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><computeroutput>CREATE INDEX</computeroutput></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Message returned if the index was successfully created.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
2001-07-16 07:07:00 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
2001-08-06 20:09:45 +02:00
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
See <xref linkend="indexes"> for information about when indexes can
|
|
|
|
be used, when they are not used, and in which particular situations
|
|
|
|
can be useful.
|
2001-07-16 07:07:00 +02:00
|
|
|
</para>
|
|
|
|
|
2000-05-02 22:02:03 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
Currently, only the B-tree and GiST index methods support
|
|
|
|
multicolumn indexes. Up to 32 fields may be specified by default.
|
|
|
|
(This limit can be altered when building
|
|
|
|
<application>PostgreSQL</application>.) Only B-tree currently
|
|
|
|
supports unique indexes.
|
2000-05-02 22:02:03 +02:00
|
|
|
</para>
|
|
|
|
|
2000-04-23 04:08:33 +02:00
|
|
|
<para>
|
|
|
|
An <firstterm>operator class</firstterm> can be specified for each
|
2002-04-12 01:20:04 +02:00
|
|
|
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
|
2000-04-23 04:08:33 +02:00
|
|
|
four-byte integers would use the <literal>int4_ops</literal> class;
|
|
|
|
this operator class includes comparison functions for four-byte
|
2003-04-22 12:08:08 +02:00
|
|
|
integers. In practice the default operator class for the column's data
|
2002-04-12 01:20:04 +02:00
|
|
|
type is usually sufficient. The main point of having operator classes
|
2000-09-12 22:52:08 +02:00
|
|
|
is that for some data types, there could be more than one meaningful
|
2002-04-12 01:20:04 +02:00
|
|
|
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
|
2003-04-22 12:08:08 +02:00
|
|
|
the proper class when making an index. More information about
|
|
|
|
operator classes is in <xref linkend="indexes-opclass"> and in <xref
|
|
|
|
linkend="xindex">.
|
2000-04-23 04:08:33 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
|
|
|
|
to remove an index.
|
|
|
|
</para>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refsect1>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<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>
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
1998-09-16 16:43:12 +02:00
|
|
|
|
|
|
|
<!--
|
|
|
|
<comment>
|
|
|
|
Is this example correct?
|
|
|
|
</comment>
|
1998-05-13 07:34:00 +02:00
|
|
|
<para>
|
2002-01-20 23:19:57 +01:00
|
|
|
To create a R-tree index on a point attribute so that we
|
1998-05-13 07:34:00 +02:00
|
|
|
can efficiently use box operators on the result of the
|
|
|
|
conversion function:
|
|
|
|
</para>
|
|
|
|
<programlisting>
|
1998-09-16 16:43:12 +02:00
|
|
|
CREATE INDEX pointloc
|
|
|
|
ON points USING RTREE (point2box(location) box_ops);
|
|
|
|
SELECT * FROM points
|
|
|
|
WHERE point2box(points.pointloc) = boxes.box;
|
1998-05-13 07:34:00 +02:00
|
|
|
</programlisting>
|
1998-09-16 16:43:12 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsect1>
|
1998-05-13 07:34:00 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<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>
|
1998-05-13 07:34:00 +02:00
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|
1998-05-13 07:34:00 +02:00
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
|
|
|
mode: sgml
|
1999-07-06 19:16:42 +02:00
|
|
|
sgml-omittag:nil
|
1998-05-13 07:34:00 +02:00
|
|
|
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:
|
|
|
|
-->
|