1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
<?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>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 15.4 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</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="53.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="64.2. Index Access Method Functions">Section 64.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;
amadjustmembers_function amadjustmembers; /* can be NULL */
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="53.35. pg_opfamily"><code class="structname">pg_opfamily</code></a>,
<a class="link" href="catalog-pg-opclass.html" title="53.33. pg_opclass"><code class="structname">pg_opclass</code></a>,
<a class="link" href="catalog-pg-amop.html" title="53.4. pg_amop"><code class="structname">pg_amop</code></a>, and
<a class="link" href="catalog-pg-amproc.html" title="53.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="38.16. Interfacing Extensions to Indexes">Section 38.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="53.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="53.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="64.5. Index Uniqueness Checks">Section 64.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 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 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.2. Index Access Method Functions</td></tr></table></div></body></html>
|
