Table of Contents
This chapter defines the interface between the core PostgreSQL system and index access methods, which manage individual index types. The core system knows nothing about indexes beyond what is specified here, so it is possible to develop entirely new index types by writing add-on code.
All indexes in PostgreSQL are what are known
technically as secondary indexes; that is, the index is
physically separate from the table file that it describes. Each index
is stored as its own physical relation and so is described
by an entry in the pg_class
catalog. The contents of an
index are entirely under the control of its index access method. In
practice, all index access methods divide indexes into standard-size
pages so that they can use the regular storage manager and buffer manager
to access the index contents. (All the existing index access methods
furthermore use the standard page layout described in Section 49.3, “Database Page Layout”, and they all use the same format for index
tuple headers; but these decisions are not forced on an access method.)
An index is effectively a mapping from some data key values to tuple identifiers, or TIDs, of row versions (tuples) in the index's parent table. A TID consists of a block number and an item number within that block (see Section 49.3, “Database Page Layout”). This is sufficient information to fetch a particular row version from the table. Indexes are not directly aware that under MVCC, there may be multiple extant versions of the same logical row; to an index, each tuple is an independent object that needs its own index entry. Thus, an update of a row always creates all-new index entries for the row, even if the key values did not change. Index entries for dead tuples are reclaimed (by vacuuming) when the dead tuples themselves are reclaimed.
Each index access method is described by a row in the
pg_am
system catalog (see
Section 41.3, “pg_am
”). The principal contents of a
pg_am
row are references to
pg_proc
entries that identify the index access
functions supplied by the access method. The APIs for these functions
are defined later in this chapter. In addition, the
pg_am
row specifies a few fixed properties of
the access method, such as whether it can support multi-column indexes.
There is not currently any special support
for creating or deleting pg_am
entries;
anyone able to write a new access method is expected to be competent
to insert an appropriate row for themselves.
To be useful, an index access method must also have one or more
operator classes defined in
pg_opclass
,
pg_amop
, and
pg_amproc
.
These entries allow the planner
to determine what kinds of query qualifications can be used with
indexes of this access method. Operator classes are described
in Section 31.14, “Interfacing Extensions To Indexes”, which is prerequisite material for reading
this chapter.
An individual index is defined by a
pg_class
entry that describes it as a physical relation, plus a
pg_index
entry that shows the logical content of the index [mdash ] that is, the set
of index columns it has and the semantics of those columns, as captured by
the associated operator classes. The index columns (key values) can be
either simple columns of the underlying table or expressions over the table
rows. The index access method normally has no interest in where the index
key values come from (it is always handed precomputed key values) but it
will be very interested in the operator class information in
pg_index
. Both of these catalog entries can be
accessed as part of the Relation
data structure that is
passed to all operations on the index.
Some of the flag columns of pg_am
have nonobvious
implications. The requirements of amcanunique
are discussed in Section 47.5, “Index Uniqueness Checks”, and those of
amconcurrent
in Section 47.4, “Index Locking Considerations”.
The amcanmulticol
flag asserts that the
access method supports multi-column indexes, while
amindexnulls
asserts that index entries are
created for NULL key values. Since most indexable operators are
strict and hence cannot return TRUE for NULL inputs,
it is at first sight attractive to not store index entries for NULLs:
they could never be returned by an index scan anyway. However, this
argument fails for a full-table index scan (one with no scan keys);
such a scan should include null rows. In practice this means that
indexes that support ordered scans (have amorderstrategy
nonzero) must index nulls, since the planner might decide to use such a
scan as a substitute for sorting. Such indexes must also be willing to
run a scan with no scan keys at all. Another restriction is that an index
access method that supports multiple index columns must
support indexing null values in columns after the first, because the planner
will assume the index can be used for queries on just the first
column(s). For example, consider an index on (a,b) and a query with
WHERE a = 4
. The system will assume the index can be
used to scan for rows with a = 4
, which is wrong if the
index omits rows where b
is null.
It is, however, OK to omit rows where the first indexed column is null.
(GiST currently does so.) Thus,
amindexnulls
should be set true only if the
index access method indexes all rows, including arbitrary combinations of
null values.