1/*-------------------------------------------------------------------------
2 *
3 * amapi.h
4 * API for Postgres index access methods.
5 *
6 * Copyright (c) 2015-2019, PostgreSQL Global Development Group
7 *
8 * src/include/access/amapi.h
9 *
10 *-------------------------------------------------------------------------
11 */
12#ifndef AMAPI_H
13#define AMAPI_H
14
15#include "access/genam.h"
16
17/*
18 * We don't wish to include planner header files here, since most of an index
19 * AM's implementation isn't concerned with those data structures. To allow
20 * declaring amcostestimate_function here, use forward struct references.
21 */
22struct PlannerInfo;
23struct IndexPath;
24
25/* Likewise, this file shouldn't depend on execnodes.h. */
26struct IndexInfo;
27
28
29/*
30 * Properties for amproperty API. This list covers properties known to the
31 * core code, but an index AM can define its own properties, by matching the
32 * string property name.
33 */
34typedef enum IndexAMProperty
35{
36 AMPROP_UNKNOWN = 0, /* anything not known to core code */
37 AMPROP_ASC, /* column properties */
38 AMPROP_DESC,
39 AMPROP_NULLS_FIRST,
40 AMPROP_NULLS_LAST,
41 AMPROP_ORDERABLE,
42 AMPROP_DISTANCE_ORDERABLE,
43 AMPROP_RETURNABLE,
44 AMPROP_SEARCH_ARRAY,
45 AMPROP_SEARCH_NULLS,
46 AMPROP_CLUSTERABLE, /* index properties */
47 AMPROP_INDEX_SCAN,
48 AMPROP_BITMAP_SCAN,
49 AMPROP_BACKWARD_SCAN,
50 AMPROP_CAN_ORDER, /* AM properties */
51 AMPROP_CAN_UNIQUE,
52 AMPROP_CAN_MULTI_COL,
53 AMPROP_CAN_EXCLUDE,
54 AMPROP_CAN_INCLUDE
55} IndexAMProperty;
56
57
58/*
59 * Callback function signatures --- see indexam.sgml for more info.
60 */
61
62/* build new index */
63typedef IndexBuildResult *(*ambuild_function) (Relation heapRelation,
64 Relation indexRelation,
65 struct IndexInfo *indexInfo);
66
67/* build empty index */
68typedef void (*ambuildempty_function) (Relation indexRelation);
69
70/* insert this tuple */
71typedef bool (*aminsert_function) (Relation indexRelation,
72 Datum *values,
73 bool *isnull,
74 ItemPointer heap_tid,
75 Relation heapRelation,
76 IndexUniqueCheck checkUnique,
77 struct IndexInfo *indexInfo);
78
79/* bulk delete */
80typedef IndexBulkDeleteResult *(*ambulkdelete_function) (IndexVacuumInfo *info,
81 IndexBulkDeleteResult *stats,
82 IndexBulkDeleteCallback callback,
83 void *callback_state);
84
85/* post-VACUUM cleanup */
86typedef IndexBulkDeleteResult *(*amvacuumcleanup_function) (IndexVacuumInfo *info,
87 IndexBulkDeleteResult *stats);
88
89/* can indexscan return IndexTuples? */
90typedef bool (*amcanreturn_function) (Relation indexRelation, int attno);
91
92/* estimate cost of an indexscan */
93typedef void (*amcostestimate_function) (struct PlannerInfo *root,
94 struct IndexPath *path,
95 double loop_count,
96 Cost *indexStartupCost,
97 Cost *indexTotalCost,
98 Selectivity *indexSelectivity,
99 double *indexCorrelation,
100 double *indexPages);
101
102/* parse index reloptions */
103typedef bytea *(*amoptions_function) (Datum reloptions,
104 bool validate);
105
106/* report AM, index, or index column property */
107typedef bool (*amproperty_function) (Oid index_oid, int attno,
108 IndexAMProperty prop, const char *propname,
109 bool *res, bool *isnull);
110
111/* name of phase as used in progress reporting */
112typedef char *(*ambuildphasename_function) (int64 phasenum);
113
114/* validate definition of an opclass for this AM */
115typedef bool (*amvalidate_function) (Oid opclassoid);
116
117/* prepare for index scan */
118typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation,
119 int nkeys,
120 int norderbys);
121
122/* (re)start index scan */
123typedef void (*amrescan_function) (IndexScanDesc scan,
124 ScanKey keys,
125 int nkeys,
126 ScanKey orderbys,
127 int norderbys);
128
129/* next valid tuple */
130typedef bool (*amgettuple_function) (IndexScanDesc scan,
131 ScanDirection direction);
132
133/* fetch all valid tuples */
134typedef int64 (*amgetbitmap_function) (IndexScanDesc scan,
135 TIDBitmap *tbm);
136
137/* end index scan */
138typedef void (*amendscan_function) (IndexScanDesc scan);
139
140/* mark current scan position */
141typedef void (*ammarkpos_function) (IndexScanDesc scan);
142
143/* restore marked scan position */
144typedef void (*amrestrpos_function) (IndexScanDesc scan);
145
146/*
147 * Callback function signatures - for parallel index scans.
148 */
149
150/* estimate size of parallel scan descriptor */
151typedef Size (*amestimateparallelscan_function) (void);
152
153/* prepare for parallel index scan */
154typedef void (*aminitparallelscan_function) (void *target);
155
156/* (re)start parallel index scan */
157typedef void (*amparallelrescan_function) (IndexScanDesc scan);
158
159/*
160 * API struct for an index AM. Note this must be stored in a single palloc'd
161 * chunk of memory.
162 */
163typedef struct IndexAmRoutine
164{
165 NodeTag type;
166
167 /*
168 * Total number of strategies (operators) by which we can traverse/search
169 * this AM. Zero if AM does not have a fixed set of strategy assignments.
170 */
171 uint16 amstrategies;
172 /* total number of support functions that this AM uses */
173 uint16 amsupport;
174 /* does AM support ORDER BY indexed column's value? */
175 bool amcanorder;
176 /* does AM support ORDER BY result of an operator on indexed column? */
177 bool amcanorderbyop;
178 /* does AM support backward scanning? */
179 bool amcanbackward;
180 /* does AM support UNIQUE indexes? */
181 bool amcanunique;
182 /* does AM support multi-column indexes? */
183 bool amcanmulticol;
184 /* does AM require scans to have a constraint on the first index column? */
185 bool amoptionalkey;
186 /* does AM handle ScalarArrayOpExpr quals? */
187 bool amsearcharray;
188 /* does AM handle IS NULL/IS NOT NULL quals? */
189 bool amsearchnulls;
190 /* can index storage data type differ from column data type? */
191 bool amstorage;
192 /* can an index of this type be clustered on? */
193 bool amclusterable;
194 /* does AM handle predicate locks? */
195 bool ampredlocks;
196 /* does AM support parallel scan? */
197 bool amcanparallel;
198 /* does AM support columns included with clause INCLUDE? */
199 bool amcaninclude;
200 /* type of data stored in index, or InvalidOid if variable */
201 Oid amkeytype;
202
203 /*
204 * If you add new properties to either the above or the below lists, then
205 * they should also (usually) be exposed via the property API (see
206 * IndexAMProperty at the top of the file, and utils/adt/amutils.c).
207 */
208
209 /* interface functions */
210 ambuild_function ambuild;
211 ambuildempty_function ambuildempty;
212 aminsert_function aminsert;
213 ambulkdelete_function ambulkdelete;
214 amvacuumcleanup_function amvacuumcleanup;
215 amcanreturn_function amcanreturn; /* can be NULL */
216 amcostestimate_function amcostestimate;
217 amoptions_function amoptions;
218 amproperty_function amproperty; /* can be NULL */
219 ambuildphasename_function ambuildphasename; /* can be NULL */
220 amvalidate_function amvalidate;
221 ambeginscan_function ambeginscan;
222 amrescan_function amrescan;
223 amgettuple_function amgettuple; /* can be NULL */
224 amgetbitmap_function amgetbitmap; /* can be NULL */
225 amendscan_function amendscan;
226 ammarkpos_function ammarkpos; /* can be NULL */
227 amrestrpos_function amrestrpos; /* can be NULL */
228
229 /* interface functions to support parallel index scans */
230 amestimateparallelscan_function amestimateparallelscan; /* can be NULL */
231 aminitparallelscan_function aminitparallelscan; /* can be NULL */
232 amparallelrescan_function amparallelrescan; /* can be NULL */
233} IndexAmRoutine;
234
235
236/* Functions in access/index/amapi.c */
237extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
238extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
239
240#endif /* AMAPI_H */
241