Sophie: postgresql9.6-docs-9.6.22-1.mga7 noarch

postgresql9.6-docs-9.6.22-1.mga7.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Basic API Structure for Indexes</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.6.22 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Index Access Method Interface Definition"
HREF="indexam.html"><LINK
REL="PREVIOUS"
TITLE="Index Access Method Interface Definition"
HREF="indexam.html"><LINK
REL="NEXT"
TITLE="Index Access Method Functions"
HREF="index-functions.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2021-05-18T09:16:10"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="4"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.6.22 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Index Access Method Interface Definition"
HREF="indexam.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="indexam.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 59. Index Access Method Interface Definition</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Index Access Method Functions"
HREF="index-functions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="INDEX-API"
>59.1. Basic API Structure for Indexes</A
></H1
><P
>   Each index access method is described by a row in the
   <A
HREF="catalog-pg-am.html"
><TT
CLASS="STRUCTNAME"
>pg_am</TT
></A
>
   system catalog.  The <TT
CLASS="STRUCTNAME"
>pg_am</TT
> entry
   specifies a name and a <I
CLASS="FIRSTTERM"
>handler function</I
> for the access
   method.  These entries can be created and deleted using the
   <A
HREF="sql-create-access-method.html"
>CREATE ACCESS METHOD</A
> and
   <A
HREF="sql-drop-access-method.html"
>DROP ACCESS METHOD</A
> SQL commands.
  </P
><P
>   An index access method handler function must be declared to accept a
   single argument of type <TT
CLASS="TYPE"
>internal</TT
> and to return the
   pseudo-type <TT
CLASS="TYPE"
>index_am_handler</TT
>.  The argument is a dummy value that
   simply serves to prevent handler functions from being called directly from
   SQL commands.  The result of the function must be a palloc'd struct of
   type <TT
CLASS="STRUCTNAME"
>IndexAmRoutine</TT
>, which contains everything
   that the core code needs to know to make use of the index access method.
   The <TT
CLASS="STRUCTNAME"
>IndexAmRoutine</TT
> struct, also called the access
   method's <I
CLASS="FIRSTTERM"
>API struct</I
>, includes fields specifying assorted
   fixed properties of the access method, such as whether it can support
   multicolumn indexes.  More importantly, it contains pointers to support
   functions for the access method, which do all of the real work to access
   indexes.  These support functions are plain C functions and are not
   visible or callable at the SQL level.  The support functions are described
   in <A
HREF="index-functions.html"
>Section 59.2</A
>.
  </P
><P
>   The structure <TT
CLASS="STRUCTNAME"
>IndexAmRoutine</TT
> is defined thus:
</P><PRE
CLASS="PROGRAMLISTING"
>typedef struct IndexAmRoutine
{
    NodeTag     type;

    /*
     * Total number of strategies (operators) by which we can traverse/search
     * this AM.  Zero if AM does not have a fixed set of strategy assignments.
     */
    uint16      amstrategies;
    /* total number of support functions that this AM uses */
    uint16      amsupport;
    /* does AM support ORDER BY indexed column's value? */
    bool        amcanorder;
    /* does AM support ORDER BY result of an operator on indexed column? */
    bool        amcanorderbyop;
    /* does AM support backward scanning? */
    bool        amcanbackward;
    /* does AM support UNIQUE indexes? */
    bool        amcanunique;
    /* does AM support multi-column indexes? */
    bool        amcanmulticol;
    /* does AM require scans to have a constraint on the first index column? */
    bool        amoptionalkey;
    /* does AM handle ScalarArrayOpExpr quals? */
    bool        amsearcharray;
    /* does AM handle IS NULL/IS NOT NULL quals? */
    bool        amsearchnulls;
    /* can index storage data type differ from column data type? */
    bool        amstorage;
    /* can an index of this type be clustered on? */
    bool        amclusterable;
    /* does AM handle predicate locks? */
    bool        ampredlocks;
    /* type of data stored in index, or InvalidOid if variable */
    Oid         amkeytype;

    /* interface functions */
    ambuild_function ambuild;
    ambuildempty_function ambuildempty;
    aminsert_function aminsert;
    ambulkdelete_function ambulkdelete;
    amvacuumcleanup_function amvacuumcleanup;
    amcanreturn_function amcanreturn;   /* can be NULL */
    amcostestimate_function amcostestimate;
    amoptions_function amoptions;
    amproperty_function amproperty;     /* can be NULL */
    amvalidate_function amvalidate;
    ambeginscan_function ambeginscan;
    amrescan_function amrescan;
    amgettuple_function amgettuple;     /* can be NULL */
    amgetbitmap_function amgetbitmap;   /* can be NULL */
    amendscan_function amendscan;
    ammarkpos_function ammarkpos;       /* can be NULL */
    amrestrpos_function amrestrpos;     /* can be NULL */
} IndexAmRoutine;</PRE
><P>
  </P
><P
>   To be useful, an index access method must also have one or more
   <I
CLASS="FIRSTTERM"
>operator families</I
> and
   <I
CLASS="FIRSTTERM"
>operator classes</I
> defined in
   <A
HREF="catalog-pg-opfamily.html"
><TT
CLASS="STRUCTNAME"
>pg_opfamily</TT
></A
>,
   <A
HREF="catalog-pg-opclass.html"
><TT
CLASS="STRUCTNAME"
>pg_opclass</TT
></A
>,
   <A
HREF="catalog-pg-amop.html"
><TT
CLASS="STRUCTNAME"
>pg_amop</TT
></A
>, and
   <A
HREF="catalog-pg-amproc.html"
><TT
CLASS="STRUCTNAME"
>pg_amproc</TT
></A
>.
   These entries allow the planner
   to determine what kinds of query qualifications can be used with
   indexes of this access method.  Operator families and classes are described
   in <A
HREF="xindex.html"
>Section 36.14</A
>, which is prerequisite material for reading
   this chapter.
  </P
><P
>   An individual index is defined by a
   <A
HREF="catalog-pg-class.html"
><TT
CLASS="STRUCTNAME"
>pg_class</TT
></A
>
   entry that describes it as a physical relation, plus a
   <A
HREF="catalog-pg-index.html"
><TT
CLASS="STRUCTNAME"
>pg_index</TT
></A
>
   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
   <TT
CLASS="STRUCTNAME"
>pg_index</TT
>.  Both of these catalog entries can be
   accessed as part of the <TT
CLASS="STRUCTNAME"
>Relation</TT
> data structure that is
   passed to all operations on the index.
  </P
><P
>   Some of the flag fields of <TT
CLASS="STRUCTNAME"
>IndexAmRoutine</TT
> have nonobvious
   implications.  The requirements of <TT
CLASS="STRUCTFIELD"
>amcanunique</TT
>
   are discussed in <A
HREF="index-unique-checks.html"
>Section 59.5</A
>.
   The <TT
CLASS="STRUCTFIELD"
>amcanmulticol</TT
> flag asserts that the
   access method supports multicolumn indexes, while
   <TT
CLASS="STRUCTFIELD"
>amoptionalkey</TT
> asserts that it allows scans
   where no indexable restriction clause is given for the first index column.
   When <TT
CLASS="STRUCTFIELD"
>amcanmulticol</TT
> is false,
   <TT
CLASS="STRUCTFIELD"
>amoptionalkey</TT
> essentially says whether the
   access method supports full-index scans without any restriction clause.
   Access methods that support multiple index columns <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must</I
></SPAN
>
   support scans that omit restrictions on any or all of the columns after
   the first; however they are permitted to require some restriction to
   appear for the first index column, and this is signaled by setting
   <TT
CLASS="STRUCTFIELD"
>amoptionalkey</TT
> false.
   One reason that an index AM might set
   <TT
CLASS="STRUCTFIELD"
>amoptionalkey</TT
> false is if it doesn't index
   null 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 null values:
   they could never be returned by an index scan anyway.  However, this
   argument fails when an index scan has no restriction clause for a given
   index column.  In practice this means that
   indexes that have <TT
CLASS="STRUCTFIELD"
>amoptionalkey</TT
> true must
   index nulls, since the planner might decide to use such an index
   with no scan keys at all.  A related restriction is that an index
   access method that supports multiple index columns <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must</I
></SPAN
>
   support indexing null values in columns after the first, because the planner
   will assume the index can be used for queries that do not restrict
   these columns.  For example, consider an index on (a,b) and a query with
   <TT
CLASS="LITERAL"
>WHERE a = 4</TT
>.  The system will assume the index can be
   used to scan for rows with <TT
CLASS="LITERAL"
>a = 4</TT
>, which is wrong if the
   index omits rows where <TT
CLASS="LITERAL"
>b</TT
> is null.
   It is, however, OK to omit rows where the first indexed column is null.
   An index access method that does index nulls may also set
   <TT
CLASS="STRUCTFIELD"
>amsearchnulls</TT
>, indicating that it supports
   <TT
CLASS="LITERAL"
>IS NULL</TT
> and <TT
CLASS="LITERAL"
>IS NOT NULL</TT
> clauses as search
   conditions.
  </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="indexam.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="index-functions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Index Access Method Interface Definition</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="indexam.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Index Access Method Functions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>