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 */ 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 */ 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, 82 IndexBulkDeleteCallback callback, 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 /* name of phase as used in progress reporting */ 112 typedef char *(*ambuildphasename_function) (int64 phasenum); 113 114 /* validate definition of an opclass for this AM */ 115 typedef bool (*amvalidate_function) (Oid opclassoid); 116 117 /* prepare for index scan */ 118 typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation, 119 int nkeys, 120 int norderbys); 121 122 /* (re)start index scan */ 123 typedef void (*amrescan_function) (IndexScanDesc scan, 124 ScanKey keys, 125 int nkeys, 126 ScanKey orderbys, 127 int norderbys); 128 129 /* next valid tuple */ 130 typedef bool (*amgettuple_function) (IndexScanDesc scan, 131 ScanDirection direction); 132 133 /* fetch all valid tuples */ 134 typedef int64 (*amgetbitmap_function) (IndexScanDesc scan, 135 TIDBitmap *tbm); 136 137 /* end index scan */ 138 typedef void (*amendscan_function) (IndexScanDesc scan); 139 140 /* mark current scan position */ 141 typedef void (*ammarkpos_function) (IndexScanDesc scan); 142 143 /* restore marked scan position */ 144 typedef void (*amrestrpos_function) (IndexScanDesc scan); 145 146 /* 147 * Callback function signatures - for parallel index scans. 148 */ 149 150 /* estimate size of parallel scan descriptor */ 151 typedef Size (*amestimateparallelscan_function) (void); 152 153 /* prepare for parallel index scan */ 154 typedef void (*aminitparallelscan_function) (void *target); 155 156 /* (re)start parallel index scan */ 157 typedef 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 */ 163 typedef 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 /* opclass options support function number or 0 */ 175 uint16 amoptsprocnum; 176 /* does AM support ORDER BY indexed column's value? */ 177 bool amcanorder; 178 /* does AM support ORDER BY result of an operator on indexed column? */ 179 bool amcanorderbyop; 180 /* does AM support backward scanning? */ 181 bool amcanbackward; 182 /* does AM support UNIQUE indexes? */ 183 bool amcanunique; 184 /* does AM support multi-column indexes? */ 185 bool amcanmulticol; 186 /* does AM require scans to have a constraint on the first index column? */ 187 bool amoptionalkey; 188 /* does AM handle ScalarArrayOpExpr quals? */ 189 bool amsearcharray; 190 /* does AM handle IS NULL/IS NOT NULL quals? */ 191 bool amsearchnulls; 192 /* can index storage data type differ from column data type? */ 193 bool amstorage; 194 /* can an index of this type be clustered on? */ 195 bool amclusterable; 196 /* does AM handle predicate locks? */ 197 bool ampredlocks; 198 /* does AM support parallel scan? */ 199 bool amcanparallel; 200 /* does AM support columns included with clause INCLUDE? */ 201 bool amcaninclude; 202 /* does AM use maintenance_work_mem? */ 203 bool amusemaintenanceworkmem; 204 /* OR of parallel vacuum flags. See vacuum.h for flags. */ 205 uint8 amparallelvacuumoptions; 206 /* type of data stored in index, or InvalidOid if variable */ 207 Oid amkeytype; 208 209 /* 210 * If you add new properties to either the above or the below lists, then 211 * they should also (usually) be exposed via the property API (see 212 * IndexAMProperty at the top of the file, and utils/adt/amutils.c). 213 */ 214 215 /* interface functions */ 216 ambuild_function ambuild; 217 ambuildempty_function ambuildempty; 218 aminsert_function aminsert; 219 ambulkdelete_function ambulkdelete; 220 amvacuumcleanup_function amvacuumcleanup; 221 amcanreturn_function amcanreturn; /* can be NULL */ 222 amcostestimate_function amcostestimate; 223 amoptions_function amoptions; 224 amproperty_function amproperty; /* can be NULL */ 225 ambuildphasename_function ambuildphasename; /* can be NULL */ 226 amvalidate_function amvalidate; 227 ambeginscan_function ambeginscan; 228 amrescan_function amrescan; 229 amgettuple_function amgettuple; /* can be NULL */ 230 amgetbitmap_function amgetbitmap; /* can be NULL */ 231 amendscan_function amendscan; 232 ammarkpos_function ammarkpos; /* can be NULL */ 233 amrestrpos_function amrestrpos; /* can be NULL */ 234 235 /* interface functions to support parallel index scans */ 236 amestimateparallelscan_function amestimateparallelscan; /* can be NULL */ 237 aminitparallelscan_function aminitparallelscan; /* can be NULL */ 238 amparallelrescan_function amparallelrescan; /* can be NULL */ 239 } IndexAmRoutine; 240 241 242 /* Functions in access/index/amapi.c */ 243 extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler); 244 extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror); 245 246 #endif /* AMAPI_H */ 247