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-2020, 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  struct IndexInfo *indexInfo);
114 
115 /* bulk delete */
116 typedef IndexBulkDeleteResult *(*ambulkdelete_function) (IndexVacuumInfo *info,
117  IndexBulkDeleteResult *stats,
119  void *callback_state);
120 
121 /* post-VACUUM cleanup */
122 typedef IndexBulkDeleteResult *(*amvacuumcleanup_function) (IndexVacuumInfo *info,
123  IndexBulkDeleteResult *stats);
124 
125 /* can indexscan return IndexTuples? */
126 typedef bool (*amcanreturn_function) (Relation indexRelation, int attno);
127 
128 /* estimate cost of an indexscan */
129 typedef void (*amcostestimate_function) (struct PlannerInfo *root,
130  struct IndexPath *path,
131  double loop_count,
132  Cost *indexStartupCost,
133  Cost *indexTotalCost,
134  Selectivity *indexSelectivity,
135  double *indexCorrelation,
136  double *indexPages);
137 
138 /* parse index reloptions */
139 typedef bytea *(*amoptions_function) (Datum reloptions,
140  bool validate);
141 
142 /* report AM, index, or index column property */
143 typedef bool (*amproperty_function) (Oid index_oid, int attno,
144  IndexAMProperty prop, const char *propname,
145  bool *res, bool *isnull);
146 
147 /* name of phase as used in progress reporting */
148 typedef char *(*ambuildphasename_function) (int64 phasenum);
149 
150 /* validate definition of an opclass for this AM */
151 typedef bool (*amvalidate_function) (Oid opclassoid);
152 
153 /* validate operators and support functions to be added to an opclass/family */
154 typedef void (*amadjustmembers_function) (Oid opfamilyoid,
155  Oid opclassoid,
156  List *operators,
157  List *functions);
158 
159 /* prepare for index scan */
160 typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation,
161  int nkeys,
162  int norderbys);
163 
164 /* (re)start index scan */
165 typedef void (*amrescan_function) (IndexScanDesc scan,
166  ScanKey keys,
167  int nkeys,
168  ScanKey orderbys,
169  int norderbys);
170 
171 /* next valid tuple */
173  ScanDirection direction);
174 
175 /* fetch all valid tuples */
176 typedef int64 (*amgetbitmap_function) (IndexScanDesc scan,
177  TIDBitmap *tbm);
178 
179 /* end index scan */
180 typedef void (*amendscan_function) (IndexScanDesc scan);
181 
182 /* mark current scan position */
183 typedef void (*ammarkpos_function) (IndexScanDesc scan);
184 
185 /* restore marked scan position */
186 typedef void (*amrestrpos_function) (IndexScanDesc scan);
187 
188 /*
189  * Callback function signatures - for parallel index scans.
190  */
191 
192 /* estimate size of parallel scan descriptor */
194 
195 /* prepare for parallel index scan */
196 typedef void (*aminitparallelscan_function) (void *target);
197 
198 /* (re)start parallel index scan */
200 
201 /*
202  * API struct for an index AM. Note this must be stored in a single palloc'd
203  * chunk of memory.
204  */
205 typedef struct IndexAmRoutine
206 {
208 
209  /*
210  * Total number of strategies (operators) by which we can traverse/search
211  * this AM. Zero if AM does not have a fixed set of strategy assignments.
212  */
214  /* total number of support functions that this AM uses */
216  /* opclass options support function number or 0 */
218  /* does AM support ORDER BY indexed column's value? */
220  /* does AM support ORDER BY result of an operator on indexed column? */
222  /* does AM support backward scanning? */
224  /* does AM support UNIQUE indexes? */
226  /* does AM support multi-column indexes? */
228  /* does AM require scans to have a constraint on the first index column? */
230  /* does AM handle ScalarArrayOpExpr quals? */
232  /* does AM handle IS NULL/IS NOT NULL quals? */
234  /* can index storage data type differ from column data type? */
235  bool amstorage;
236  /* can an index of this type be clustered on? */
238  /* does AM handle predicate locks? */
240  /* does AM support parallel scan? */
242  /* does AM support columns included with clause INCLUDE? */
244  /* does AM use maintenance_work_mem? */
246  /* OR of parallel vacuum flags. See vacuum.h for flags. */
248  /* type of data stored in index, or InvalidOid if variable */
250 
251  /*
252  * If you add new properties to either the above or the below lists, then
253  * they should also (usually) be exposed via the property API (see
254  * IndexAMProperty at the top of the file, and utils/adt/amutils.c).
255  */
256 
257  /* interface functions */
266  amproperty_function amproperty; /* can be NULL */
272  amgettuple_function amgettuple; /* can be NULL */
275  ammarkpos_function ammarkpos; /* can be NULL */
276  amrestrpos_function amrestrpos; /* can be NULL */
277 
278  /* interface functions to support parallel index scans */
283 
284 
285 /* Functions in access/index/amapi.c */
286 extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
287 extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
288 
289 #endif /* AMAPI_H */
ambeginscan_function ambeginscan
Definition: amapi.h:270
bool(* amgettuple_function)(IndexScanDesc scan, ScanDirection direction)
Definition: amapi.h:172
uint8 amparallelvacuumoptions
Definition: amapi.h:247
bool(* aminsert_function)(Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_tid, Relation heapRelation, IndexUniqueCheck checkUnique, struct IndexInfo *indexInfo)
Definition: amapi.h:107
bool ref_is_hard
Definition: amapi.h:88
ambulkdelete_function ambulkdelete
Definition: amapi.h:261
bool amcanmulticol
Definition: amapi.h:227
uint16 amsupport
Definition: amapi.h:215
NodeTag type
Definition: amapi.h:207
IndexBulkDeleteResult *(* ambulkdelete_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state)
Definition: amapi.h:116
void(* amadjustmembers_function)(Oid opfamilyoid, Oid opclassoid, List *operators, List *functions)
Definition: amapi.h:154
Path path
Definition: pathnodes.h:1206
IndexAMProperty
Definition: amapi.h:34
void(* amrestrpos_function)(IndexScanDesc scan)
Definition: amapi.h:186
amgettuple_function amgettuple
Definition: amapi.h:272
int number
Definition: amapi.h:84
bool amcanorderbyop
Definition: amapi.h:221
amproperty_function amproperty
Definition: amapi.h:266
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:281
bool amstorage
Definition: amapi.h:235
unsigned char uint8
Definition: c.h:372
bool ampredlocks
Definition: amapi.h:239
aminsert_function aminsert
Definition: amapi.h:260
double Selectivity
Definition: nodes.h:662
unsigned int Oid
Definition: postgres_ext.h:31
NodeTag
Definition: nodes.h:26
Oid amkeytype
Definition: amapi.h:249
bool amoptionalkey
Definition: amapi.h:229
amvalidate_function amvalidate
Definition: amapi.h:268
IndexUniqueCheck
Definition: genam.h:112
Oid righttype
Definition: amapi.h:86
bool is_func
Definition: amapi.h:82
Size(* amestimateparallelscan_function)(void)
Definition: amapi.h:193
unsigned short uint16
Definition: c.h:373
bool(* amvalidate_function)(Oid opclassoid)
Definition: amapi.h:151
amgetbitmap_function amgetbitmap
Definition: amapi.h:273
char *(* ambuildphasename_function)(int64 phasenum)
Definition: amapi.h:148
bool(* amproperty_function)(Oid index_oid, int attno, IndexAMProperty prop, const char *propname, bool *res, bool *isnull)
Definition: amapi.h:143
ambuild_function ambuild
Definition: amapi.h:258
amoptions_function amoptions
Definition: amapi.h:265
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
bool amcaninclude
Definition: amapi.h:243
amcostestimate_function amcostestimate
Definition: amapi.h:264
bool amcanunique
Definition: amapi.h:225
amvacuumcleanup_function amvacuumcleanup
Definition: amapi.h:262
amendscan_function amendscan
Definition: amapi.h:274
void(* amrescan_function)(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: amapi.h:165
bool amcanbackward
Definition: amapi.h:223
ScanDirection
Definition: sdir.h:22
struct IndexAmRoutine IndexAmRoutine
struct OpFamilyMember OpFamilyMember
void(* aminitparallelscan_function)(void *target)
Definition: amapi.h:196
int64(* amgetbitmap_function)(IndexScanDesc scan, TIDBitmap *tbm)
Definition: amapi.h:176
amrescan_function amrescan
Definition: amapi.h:271
bool amcanparallel
Definition: amapi.h:241
bool amsearchnulls
Definition: amapi.h:233
uintptr_t Datum
Definition: postgres.h:367
void(* amparallelrescan_function)(IndexScanDesc scan)
Definition: amapi.h:199
bool amclusterable
Definition: amapi.h:237
bool amsearcharray
Definition: amapi.h:231
bool amusemaintenanceworkmem
Definition: amapi.h:245
IndexScanDesc(* ambeginscan_function)(Relation indexRelation, int nkeys, int norderbys)
Definition: amapi.h:160
amadjustmembers_function amadjustmembers
Definition: amapi.h:269
size_t Size
Definition: c.h:473
static const struct fns functions
Definition: regcomp.c:298
void(* amendscan_function)(IndexScanDesc scan)
Definition: amapi.h:180
ammarkpos_function ammarkpos
Definition: amapi.h:275
bool amcanorder
Definition: amapi.h:219
ambuildphasename_function ambuildphasename
Definition: amapi.h:267
bool ref_is_family
Definition: amapi.h:89
amestimateparallelscan_function amestimateparallelscan
Definition: amapi.h:279
uint16 amstrategies
Definition: amapi.h:213
static Datum values[MAXATTR]
Definition: bootstrap.c:165
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:217
Oid sortfamily
Definition: amapi.h:87
ambuildempty_function ambuildempty
Definition: amapi.h:259
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:129
Definition: c.h:562
bytea *(* amoptions_function)(Datum reloptions, bool validate)
Definition: amapi.h:139
void(* ammarkpos_function)(IndexScanDesc scan)
Definition: amapi.h:183
Definition: pg_list.h:50
amcanreturn_function amcanreturn
Definition: amapi.h:263
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:87
IndexBulkDeleteResult *(* amvacuumcleanup_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Definition: amapi.h:122
double Cost
Definition: nodes.h:663
bool(* amcanreturn_function)(Relation indexRelation, int attno)
Definition: amapi.h:126
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:84
aminitparallelscan_function aminitparallelscan
Definition: amapi.h:280
unsigned char bool
Definition: c.h:324
amrestrpos_function amrestrpos
Definition: amapi.h:276