codekingpro/portable-devtools

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>64.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 64. Index Access Method Interface Definition" /><link rel="next" href="index-functions.html" title="64.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">64.1. Basic API Structure for Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 64. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-functions.html" title="64.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">64.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 the4   <a class="link" href="catalog-pg-am.html" title="53.3. pg_am"><code class="structname">pg_am</code></a>5   system catalog.  The <code class="structname">pg_am</code> entry6   specifies a name and a <em class="firstterm">handler function</em> for the index7   access method.  These entries can be created and deleted using the8   <a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a> and9   <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 a12   single argument of type <code class="type">internal</code> and to return the13   pseudo-type <code class="type">index_am_handler</code>.  The argument is a dummy value that14   simply serves to prevent handler functions from being called directly from15   SQL commands.  The result of the function must be a palloc'd struct of16   type <code class="structname">IndexAmRoutine</code>, which contains everything17   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 access19   method's <em class="firstterm">API struct</em>, includes fields specifying assorted20   fixed properties of the access method, such as whether it can support21   multicolumn indexes.  More importantly, it contains pointers to support22   functions for the access method, which do all of the real work to access23   indexes.  These support functions are plain C functions and are not24   visible or callable at the SQL level.  The support functions are described25   in <a class="xref" href="index-functions.html" title="64.2. Index Access Method Functions">Section 64.2</a>.26  </p><p>27   The structure <code class="structname">IndexAmRoutine</code> is defined thus:28</p><pre class="programlisting">29typedef struct IndexAmRoutine30{31    NodeTag     type;32 33    /*34     * Total number of strategies (operators) by which we can traverse/search35     * 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 backward scanning? */47    bool        amcanbackward;48    /* does AM support UNIQUE indexes? */49    bool        amcanunique;50    /* does AM support multi-column indexes? */51    bool        amcanmulticol;52    /* does AM require scans to have a constraint on the first index column? */53    bool        amoptionalkey;54    /* does AM handle ScalarArrayOpExpr quals? */55    bool        amsearcharray;56    /* does AM handle IS NULL/IS NOT NULL quals? */57    bool        amsearchnulls;58    /* can index storage data type differ from column data type? */59    bool        amstorage;60    /* can an index of this type be clustered on? */61    bool        amclusterable;62    /* does AM handle predicate locks? */63    bool        ampredlocks;64    /* does AM support parallel scan? */65    bool        amcanparallel;66    /* does AM support columns included with clause INCLUDE? */67    bool        amcaninclude;68    /* does AM use maintenance_work_mem? */69    bool        amusemaintenanceworkmem;70    /* does AM summarize tuples, with at least all tuples in the block71     * summarized in one summary */72    bool        amsummarizing;73    /* OR of parallel vacuum flags */74    uint8       amparallelvacuumoptions;75    /* type of data stored in index, or InvalidOid if variable */76    Oid         amkeytype;77 78    /* interface functions */79    ambuild_function ambuild;80    ambuildempty_function ambuildempty;81    aminsert_function aminsert;82    ambulkdelete_function ambulkdelete;83    amvacuumcleanup_function amvacuumcleanup;84    amcanreturn_function amcanreturn;   /* can be NULL */85    amcostestimate_function amcostestimate;86    amoptions_function amoptions;87    amproperty_function amproperty;     /* can be NULL */88    ambuildphasename_function ambuildphasename;   /* can be NULL */89    amvalidate_function amvalidate;90    amadjustmembers_function amadjustmembers; /* can be NULL */91    ambeginscan_function ambeginscan;92    amrescan_function amrescan;93    amgettuple_function amgettuple;     /* can be NULL */94    amgetbitmap_function amgetbitmap;   /* can be NULL */95    amendscan_function amendscan;96    ammarkpos_function ammarkpos;       /* can be NULL */97    amrestrpos_function amrestrpos;     /* can be NULL */98 99    /* interface functions to support parallel index scans */100    amestimateparallelscan_function amestimateparallelscan;    /* can be NULL */101    aminitparallelscan_function aminitparallelscan;    /* can be NULL */102    amparallelrescan_function amparallelrescan;    /* can be NULL */103} IndexAmRoutine;104</pre><p>105  </p><p>106   To be useful, an index access method must also have one or more107   <em class="firstterm">operator families</em> and108   <em class="firstterm">operator classes</em> defined in109   <a class="link" href="catalog-pg-opfamily.html" title="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>,110   <a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>,111   <a class="link" href="catalog-pg-amop.html" title="53.4. pg_amop"><code class="structname">pg_amop</code></a>, and112   <a class="link" href="catalog-pg-amproc.html" title="53.5. pg_amproc"><code class="structname">pg_amproc</code></a>.113   These entries allow the planner114   to determine what kinds of query qualifications can be used with115   indexes of this access method.  Operator families and classes are described116   in <a class="xref" href="xindex.html" title="38.16. Interfacing Extensions to Indexes">Section 38.16</a>, which is prerequisite material for reading117   this chapter.118  </p><p>119   An individual index is defined by a120   <a class="link" href="catalog-pg-class.html" title="53.11. pg_class"><code class="structname">pg_class</code></a>121   entry that describes it as a physical relation, plus a122   <a class="link" href="catalog-pg-index.html" title="53.26. pg_index"><code class="structname">pg_index</code></a>123   entry that shows the logical content of the index — that is, the set124   of index columns it has and the semantics of those columns, as captured by125   the associated operator classes.  The index columns (key values) can be126   either simple columns of the underlying table or expressions over the table127   rows.  The index access method normally has no interest in where the index128   key values come from (it is always handed precomputed key values) but it129   will be very interested in the operator class information in130   <code class="structname">pg_index</code>.  Both of these catalog entries can be131   accessed as part of the <code class="structname">Relation</code> data structure that is132   passed to all operations on the index.133  </p><p>134   Some of the flag fields of <code class="structname">IndexAmRoutine</code> have nonobvious135   implications.  The requirements of <code class="structfield">amcanunique</code>136   are discussed in <a class="xref" href="index-unique-checks.html" title="64.5. Index Uniqueness Checks">Section 64.5</a>.137   The <code class="structfield">amcanmulticol</code> flag asserts that the138   access method supports multi-key-column indexes, while139   <code class="structfield">amoptionalkey</code> asserts that it allows scans140   where no indexable restriction clause is given for the first index column.141   When <code class="structfield">amcanmulticol</code> is false,142   <code class="structfield">amoptionalkey</code> essentially says whether the143   access method supports full-index scans without any restriction clause.144   Access methods that support multiple index columns <span class="emphasis"><em>must</em></span>145   support scans that omit restrictions on any or all of the columns after146   the first; however they are permitted to require some restriction to147   appear for the first index column, and this is signaled by setting148   <code class="structfield">amoptionalkey</code> false.149   One reason that an index AM might set150   <code class="structfield">amoptionalkey</code> false is if it doesn't index151   null values.  Since most indexable operators are152   strict and hence cannot return true for null inputs,153   it is at first sight attractive to not store index entries for null values:154   they could never be returned by an index scan anyway.  However, this155   argument fails when an index scan has no restriction clause for a given156   index column.  In practice this means that157   indexes that have <code class="structfield">amoptionalkey</code> true must158   index nulls, since the planner might decide to use such an index159   with no scan keys at all.  A related restriction is that an index160   access method that supports multiple index columns <span class="emphasis"><em>must</em></span>161   support indexing null values in columns after the first, because the planner162   will assume the index can be used for queries that do not restrict163   these columns.  For example, consider an index on (a,b) and a query with164   <code class="literal">WHERE a = 4</code>.  The system will assume the index can be165   used to scan for rows with <code class="literal">a = 4</code>, which is wrong if the166   index omits rows where <code class="literal">b</code> is null.167   It is, however, OK to omit rows where the first indexed column is null.168   An index access method that does index nulls may also set169   <code class="structfield">amsearchnulls</code>, indicating that it supports170   <code class="literal">IS NULL</code> and <code class="literal">IS NOT NULL</code> clauses as search171   conditions.172  </p><p>173   The <code class="structfield">amcaninclude</code> flag indicates whether the174   access method supports <span class="quote">“<span class="quote">included</span>”</span> columns, that is it can175   store (without processing) additional columns beyond the key column(s).176   The requirements of the preceding paragraph apply only to the key177   columns.  In particular, the combination178   of <code class="structfield">amcanmulticol</code>=<code class="literal">false</code>179   and <code class="structfield">amcaninclude</code>=<code class="literal">true</code> is180   sensible: it means that there can only be one key column, but there can181   also be included column(s).  Also, included columns must be allowed to be182   null, independently of <code class="structfield">amoptionalkey</code>.183  </p><p>184   The <code class="structfield">amsummarizing</code> flag indicates whether the185   access method summarizes the indexed tuples, with summarizing granularity186   of at least per block.187   Access methods that do not point to individual tuples, but to block ranges188   (like <acronym class="acronym">BRIN</acronym>), may allow the <acronym class="acronym">HOT</acronym> optimization189   to continue. This does not apply to attributes referenced in index190   predicates, an update of such an attribute always disables <acronym class="acronym">HOT</acronym>.191  </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 64. Index Access Method Interface Definition">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 64. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-functions.html" title="64.2. Index Access Method Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 64. Index Access Method Interface Definition </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.2. Index Access Method Functions</td></tr></table></div></body></html>