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-2018, 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 /*
59  * Callback function signatures --- see indexam.sgml for more info.
60  */
61 
62 /* build new index */
63 typedef IndexBuildResult *(*ambuild_function) (Relation heapRelation,
64  Relation indexRelation,
65  struct IndexInfo *indexInfo);
66 
67 /* build empty index */
68 typedef void (*ambuildempty_function) (Relation indexRelation);
69 
70 /* insert this tuple */
71 typedef 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 */
80 typedef IndexBulkDeleteResult *(*ambulkdelete_function) (IndexVacuumInfo *info,
81  IndexBulkDeleteResult *stats,
83  void *callback_state);
84 
85 /* post-VACUUM cleanup */
86 typedef IndexBulkDeleteResult *(*amvacuumcleanup_function) (IndexVacuumInfo *info,
87  IndexBulkDeleteResult *stats);
88 
89 /* can indexscan return IndexTuples? */
90 typedef bool (*amcanreturn_function) (Relation indexRelation, int attno);
91 
92 /* estimate cost of an indexscan */
93 typedef 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 */
103 typedef bytea *(*amoptions_function) (Datum reloptions,
104  bool validate);
105 
106 /* report AM, index, or index column property */
107 typedef bool (*amproperty_function) (Oid index_oid, int attno,
108  IndexAMProperty prop, const char *propname,
109  bool *res, bool *isnull);
110 
111 /* validate definition of an opclass for this AM */
112 typedef bool (*amvalidate_function) (Oid opclassoid);
113 
114 /* prepare for index scan */
115 typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation,
116  int nkeys,
117  int norderbys);
118 
119 /* (re)start index scan */
120 typedef void (*amrescan_function) (IndexScanDesc scan,
121  ScanKey keys,
122  int nkeys,
123  ScanKey orderbys,
124  int norderbys);
125 
126 /* next valid tuple */
128  ScanDirection direction);
129 
130 /* fetch all valid tuples */
131 typedef int64 (*amgetbitmap_function) (IndexScanDesc scan,
132  TIDBitmap *tbm);
133 
134 /* end index scan */
135 typedef void (*amendscan_function) (IndexScanDesc scan);
136 
137 /* mark current scan position */
138 typedef void (*ammarkpos_function) (IndexScanDesc scan);
139 
140 /* restore marked scan position */
141 typedef void (*amrestrpos_function) (IndexScanDesc scan);
142 
143 /*
144  * Callback function signatures - for parallel index scans.
145  */
146 
147 /* estimate size of parallel scan descriptor */
149 
150 /* prepare for parallel index scan */
151 typedef void (*aminitparallelscan_function) (void *target);
152 
153 /* (re)start parallel index scan */
155 
156 /*
157  * API struct for an index AM. Note this must be stored in a single palloc'd
158  * chunk of memory.
159  */
160 typedef struct IndexAmRoutine
161 {
163 
164  /*
165  * Total number of strategies (operators) by which we can traverse/search
166  * this AM. Zero if AM does not have a fixed set of strategy assignments.
167  */
169  /* total number of support functions that this AM uses */
171  /* does AM support ORDER BY indexed column's value? */
173  /* does AM support ORDER BY result of an operator on indexed column? */
175  /* does AM support backward scanning? */
177  /* does AM support UNIQUE indexes? */
179  /* does AM support multi-column indexes? */
181  /* does AM require scans to have a constraint on the first index column? */
183  /* does AM handle ScalarArrayOpExpr quals? */
185  /* does AM handle IS NULL/IS NOT NULL quals? */
187  /* can index storage data type differ from column data type? */
188  bool amstorage;
189  /* can an index of this type be clustered on? */
191  /* does AM handle predicate locks? */
193  /* does AM support parallel scan? */
195  /* does AM support columns included with clause INCLUDE? */
197  /* type of data stored in index, or InvalidOid if variable */
199 
200  /*
201  * If you add new properties to either the above or the below lists, then
202  * they should also (usually) be exposed via the property API (see
203  * IndexAMProperty at the top of the file, and utils/adt/amutils.c).
204  */
205 
206  /* interface functions */
215  amproperty_function amproperty; /* can be NULL */
219  amgettuple_function amgettuple; /* can be NULL */
222  ammarkpos_function ammarkpos; /* can be NULL */
223  amrestrpos_function amrestrpos; /* can be NULL */
224 
225  /* interface functions to support parallel index scans */
230 
231 
232 /* Functions in access/index/amapi.c */
233 extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
234 extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
235 
236 #endif /* AMAPI_H */
ambeginscan_function ambeginscan
Definition: amapi.h:217
bool(* amgettuple_function)(IndexScanDesc scan, ScanDirection direction)
Definition: amapi.h:127
bool(* aminsert_function)(Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_tid, Relation heapRelation, IndexUniqueCheck checkUnique, struct IndexInfo *indexInfo)
Definition: amapi.h:71
ambulkdelete_function ambulkdelete
Definition: amapi.h:210
bool amcanmulticol
Definition: amapi.h:180
uint16 amsupport
Definition: amapi.h:170
NodeTag type
Definition: amapi.h:162
IndexBulkDeleteResult *(* ambulkdelete_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state)
Definition: amapi.h:80
Path path
Definition: relation.h:1154
IndexAMProperty
Definition: amapi.h:34
void(* amrestrpos_function)(IndexScanDesc scan)
Definition: amapi.h:141
amgettuple_function amgettuple
Definition: amapi.h:219
bool amcanorderbyop
Definition: amapi.h:174
amproperty_function amproperty
Definition: amapi.h:215
void(* ambuildempty_function)(Relation indexRelation)
Definition: amapi.h:68
IndexBuildResult *(* ambuild_function)(Relation heapRelation, Relation indexRelation, struct IndexInfo *indexInfo)
Definition: amapi.h:63
amparallelrescan_function amparallelrescan
Definition: amapi.h:228
bool amstorage
Definition: amapi.h:188
bool ampredlocks
Definition: amapi.h:192
aminsert_function aminsert
Definition: amapi.h:209
double Selectivity
Definition: nodes.h:647
unsigned int Oid
Definition: postgres_ext.h:31
NodeTag
Definition: nodes.h:26
Oid amkeytype
Definition: amapi.h:198
bool amoptionalkey
Definition: amapi.h:182
amvalidate_function amvalidate
Definition: amapi.h:216
char bool
Definition: c.h:275
IndexUniqueCheck
Definition: genam.h:111
Size(* amestimateparallelscan_function)(void)
Definition: amapi.h:148
unsigned short uint16
Definition: c.h:324
bool(* amvalidate_function)(Oid opclassoid)
Definition: amapi.h:112
amgetbitmap_function amgetbitmap
Definition: amapi.h:220
bool(* amproperty_function)(Oid index_oid, int attno, IndexAMProperty prop, const char *propname, bool *res, bool *isnull)
Definition: amapi.h:107
ambuild_function ambuild
Definition: amapi.h:207
amoptions_function amoptions
Definition: amapi.h:214
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
bool amcaninclude
Definition: amapi.h:196
amcostestimate_function amcostestimate
Definition: amapi.h:213
bool amcanunique
Definition: amapi.h:178
amvacuumcleanup_function amvacuumcleanup
Definition: amapi.h:211
amendscan_function amendscan
Definition: amapi.h:221
void(* amrescan_function)(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: amapi.h:120
bool amcanbackward
Definition: amapi.h:176
ScanDirection
Definition: sdir.h:22
struct IndexAmRoutine IndexAmRoutine
void(* aminitparallelscan_function)(void *target)
Definition: amapi.h:151
int64(* amgetbitmap_function)(IndexScanDesc scan, TIDBitmap *tbm)
Definition: amapi.h:131
amrescan_function amrescan
Definition: amapi.h:218
bool amcanparallel
Definition: amapi.h:194
bool amsearchnulls
Definition: amapi.h:186
uintptr_t Datum
Definition: postgres.h:365
void(* amparallelrescan_function)(IndexScanDesc scan)
Definition: amapi.h:154
bool amclusterable
Definition: amapi.h:190
bool amsearcharray
Definition: amapi.h:184
IndexScanDesc(* ambeginscan_function)(Relation indexRelation, int nkeys, int norderbys)
Definition: amapi.h:115
size_t Size
Definition: c.h:433
void(* amendscan_function)(IndexScanDesc scan)
Definition: amapi.h:135
ammarkpos_function ammarkpos
Definition: amapi.h:222
bool amcanorder
Definition: amapi.h:172
amestimateparallelscan_function amestimateparallelscan
Definition: amapi.h:226
uint16 amstrategies
Definition: amapi.h:168
static Datum values[MAXATTR]
Definition: bootstrap.c:164
IndexAmRoutine * GetIndexAmRoutineByAmId(Oid amoid, bool noerror)
Definition: amapi.c:56
IndexAmRoutine * GetIndexAmRoutine(Oid amhandler)
Definition: amapi.c:33
ambuildempty_function ambuildempty
Definition: amapi.h:208
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:93
Definition: c.h:516
bytea *(* amoptions_function)(Datum reloptions, bool validate)
Definition: amapi.h:103
void(* ammarkpos_function)(IndexScanDesc scan)
Definition: amapi.h:138
amcanreturn_function amcanreturn
Definition: amapi.h:212
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:86
IndexBulkDeleteResult *(* amvacuumcleanup_function)(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Definition: amapi.h:86
double Cost
Definition: nodes.h:648
bool(* amcanreturn_function)(Relation indexRelation, int attno)
Definition: amapi.h:90
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:83
aminitparallelscan_function aminitparallelscan
Definition: amapi.h:227
amrestrpos_function amrestrpos
Definition: amapi.h:223