diff options
Diffstat (limited to 'doc/src/sgml/html/index-api.html')
| -rw-r--r-- | doc/src/sgml/html/index-api.html | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/doc/src/sgml/html/index-api.html b/doc/src/sgml/html/index-api.html new file mode 100644 index 0000000..22950aa --- /dev/null +++ b/doc/src/sgml/html/index-api.html @@ -0,0 +1,179 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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>61.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 V1.79.1" /><link rel="prev" href="indexam.html" title="Chapter 61. Index Access Method Interface Definition" /><link rel="next" href="index-functions.html" title="61.2. Index Access Method Functions" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">61.1. Basic API Structure for Indexes</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 61. Index Access Method Interface Definition">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="indexam.html" title="Chapter 61. Index Access Method Interface Definition">Up</a></td><th width="60%" align="center">Chapter 61. Index Access Method Interface Definition</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="index-functions.html" title="61.2. Index Access Method Functions">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="INDEX-API"><div class="titlepage"><div><div><h2 class="title" style="clear: both">61.1. Basic API Structure for Indexes</h2></div></div></div><p> + Each index access method is described by a row in the + <a class="link" href="catalog-pg-am.html" title="51.3. pg_am"><code class="structname">pg_am</code></a> + system catalog. The <code class="structname">pg_am</code> entry + specifies a name and a <em class="firstterm">handler function</em> for the index + access method. These entries can be created and deleted using the + <a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a> and + <a class="xref" href="sql-drop-access-method.html" title="DROP ACCESS METHOD"><span class="refentrytitle">DROP ACCESS METHOD</span></a> SQL commands. + </p><p> + An index access method handler function must be declared to accept a + single argument of type <code class="type">internal</code> and to return the + pseudo-type <code class="type">index_am_handler</code>. 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 <code class="structname">IndexAmRoutine</code>, which contains everything + that the core code needs to know to make use of the index access method. + The <code class="structname">IndexAmRoutine</code> struct, also called the access + method's <em class="firstterm">API struct</em>, 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 class="xref" href="index-functions.html" title="61.2. Index Access Method Functions">Section 61.2</a>. + </p><p> + The structure <code class="structname">IndexAmRoutine</code> 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; + /* opclass options support function number or 0 */ + uint16 amoptsprocnum; + /* 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; + /* does AM support parallel scan? */ + bool amcanparallel; + /* does AM support columns included with clause INCLUDE? */ + bool amcaninclude; + /* does AM use maintenance_work_mem? */ + bool amusemaintenanceworkmem; + /* OR of parallel vacuum flags */ + uint8 amparallelvacuumoptions; + /* 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 */ + ambuildphasename_function ambuildphasename; /* 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 */ + + /* interface functions to support parallel index scans */ + amestimateparallelscan_function amestimateparallelscan; /* can be NULL */ + aminitparallelscan_function aminitparallelscan; /* can be NULL */ + amparallelrescan_function amparallelrescan; /* can be NULL */ +} IndexAmRoutine; +</pre><p> + </p><p> + To be useful, an index access method must also have one or more + <em class="firstterm">operator families</em> and + <em class="firstterm">operator classes</em> defined in + <a class="link" href="catalog-pg-opfamily.html" title="51.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>, + <a class="link" href="catalog-pg-opclass.html" title="51.33. pg_opclass"><code class="structname">pg_opclass</code></a>, + <a class="link" href="catalog-pg-amop.html" title="51.4. pg_amop"><code class="structname">pg_amop</code></a>, and + <a class="link" href="catalog-pg-amproc.html" title="51.5. pg_amproc"><code class="structname">pg_amproc</code></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 class="xref" href="xindex.html" title="37.16. Interfacing Extensions to Indexes">Section 37.16</a>, which is prerequisite material for reading + this chapter. + </p><p> + An individual index is defined by a + <a class="link" href="catalog-pg-class.html" title="51.11. pg_class"><code class="structname">pg_class</code></a> + entry that describes it as a physical relation, plus a + <a class="link" href="catalog-pg-index.html" title="51.26. pg_index"><code class="structname">pg_index</code></a> + entry that shows the logical content of the index — 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 + <code class="structname">pg_index</code>. Both of these catalog entries can be + accessed as part of the <code class="structname">Relation</code> data structure that is + passed to all operations on the index. + </p><p> + Some of the flag fields of <code class="structname">IndexAmRoutine</code> have nonobvious + implications. The requirements of <code class="structfield">amcanunique</code> + are discussed in <a class="xref" href="index-unique-checks.html" title="61.5. Index Uniqueness Checks">Section 61.5</a>. + The <code class="structfield">amcanmulticol</code> flag asserts that the + access method supports multi-key-column indexes, while + <code class="structfield">amoptionalkey</code> asserts that it allows scans + where no indexable restriction clause is given for the first index column. + When <code class="structfield">amcanmulticol</code> is false, + <code class="structfield">amoptionalkey</code> essentially says whether the + access method supports full-index scans without any restriction clause. + Access methods that support multiple index columns <span class="emphasis"><em>must</em></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 + <code class="structfield">amoptionalkey</code> false. + One reason that an index AM might set + <code class="structfield">amoptionalkey</code> 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 <code class="structfield">amoptionalkey</code> 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"><em>must</em></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 + <code class="literal">WHERE a = 4</code>. The system will assume the index can be + used to scan for rows with <code class="literal">a = 4</code>, which is wrong if the + index omits rows where <code class="literal">b</code> 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 + <code class="structfield">amsearchnulls</code>, indicating that it supports + <code class="literal">IS NULL</code> and <code class="literal">IS NOT NULL</code> clauses as search + conditions. + </p><p> + The <code class="structfield">amcaninclude</code> flag indicates whether the + access method supports <span class="quote">“<span class="quote">included</span>”</span> columns, that is it can + store (without processing) additional columns beyond the key column(s). + The requirements of the preceding paragraph apply only to the key + columns. In particular, the combination + of <code class="structfield">amcanmulticol</code>=<code class="literal">false</code> + and <code class="structfield">amcaninclude</code>=<code class="literal">true</code> is + sensible: it means that there can only be one key column, but there can + also be included column(s). Also, included columns must be allowed to be + null, independently of <code class="structfield">amoptionalkey</code>. + </p></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="indexam.html" title="Chapter 61. Index Access Method Interface Definition">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="indexam.html" title="Chapter 61. Index Access Method Interface Definition">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="index-functions.html" title="61.2. Index Access Method Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 61. Index Access Method Interface Definition </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 61.2. Index Access Method Functions</td></tr></table></div></body></html>
\ No newline at end of file |