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-2022, 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  /* does AM block HOT update? */
249  /* OR of parallel vacuum flags. See vacuum.h for flags. */
251  /* type of data stored in index, or InvalidOid if variable */
253 
254  /*
255  * If you add new properties to either the above or the below lists, then
256  * they should also (usually) be exposed via the property API (see
257  * IndexAMProperty at the top of the file, and utils/adt/amutils.c).
258  */
259 
260  /* interface functions */
269  amproperty_function amproperty; /* can be NULL */
275  amgettuple_function amgettuple; /* can be NULL */
278  ammarkpos_function ammarkpos; /* can be NULL */
279  amrestrpos_function amrestrpos; /* can be NULL */
280 
281  /* interface functions to support parallel index scans */
286 
287 
288 /* Functions in access/index/amapi.c */
289 extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
290 extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
291 
292 #endif /* AMAPI_H */
void(* amparallelrescan_function)(IndexScanDesc scan)
Definition: amapi.h:200
IndexScanDesc(* ambeginscan_function)(Relation indexRelation, int nkeys, int norderbys)
Definition: amapi.h:161
void(* amadjustmembers_function)(Oid opfamilyoid, Oid opclassoid, List *operators, List *functions)
Definition: amapi.h:155
bool(* amproperty_function)(Oid index_oid, int attno, IndexAMProperty prop, const char *propname, bool *res, bool *isnull)
Definition: amapi.h:144
bool(* amvalidate_function)(Oid opclassoid)
Definition: amapi.h:152
void(* amendscan_function)(IndexScanDesc scan)
Definition: amapi.h:181
bool(* amcanreturn_function)(Relation indexRelation, int attno)
Definition: amapi.h:127
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
void(* ambuildempty_function)(Relation indexRelation)
Definition: amapi.h:104
IndexAmRoutine * GetIndexAmRoutineByAmId(Oid amoid, bool noerror)
Definition: amapi.c:56
IndexBulkDeleteResult *(* ambulkdelete_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state)
Definition: amapi.h:117
IndexAmRoutine * GetIndexAmRoutine(Oid amhandler)
Definition: amapi.c:33
int64(* amgetbitmap_function)(IndexScanDesc scan, TIDBitmap *tbm)
Definition: amapi.h:177
Size(* amestimateparallelscan_function)(void)
Definition: amapi.h:194
void(* amrestrpos_function)(IndexScanDesc scan)
Definition: amapi.h:187
IndexBulkDeleteResult *(* amvacuumcleanup_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Definition: amapi.h:123
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
bool(* amgettuple_function)(IndexScanDesc scan, ScanDirection direction)
Definition: amapi.h:173
IndexAMProperty
Definition: amapi.h:35
@ AMPROP_BACKWARD_SCAN
Definition: amapi.h:49
@ AMPROP_SEARCH_ARRAY
Definition: amapi.h:44
@ AMPROP_CAN_MULTI_COL
Definition: amapi.h:52
@ AMPROP_CAN_ORDER
Definition: amapi.h:50
@ AMPROP_ORDERABLE
Definition: amapi.h:41
@ AMPROP_ASC
Definition: amapi.h:37
@ AMPROP_DISTANCE_ORDERABLE
Definition: amapi.h:42
@ AMPROP_CAN_INCLUDE
Definition: amapi.h:54
@ AMPROP_SEARCH_NULLS
Definition: amapi.h:45
@ AMPROP_CAN_EXCLUDE
Definition: amapi.h:53
@ AMPROP_UNKNOWN
Definition: amapi.h:36
@ AMPROP_CAN_UNIQUE
Definition: amapi.h:51
@ AMPROP_DESC
Definition: amapi.h:38
@ AMPROP_NULLS_LAST
Definition: amapi.h:40
@ AMPROP_INDEX_SCAN
Definition: amapi.h:47
@ AMPROP_NULLS_FIRST
Definition: amapi.h:39
@ AMPROP_CLUSTERABLE
Definition: amapi.h:46
@ AMPROP_RETURNABLE
Definition: amapi.h:43
@ AMPROP_BITMAP_SCAN
Definition: amapi.h:48
bytea *(* amoptions_function)(Datum reloptions, bool validate)
Definition: amapi.h:140
void(* aminitparallelscan_function)(void *target)
Definition: amapi.h:197
void(* ammarkpos_function)(IndexScanDesc scan)
Definition: amapi.h:184
struct OpFamilyMember OpFamilyMember
IndexBuildResult *(* ambuild_function)(Relation heapRelation, Relation indexRelation, struct IndexInfo *indexInfo)
Definition: amapi.h:99
struct IndexAmRoutine IndexAmRoutine
char *(* ambuildphasename_function)(int64 phasenum)
Definition: amapi.h:149
void(* amrescan_function)(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: amapi.h:166
static Datum values[MAXATTR]
Definition: bootstrap.c:156
unsigned short uint16
Definition: c.h:440
unsigned char bool
Definition: c.h:391
unsigned char uint8
Definition: c.h:439
size_t Size
Definition: c.h:540
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:86
IndexUniqueCheck
Definition: genam.h:115
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:89
double Cost
Definition: nodes.h:673
NodeTag
Definition: nodes.h:27
double Selectivity
Definition: nodes.h:672
uintptr_t Datum
Definition: postgres.h:411
unsigned int Oid
Definition: postgres_ext.h:31
static const struct fns functions
Definition: regcomp.c:313
ScanDirection
Definition: sdir.h:23
ambuildphasename_function ambuildphasename
Definition: amapi.h:270
ambuildempty_function ambuildempty
Definition: amapi.h:262
amvacuumcleanup_function amvacuumcleanup
Definition: amapi.h:265
bool amclusterable
Definition: amapi.h:238
amoptions_function amoptions
Definition: amapi.h:268
amestimateparallelscan_function amestimateparallelscan
Definition: amapi.h:282
amrestrpos_function amrestrpos
Definition: amapi.h:279
aminsert_function aminsert
Definition: amapi.h:263
amendscan_function amendscan
Definition: amapi.h:277
uint16 amoptsprocnum
Definition: amapi.h:218
amparallelrescan_function amparallelrescan
Definition: amapi.h:284
Oid amkeytype
Definition: amapi.h:252
bool ampredlocks
Definition: amapi.h:240
uint16 amsupport
Definition: amapi.h:216
amcostestimate_function amcostestimate
Definition: amapi.h:267
bool amcanorderbyop
Definition: amapi.h:222
amadjustmembers_function amadjustmembers
Definition: amapi.h:272
ambuild_function ambuild
Definition: amapi.h:261
bool amstorage
Definition: amapi.h:236
uint16 amstrategies
Definition: amapi.h:214
bool amoptionalkey
Definition: amapi.h:230
amgettuple_function amgettuple
Definition: amapi.h:275
amcanreturn_function amcanreturn
Definition: amapi.h:266
bool amcanunique
Definition: amapi.h:226
amgetbitmap_function amgetbitmap
Definition: amapi.h:276
amproperty_function amproperty
Definition: amapi.h:269
ambulkdelete_function ambulkdelete
Definition: amapi.h:264
bool amsearcharray
Definition: amapi.h:232
amvalidate_function amvalidate
Definition: amapi.h:271
ammarkpos_function ammarkpos
Definition: amapi.h:278
bool amcanmulticol
Definition: amapi.h:228
bool amusemaintenanceworkmem
Definition: amapi.h:246
ambeginscan_function ambeginscan
Definition: amapi.h:273
bool amcanparallel
Definition: amapi.h:242
amrescan_function amrescan
Definition: amapi.h:274
bool amcanorder
Definition: amapi.h:220
bool amhotblocking
Definition: amapi.h:248
aminitparallelscan_function aminitparallelscan
Definition: amapi.h:283
uint8 amparallelvacuumoptions
Definition: amapi.h:250
bool amcanbackward
Definition: amapi.h:224
NodeTag type
Definition: amapi.h:208
bool amcaninclude
Definition: amapi.h:244
bool amsearchnulls
Definition: amapi.h:234
Path path
Definition: pathnodes.h:1245
Definition: pg_list.h:51
Oid refobjid
Definition: amapi.h:90
Oid lefttype
Definition: amapi.h:85
bool ref_is_family
Definition: amapi.h:89
Oid righttype
Definition: amapi.h:86
int number
Definition: amapi.h:84
Oid object
Definition: amapi.h:83
bool is_func
Definition: amapi.h:82
bool ref_is_hard
Definition: amapi.h:88
Oid sortfamily
Definition: amapi.h:87
Definition: c.h:622
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48