begriffs open source - ai-pg/blob - full-docs/src/sgml/html/index-api.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>63.1. Basic API Structure for Indexes</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition" /><link rel="next" href="index-functions.html" title="63.2. Index Access Method Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">63.1. Basic API Structure for Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 63. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-functions.html" title="63.2. Index Access Method Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="INDEX-API"><div class="titlepage"><div><div><h2 class="title" style="clear: both">63.1. Basic API Structure for Indexes <a href="#INDEX-API" class="id_link">#</a></h2></div></div></div><p>
   3    Each index access method is described by a row in the
   4    <a class="link" href="catalog-pg-am.html" title="52.3. pg_am"><code class="structname">pg_am</code></a>
   5    system catalog.  The <code class="structname">pg_am</code> entry
   6    specifies a name and a <em class="firstterm">handler function</em> for the index
   7    access method.  These entries can be created and deleted using the
   8    <a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a> and
   9    <a class="xref" href="sql-drop-access-method.html" title="DROP ACCESS METHOD"><span class="refentrytitle">DROP ACCESS METHOD</span></a> SQL commands.
  10   </p><p>
  11    An index access method handler function must be declared to accept a
  12    single argument of type <code class="type">internal</code> and to return the
  13    pseudo-type <code class="type">index_am_handler</code>.  The argument is a dummy value that
  14    simply serves to prevent handler functions from being called directly from
  15    SQL commands.  The result of the function must be a palloc'd struct of
  16    type <code class="structname">IndexAmRoutine</code>, which contains everything
  17    that the core code needs to know to make use of the index access method.
  18    The <code class="structname">IndexAmRoutine</code> struct, also called the access
  19    method's <em class="firstterm">API struct</em>, includes fields specifying assorted
  20    fixed properties of the access method, such as whether it can support
  21    multicolumn indexes.  More importantly, it contains pointers to support
  22    functions for the access method, which do all of the real work to access
  23    indexes.  These support functions are plain C functions and are not
  24    visible or callable at the SQL level.  The support functions are described
  25    in <a class="xref" href="index-functions.html" title="63.2. Index Access Method Functions">Section 63.2</a>.
  26   </p><p>
  27    The structure <code class="structname">IndexAmRoutine</code> is defined thus:
  28 </p><pre class="programlisting">
  29 typedef struct IndexAmRoutine
  30 {
  31     NodeTag     type;
  32
  33     /*
  34      * Total number of strategies (operators) by which we can traverse/search
  35      * this AM.  Zero if AM does not have a fixed set of strategy assignments.
  36      */
  37     uint16      amstrategies;
  38     /* total number of support functions that this AM uses */
  39     uint16      amsupport;
  40     /* opclass options support function number or 0 */
  41     uint16      amoptsprocnum;
  42     /* does AM support ORDER BY indexed column's value? */
  43     bool        amcanorder;
  44     /* does AM support ORDER BY result of an operator on indexed column? */
  45     bool        amcanorderbyop;
  46     /* does AM support hashing using API consistent with the hash AM? */
  47     bool        amcanhash;
  48     /* do operators within an opfamily have consistent equality semantics? */
  49     bool        amconsistentequality;
  50     /* do operators within an opfamily have consistent ordering semantics? */
  51     bool        amconsistentordering;
  52     /* does AM support backward scanning? */
  53     bool        amcanbackward;
  54     /* does AM support UNIQUE indexes? */
  55     bool        amcanunique;
  56     /* does AM support multi-column indexes? */
  57     bool        amcanmulticol;
  58     /* does AM require scans to have a constraint on the first index column? */
  59     bool        amoptionalkey;
  60     /* does AM handle ScalarArrayOpExpr quals? */
  61     bool        amsearcharray;
  62     /* does AM handle IS NULL/IS NOT NULL quals? */
  63     bool        amsearchnulls;
  64     /* can index storage data type differ from column data type? */
  65     bool        amstorage;
  66     /* can an index of this type be clustered on? */
  67     bool        amclusterable;
  68     /* does AM handle predicate locks? */
  69     bool        ampredlocks;
  70     /* does AM support parallel scan? */
  71     bool        amcanparallel;
  72     /* does AM support parallel build? */
  73     bool        amcanbuildparallel;
  74     /* does AM support columns included with clause INCLUDE? */
  75     bool        amcaninclude;
  76     /* does AM use maintenance_work_mem? */
  77     bool        amusemaintenanceworkmem;
  78     /* does AM summarize tuples, with at least all tuples in the block
  79      * summarized in one summary */
  80     bool        amsummarizing;
  81     /* OR of parallel vacuum flags */
  82     uint8       amparallelvacuumoptions;
  83     /* type of data stored in index, or InvalidOid if variable */
  84     Oid         amkeytype;
  85
  86     /* interface functions */
  87     ambuild_function ambuild;
  88     ambuildempty_function ambuildempty;
  89     aminsert_function aminsert;
  90     aminsertcleanup_function aminsertcleanup;   /* can be NULL */
  91     ambulkdelete_function ambulkdelete;
  92     amvacuumcleanup_function amvacuumcleanup;
  93     amcanreturn_function amcanreturn;   /* can be NULL */
  94     amcostestimate_function amcostestimate;
  95     amgettreeheight_function amgettreeheight;   /* can be NULL */
  96     amoptions_function amoptions;
  97     amproperty_function amproperty;     /* can be NULL */
  98     ambuildphasename_function ambuildphasename;   /* can be NULL */
  99     amvalidate_function amvalidate;
 100     amadjustmembers_function amadjustmembers; /* can be NULL */
 101     ambeginscan_function ambeginscan;
 102     amrescan_function amrescan;
 103     amgettuple_function amgettuple;     /* can be NULL */
 104     amgetbitmap_function amgetbitmap;   /* can be NULL */
 105     amendscan_function amendscan;
 106     ammarkpos_function ammarkpos;       /* can be NULL */
 107     amrestrpos_function amrestrpos;     /* can be NULL */
 108
 109     /* interface functions to support parallel index scans */
 110     amestimateparallelscan_function amestimateparallelscan;    /* can be NULL */
 111     aminitparallelscan_function aminitparallelscan;    /* can be NULL */
 112     amparallelrescan_function amparallelrescan;    /* can be NULL */
 113
 114     /* interface functions to support planning */
 115     amtranslate_strategy_function amtranslatestrategy;  /* can be NULL */
 116     amtranslate_cmptype_function amtranslatecmptype;    /* can be NULL */
 117 } IndexAmRoutine;
 118 </pre><p>
 119   </p><p>
 120    To be useful, an index access method must also have one or more
 121    <em class="firstterm">operator families</em> and
 122    <em class="firstterm">operator classes</em> defined in
 123    <a class="link" href="catalog-pg-opfamily.html" title="52.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>,
 124    <a class="link" href="catalog-pg-opclass.html" title="52.33. pg_opclass"><code class="structname">pg_opclass</code></a>,
 125    <a class="link" href="catalog-pg-amop.html" title="52.4. pg_amop"><code class="structname">pg_amop</code></a>, and
 126    <a class="link" href="catalog-pg-amproc.html" title="52.5. pg_amproc"><code class="structname">pg_amproc</code></a>.
 127    These entries allow the planner
 128    to determine what kinds of query qualifications can be used with
 129    indexes of this access method.  Operator families and classes are described
 130    in <a class="xref" href="xindex.html" title="36.16. Interfacing Extensions to Indexes">Section 36.16</a>, which is prerequisite material for reading
 131    this chapter.
 132   </p><p>
 133    An individual index is defined by a
 134    <a class="link" href="catalog-pg-class.html" title="52.11. pg_class"><code class="structname">pg_class</code></a>
 135    entry that describes it as a physical relation, plus a
 136    <a class="link" href="catalog-pg-index.html" title="52.26. pg_index"><code class="structname">pg_index</code></a>
 137    entry that shows the logical content of the index — that is, the set
 138    of index columns it has and the semantics of those columns, as captured by
 139    the associated operator classes.  The index columns (key values) can be
 140    either simple columns of the underlying table or expressions over the table
 141    rows.  The index access method normally has no interest in where the index
 142    key values come from (it is always handed precomputed key values) but it
 143    will be very interested in the operator class information in
 144    <code class="structname">pg_index</code>.  Both of these catalog entries can be
 145    accessed as part of the <code class="structname">Relation</code> data structure that is
 146    passed to all operations on the index.
 147   </p><p>
 148    Some of the flag fields of <code class="structname">IndexAmRoutine</code> have nonobvious
 149    implications.  The requirements of <code class="structfield">amcanunique</code>
 150    are discussed in <a class="xref" href="index-unique-checks.html" title="63.5. Index Uniqueness Checks">Section 63.5</a>.
 151    The <code class="structfield">amcanmulticol</code> flag asserts that the
 152    access method supports multi-key-column indexes, while
 153    <code class="structfield">amoptionalkey</code> asserts that it allows scans
 154    where no indexable restriction clause is given for the first index column.
 155    When <code class="structfield">amcanmulticol</code> is false,
 156    <code class="structfield">amoptionalkey</code> essentially says whether the
 157    access method supports full-index scans without any restriction clause.
 158    Access methods that support multiple index columns <span class="emphasis"><em>must</em></span>
 159    support scans that omit restrictions on any or all of the columns after
 160    the first; however they are permitted to require some restriction to
 161    appear for the first index column, and this is signaled by setting
 162    <code class="structfield">amoptionalkey</code> false.
 163    One reason that an index <acronym class="acronym">AM</acronym> might set
 164    <code class="structfield">amoptionalkey</code> false is if it doesn't index
 165    null values.  Since most indexable operators are
 166    strict and hence cannot return true for null inputs,
 167    it is at first sight attractive to not store index entries for null values:
 168    they could never be returned by an index scan anyway.  However, this
 169    argument fails when an index scan has no restriction clause for a given
 170    index column.  In practice this means that
 171    indexes that have <code class="structfield">amoptionalkey</code> true must
 172    index nulls, since the planner might decide to use such an index
 173    with no scan keys at all.  A related restriction is that an index
 174    access method that supports multiple index columns <span class="emphasis"><em>must</em></span>
 175    support indexing null values in columns after the first, because the planner
 176    will assume the index can be used for queries that do not restrict
 177    these columns.  For example, consider an index on (a,b) and a query with
 178    <code class="literal">WHERE a = 4</code>.  The system will assume the index can be
 179    used to scan for rows with <code class="literal">a = 4</code>, which is wrong if the
 180    index omits rows where <code class="literal">b</code> is null.
 181    It is, however, OK to omit rows where the first indexed column is null.
 182    An index access method that does index nulls may also set
 183    <code class="structfield">amsearchnulls</code>, indicating that it supports
 184    <code class="literal">IS NULL</code> and <code class="literal">IS NOT NULL</code> clauses as search
 185    conditions.
 186   </p><p>
 187    The <code class="structfield">amcaninclude</code> flag indicates whether the
 188    access method supports <span class="quote">“<span class="quote">included</span>”</span> columns, that is it can
 189    store (without processing) additional columns beyond the key column(s).
 190    The requirements of the preceding paragraph apply only to the key
 191    columns.  In particular, the combination
 192    of <code class="structfield">amcanmulticol</code>=<code class="literal">false</code>
 193    and <code class="structfield">amcaninclude</code>=<code class="literal">true</code> is
 194    sensible: it means that there can only be one key column, but there can
 195    also be included column(s).  Also, included columns must be allowed to be
 196    null, independently of <code class="structfield">amoptionalkey</code>.
 197   </p><p>
 198    The <code class="structfield">amsummarizing</code> flag indicates whether the
 199    access method summarizes the indexed tuples, with summarizing granularity
 200    of at least per block.
 201    Access methods that do not point to individual tuples, but to block ranges
 202    (like <acronym class="acronym">BRIN</acronym>), may allow the <acronym class="acronym">HOT</acronym> optimization
 203    to continue. This does not apply to attributes referenced in index
 204    predicates, an update of such an attribute always disables <acronym class="acronym">HOT</acronym>.
 205   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-functions.html" title="63.2. Index Access Method Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 63. Index Access Method Interface Definition </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 63.2. Index Access Method Functions</td></tr></table></div></body></html>