begriffs open source - ai-pg/blob - full-docs/txt/index-api.txt

   1
   2 63.1. Basic API Structure for Indexes #
   3
   4    Each index access method is described by a row in the pg_am system
   5    catalog. The pg_am entry specifies a name and a handler function for
   6    the index access method. These entries can be created and deleted using
   7    the CREATE ACCESS METHOD and DROP ACCESS METHOD SQL commands.
   8
   9    An index access method handler function must be declared to accept a
  10    single argument of type internal and to return the pseudo-type
  11    index_am_handler. The argument is a dummy value that simply serves to
  12    prevent handler functions from being called directly from SQL commands.
  13    The result of the function must be a palloc'd struct of type
  14    IndexAmRoutine, which contains everything that the core code needs to
  15    know to make use of the index access method. The IndexAmRoutine struct,
  16    also called the access method's API struct, includes fields specifying
  17    assorted fixed properties of the access method, such as whether it can
  18    support multicolumn indexes. More importantly, it contains pointers to
  19    support functions for the access method, which do all of the real work
  20    to access indexes. These support functions are plain C functions and
  21    are not visible or callable at the SQL level. The support functions are
  22    described in Section 63.2.
  23
  24    The structure IndexAmRoutine is defined thus:
  25 typedef struct IndexAmRoutine
  26 {
  27     NodeTag     type;
  28
  29     /*
  30      * Total number of strategies (operators) by which we can traverse/search
  31      * this AM.  Zero if AM does not have a fixed set of strategy assignments.
  32      */
  33     uint16      amstrategies;
  34     /* total number of support functions that this AM uses */
  35     uint16      amsupport;
  36     /* opclass options support function number or 0 */
  37     uint16      amoptsprocnum;
  38     /* does AM support ORDER BY indexed column's value? */
  39     bool        amcanorder;
  40     /* does AM support ORDER BY result of an operator on indexed column? */
  41     bool        amcanorderbyop;
  42     /* does AM support hashing using API consistent with the hash AM? */
  43     bool        amcanhash;
  44     /* do operators within an opfamily have consistent equality semantics? */
  45     bool        amconsistentequality;
  46     /* do operators within an opfamily have consistent ordering semantics? */
  47     bool        amconsistentordering;
  48     /* does AM support backward scanning? */
  49     bool        amcanbackward;
  50     /* does AM support UNIQUE indexes? */
  51     bool        amcanunique;
  52     /* does AM support multi-column indexes? */
  53     bool        amcanmulticol;
  54     /* does AM require scans to have a constraint on the first index column? */
  55     bool        amoptionalkey;
  56     /* does AM handle ScalarArrayOpExpr quals? */
  57     bool        amsearcharray;
  58     /* does AM handle IS NULL/IS NOT NULL quals? */
  59     bool        amsearchnulls;
  60     /* can index storage data type differ from column data type? */
  61     bool        amstorage;
  62     /* can an index of this type be clustered on? */
  63     bool        amclusterable;
  64     /* does AM handle predicate locks? */
  65     bool        ampredlocks;
  66     /* does AM support parallel scan? */
  67     bool        amcanparallel;
  68     /* does AM support parallel build? */
  69     bool        amcanbuildparallel;
  70     /* does AM support columns included with clause INCLUDE? */
  71     bool        amcaninclude;
  72     /* does AM use maintenance_work_mem? */
  73     bool        amusemaintenanceworkmem;
  74     /* does AM summarize tuples, with at least all tuples in the block
  75      * summarized in one summary */
  76     bool        amsummarizing;
  77     /* OR of parallel vacuum flags */
  78     uint8       amparallelvacuumoptions;
  79     /* type of data stored in index, or InvalidOid if variable */
  80     Oid         amkeytype;
  81
  82     /* interface functions */
  83     ambuild_function ambuild;
  84     ambuildempty_function ambuildempty;
  85     aminsert_function aminsert;
  86     aminsertcleanup_function aminsertcleanup;   /* can be NULL */
  87     ambulkdelete_function ambulkdelete;
  88     amvacuumcleanup_function amvacuumcleanup;
  89     amcanreturn_function amcanreturn;   /* can be NULL */
  90     amcostestimate_function amcostestimate;
  91     amgettreeheight_function amgettreeheight;   /* can be NULL */
  92     amoptions_function amoptions;
  93     amproperty_function amproperty;     /* can be NULL */
  94     ambuildphasename_function ambuildphasename;   /* can be NULL */
  95     amvalidate_function amvalidate;
  96     amadjustmembers_function amadjustmembers; /* can be NULL */
  97     ambeginscan_function ambeginscan;
  98     amrescan_function amrescan;
  99     amgettuple_function amgettuple;     /* can be NULL */
 100     amgetbitmap_function amgetbitmap;   /* can be NULL */
 101     amendscan_function amendscan;
 102     ammarkpos_function ammarkpos;       /* can be NULL */
 103     amrestrpos_function amrestrpos;     /* can be NULL */
 104
 105     /* interface functions to support parallel index scans */
 106     amestimateparallelscan_function amestimateparallelscan;    /* can be NULL */
 107     aminitparallelscan_function aminitparallelscan;    /* can be NULL */
 108     amparallelrescan_function amparallelrescan;    /* can be NULL */
 109
 110     /* interface functions to support planning */
 111     amtranslate_strategy_function amtranslatestrategy;  /* can be NULL */
 112     amtranslate_cmptype_function amtranslatecmptype;    /* can be NULL */
 113 } IndexAmRoutine;
 114
 115    To be useful, an index access method must also have one or more
 116    operator families and operator classes defined in pg_opfamily,
 117    pg_opclass, pg_amop, and pg_amproc. These entries allow the planner to
 118    determine what kinds of query qualifications can be used with indexes
 119    of this access method. Operator families and classes are described in
 120    Section 36.16, which is prerequisite material for reading this chapter.
 121
 122    An individual index is defined by a pg_class entry that describes it as
 123    a physical relation, plus a pg_index entry that shows the logical
 124    content of the index — that is, the set of index columns it has and the
 125    semantics of those columns, as captured by the associated operator
 126    classes. The index columns (key values) can be either simple columns of
 127    the underlying table or expressions over the table rows. The index
 128    access method normally has no interest in where the index key values
 129    come from (it is always handed precomputed key values) but it will be
 130    very interested in the operator class information in pg_index. Both of
 131    these catalog entries can be accessed as part of the Relation data
 132    structure that is passed to all operations on the index.
 133
 134    Some of the flag fields of IndexAmRoutine have nonobvious implications.
 135    The requirements of amcanunique are discussed in Section 63.5. The
 136    amcanmulticol flag asserts that the access method supports
 137    multi-key-column indexes, while amoptionalkey asserts that it allows
 138    scans where no indexable restriction clause is given for the first
 139    index column. When amcanmulticol is false, amoptionalkey essentially
 140    says whether the access method supports full-index scans without any
 141    restriction clause. Access methods that support multiple index columns
 142    must support scans that omit restrictions on any or all of the columns
 143    after the first; however they are permitted to require some restriction
 144    to appear for the first index column, and this is signaled by setting
 145    amoptionalkey false. One reason that an index AM might set
 146    amoptionalkey false is if it doesn't index null values. Since most
 147    indexable operators are strict and hence cannot return true for null
 148    inputs, it is at first sight attractive to not store index entries for
 149    null values: they could never be returned by an index scan anyway.
 150    However, this argument fails when an index scan has no restriction
 151    clause for a given index column. In practice this means that indexes
 152    that have amoptionalkey true must index nulls, since the planner might
 153    decide to use such an index with no scan keys at all. A related
 154    restriction is that an index access method that supports multiple index
 155    columns must support indexing null values in columns after the first,
 156    because the planner will assume the index can be used for queries that
 157    do not restrict these columns. For example, consider an index on (a,b)
 158    and a query with WHERE a = 4. The system will assume the index can be
 159    used to scan for rows with a = 4, which is wrong if the index omits
 160    rows where b is null. It is, however, OK to omit rows where the first
 161    indexed column is null. An index access method that does index nulls
 162    may also set amsearchnulls, indicating that it supports IS NULL and IS
 163    NOT NULL clauses as search conditions.
 164
 165    The amcaninclude flag indicates whether the access method supports
 166    “included” columns, that is it can store (without processing)
 167    additional columns beyond the key column(s). The requirements of the
 168    preceding paragraph apply only to the key columns. In particular, the
 169    combination of amcanmulticol=false and amcaninclude=true is sensible:
 170    it means that there can only be one key column, but there can also be
 171    included column(s). Also, included columns must be allowed to be null,
 172    independently of amoptionalkey.
 173
 174    The amsummarizing flag indicates whether the access method summarizes
 175    the indexed tuples, with summarizing granularity of at least per block.
 176    Access methods that do not point to individual tuples, but to block
 177    ranges (like BRIN), may allow the HOT optimization to continue. This
 178    does not apply to attributes referenced in index predicates, an update
 179    of such an attribute always disables HOT.