PostgreSQL Source Code  git master
amapi.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * amapi.h
4  * API for Postgres index access methods.
5  *
6  * Copyright (c) 2015-2021, 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  */
22 struct PlannerInfo;
23 struct IndexPath;
24 
25 /* Likewise, this file shouldn't depend on execnodes.h. */
26 struct 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  */
34 typedef enum IndexAMProperty
35 {
36  AMPROP_UNKNOWN = 0, /* anything not known to core code */
37  AMPROP_ASC, /* column properties */
46  AMPROP_CLUSTERABLE, /* index properties */
50  AMPROP_CAN_ORDER, /* AM properties */
56 
57 /*
58  * We use lists of this struct type to keep track of both operators and
59  * support functions while building or adding to an opclass or opfamily.
60  * amadjustmembers functions receive lists of these structs, and are allowed
61  * to alter their "ref" fields.
62  *
63  * The "ref" fields define how the pg_amop or pg_amproc entry should depend
64  * on the associated objects (that is, which dependency type to use, and
65  * which opclass or opfamily it should depend on).
66  *
67  * If ref_is_hard is true, the entry will have a NORMAL dependency on the
68  * operator or support func, and an INTERNAL dependency on the opclass or
69  * opfamily. This forces the opclass or opfamily to be dropped if the
70  * operator or support func is dropped, and requires the CASCADE option
71  * to do so. Nor will ALTER OPERATOR FAMILY DROP be allowed. This is
72  * the right behavior for objects that are essential to an opclass.
73  *
74  * If ref_is_hard is false, the entry will have an AUTO dependency on the
75  * operator or support func, and also an AUTO dependency on the opclass or
76  * opfamily. This allows ALTER OPERATOR FAMILY DROP, and causes that to
77  * happen automatically if the operator or support func is dropped. This
78  * is the right behavior for inessential ("loose") objects.
79  */
80 typedef struct OpFamilyMember
81 {
82  bool is_func; /* is this an operator, or support func? */
83  Oid object; /* operator or support func's OID */
84  int number; /* strategy or support func number */
85  Oid lefttype; /* lefttype */
86  Oid righttype; /* righttype */
87  Oid sortfamily; /* ordering operator's sort opfamily, or 0 */
88  bool ref_is_hard; /* hard or soft dependency? */
89  bool ref_is_family; /* is dependency on opclass or opfamily? */
90  Oid refobjid; /* OID of opclass or opfamily */
92 
93 
94 /*
95  * Callback function signatures --- see indexam.sgml for more info.
96  */
97 
98 /* build new index */
99 typedef IndexBuildResult *(*ambuild_function) (Relation heapRelation,
100  Relation indexRelation,
101  struct IndexInfo *indexInfo);
102 
103 /* build empty index */
104 typedef void (*ambuildempty_function) (Relation indexRelation);
105 
106 /* insert this tuple */
107 typedef bool (*aminsert_function) (Relation indexRelation,
108  Datum *values,
109  bool *isnull,
110  ItemPointer heap_tid,
111  Relation heapRelation,
112  IndexUniqueCheck checkUnique,
113  bool indexUnchanged,
114  struct IndexInfo *indexInfo);
115 
116 /* bulk delete */
117 typedef IndexBulkDeleteResult *(*ambulkdelete_function) (IndexVacuumInfo *info,
118  IndexBulkDeleteResult *stats,
120  void *callback_state);
121 
122 /* post-VACUUM cleanup */
123 typedef IndexBulkDeleteResult *(*amvacuumcleanup_function) (IndexVacuumInfo *info,
124  IndexBulkDeleteResult *stats);
125 
126 /* can indexscan return IndexTuples? */
127 typedef bool (*amcanreturn_function) (Relation indexRelation, int attno);
128 
129 /* estimate cost of an indexscan */
130 typedef void (*amcostestimate_function) (struct PlannerInfo *root,
131  struct IndexPath *path,
132  double loop_count,
133  Cost *indexStartupCost,
134  Cost *indexTotalCost,
135  Selectivity *indexSelectivity,
136  double *indexCorrelation,
137  double *indexPages);
138 
139 /* parse index reloptions */
140 typedef bytea *(*amoptions_function) (Datum reloptions,
141  bool validate);
142 
143 /* report AM, index, or index column property */
144 typedef bool (*amproperty_function) (Oid index_oid, int attno,
145  IndexAMProperty prop, const char *propname,
146  bool *res, bool *isnull);
147 
148 /* name of phase as used in progress reporting */
149 typedef char *(*ambuildphasename_function) (int64 phasenum);
150 
151 /* validate definition of an opclass for this AM */
152 typedef bool (*amvalidate_function) (Oid opclassoid);
153 
154 /* validate operators and support functions to be added to an opclass/family */
155 typedef void (*amadjustmembers_function) (Oid opfamilyoid,
156  Oid opclassoid,
157  List *operators,
158  List *functions);
159 
160 /* prepare for index scan */
161 typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation,
162  int nkeys,
163  int norderbys);
164 
165 /* (re)start index scan */
166 typedef void (*amrescan_function) (IndexScanDesc scan,
167  ScanKey keys,
168  int nkeys,
169  ScanKey orderbys,
170  int norderbys);
171 
172 /* next valid tuple */
174  ScanDirection direction);
175 
176 /* fetch all valid tuples */
177 typedef int64 (*amgetbitmap_function) (IndexScanDesc scan,
178  TIDBitmap *tbm);
179 
180 /* end index scan */
181 typedef void (*amendscan_function) (IndexScanDesc scan);
182 
183 /* mark current scan position */
184 typedef void (*ammarkpos_function) (IndexScanDesc scan);
185 
186 /* restore marked scan position */
187 typedef void (*amrestrpos_function) (IndexScanDesc scan);
188 
189 /*
190  * Callback function signatures - for parallel index scans.
191  */
192 
193 /* estimate size of parallel scan descriptor */
195 
196 /* prepare for parallel index scan */
197 typedef void (*aminitparallelscan_function) (void *target);
198 
199 /* (re)start parallel index scan */
201 
202 /*
203  * API struct for an index AM. Note this must be stored in a single palloc'd
204  * chunk of memory.
205  */
206 typedef struct IndexAmRoutine
207 {
209 
210  /*
211  * Total number of strategies (operators) by which we can traverse/search
212  * this AM. Zero if AM does not have a fixed set of strategy assignments.
213  */
215  /* total number of support functions that this AM uses */
217  /* opclass options support function number or 0 */
219  /* does AM support ORDER BY indexed column's value? */
221  /* does AM support ORDER BY result of an operator on indexed column? */
223  /* does AM support backward scanning? */
225  /* does AM support UNIQUE indexes? */
227  /* does AM support multi-column indexes? */
229  /* does AM require scans to have a constraint on the first index column? */
231  /* does AM handle ScalarArrayOpExpr quals? */
233  /* does AM handle IS NULL/IS NOT NULL quals? */
235  /* can index storage data type differ from column data type? */
236  bool amstorage;
237  /* can an index of this type be clustered on? */
239  /* does AM handle predicate locks? */
241  /* does AM support parallel scan? */
243  /* does AM support columns included with clause INCLUDE? */
245  /* does AM use maintenance_work_mem? */
247  /* OR of parallel vacuum flags. See vacuum.h for flags. */
249  /* type of data stored in index, or InvalidOid if variable */
251 
252  /*
253  * If you add new properties to either the above or the below lists, then
254  * they should also (usually) be exposed via the property API (see
255  * IndexAMProperty at the top of the file, and utils/adt/amutils.c).
256  */
257 
258  /* interface functions */
267  amproperty_function amproperty; /* can be NULL */
273  amgettuple_function amgettuple; /* can be NULL */
276  ammarkpos_function ammarkpos; /* can be NULL */
277  amrestrpos_function amrestrpos; /* can be NULL */
278 
279  /* interface functions to support parallel index scans */
284 
285 
286 /* Functions in access/index/amapi.c */
287 extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
288 extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
289 
290 #endif /* AMAPI_H */
ambeginscan_function ambeginscan
Definition: amapi.h:271
bool(* amgettuple_function)(IndexScanDesc scan, ScanDirection direction)
Definition: amapi.h:173
uint8 amparallelvacuumoptions
Definition: amapi.h:248
bool ref_is_hard
Definition: amapi.h:88
ambulkdelete_function ambulkdelete
Definition: amapi.h:262
bool amcanmulticol
Definition: amapi.h:228
uint16 amsupport
Definition: amapi.h:216
NodeTag type
Definition: amapi.h:208
IndexBulkDeleteResult *(* ambulkdelete_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state)
Definition: amapi.h:117
void(* amadjustmembers_function)(Oid opfamilyoid, Oid opclassoid, List *operators, List *functions)
Definition: amapi.h:155
Path path
Definition: pathnodes.h:1236
IndexAMProperty
Definition: amapi.h:34
void(* amrestrpos_function)(IndexScanDesc scan)
Definition: amapi.h:187
amgettuple_function amgettuple
Definition: amapi.h:273
int number
Definition: amapi.h:84
bool amcanorderbyop
Definition: amapi.h:222
amproperty_function amproperty
Definition: amapi.h:267
void(* ambuildempty_function)(Relation indexRelation)
Definition: amapi.h:104
IndexBuildResult *(* ambuild_function)(Relation heapRelation, Relation indexRelation, struct IndexInfo *indexInfo)
Definition: amapi.h:99
amparallelrescan_function amparallelrescan
Definition: amapi.h:282
bool amstorage
Definition: amapi.h:236
unsigned char uint8
Definition: c.h:439
bool ampredlocks
Definition: amapi.h:240
aminsert_function aminsert
Definition: amapi.h:261
double Selectivity
Definition: nodes.h:672
unsigned int Oid
Definition: postgres_ext.h:31
NodeTag
Definition: nodes.h:26
Oid amkeytype
Definition: amapi.h:250
bool amoptionalkey
Definition: amapi.h:230
amvalidate_function amvalidate
Definition: amapi.h:269
IndexUniqueCheck
Definition: genam.h:114
Oid righttype
Definition: amapi.h:86
bool is_func
Definition: amapi.h:82
Size(* amestimateparallelscan_function)(void)
Definition: amapi.h:194
unsigned short uint16
Definition: c.h:440
bool(* amvalidate_function)(Oid opclassoid)
Definition: amapi.h:152
amgetbitmap_function amgetbitmap
Definition: amapi.h:274
char *(* ambuildphasename_function)(int64 phasenum)
Definition: amapi.h:149
bool(* amproperty_function)(Oid index_oid, int attno, IndexAMProperty prop, const char *propname, bool *res, bool *isnull)
Definition: amapi.h:144
ambuild_function ambuild
Definition: amapi.h:259
amoptions_function amoptions
Definition: amapi.h:266
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
bool amcaninclude
Definition: amapi.h:244
amcostestimate_function amcostestimate
Definition: amapi.h:265
bool amcanunique
Definition: amapi.h:226
amvacuumcleanup_function amvacuumcleanup
Definition: amapi.h:263
amendscan_function amendscan
Definition: amapi.h:275
void(* amrescan_function)(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: amapi.h:166
bool amcanbackward
Definition: amapi.h:224
ScanDirection
Definition: sdir.h:22
struct IndexAmRoutine IndexAmRoutine
struct OpFamilyMember OpFamilyMember
void(* aminitparallelscan_function)(void *target)
Definition: amapi.h:197
int64(* amgetbitmap_function)(IndexScanDesc scan, TIDBitmap *tbm)
Definition: amapi.h:177
amrescan_function amrescan
Definition: amapi.h:272
bool amcanparallel
Definition: amapi.h:242
bool amsearchnulls
Definition: amapi.h:234
uintptr_t Datum
Definition: postgres.h:411
void(* amparallelrescan_function)(IndexScanDesc scan)
Definition: amapi.h:200
bool amclusterable
Definition: amapi.h:238
bool(* aminsert_function)(Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_tid, Relation heapRelation, IndexUniqueCheck checkUnique, bool indexUnchanged, struct IndexInfo *indexInfo)
Definition: amapi.h:107
bool amsearcharray
Definition: amapi.h:232
bool amusemaintenanceworkmem
Definition: amapi.h:246
IndexScanDesc(* ambeginscan_function)(Relation indexRelation, int nkeys, int norderbys)
Definition: amapi.h:161
amadjustmembers_function amadjustmembers
Definition: amapi.h:270
size_t Size
Definition: c.h:540
static const struct fns functions
Definition: regcomp.c:313
void(* amendscan_function)(IndexScanDesc scan)
Definition: amapi.h:181
ammarkpos_function ammarkpos
Definition: amapi.h:276
bool amcanorder
Definition: amapi.h:220
ambuildphasename_function ambuildphasename
Definition: amapi.h:268
bool ref_is_family
Definition: amapi.h:89
amestimateparallelscan_function amestimateparallelscan
Definition: amapi.h:280
uint16 amstrategies
Definition: amapi.h:214
static Datum values[MAXATTR]
Definition: bootstrap.c:166
IndexAmRoutine * GetIndexAmRoutineByAmId(Oid amoid, bool noerror)
Definition: amapi.c:56
IndexAmRoutine * GetIndexAmRoutine(Oid amhandler)
Definition: amapi.c:33
Oid object
Definition: amapi.h:83
uint16 amoptsprocnum
Definition: amapi.h:218
Oid sortfamily
Definition: amapi.h:87
ambuildempty_function ambuildempty
Definition: amapi.h:260
Oid lefttype
Definition: amapi.h:85
Oid refobjid
Definition: amapi.h:90
void(* amcostestimate_function)(struct PlannerInfo *root, struct IndexPath *path, double loop_count, Cost *indexStartupCost, Cost *indexTotalCost, Selectivity *indexSelectivity, double *indexCorrelation, double *indexPages)
Definition: amapi.h:130
Definition: c.h:621
bytea *(* amoptions_function)(Datum reloptions, bool validate)
Definition: amapi.h:140
void(* ammarkpos_function)(IndexScanDesc scan)
Definition: amapi.h:184
Definition: pg_list.h:50
amcanreturn_function amcanreturn
Definition: amapi.h:264
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:89
IndexBulkDeleteResult *(* amvacuumcleanup_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Definition: amapi.h:123
double Cost
Definition: nodes.h:673
bool(* amcanreturn_function)(Relation indexRelation, int attno)
Definition: amapi.h:127
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:86
aminitparallelscan_function aminitparallelscan
Definition: amapi.h:281
unsigned char bool
Definition: c.h:391
amrestrpos_function amrestrpos
Definition: amapi.h:277