src/include/access/amapi.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * amapi.h
   4  *        API for Postgres index access methods.
   5  *
   6  * Copyright (c) 2015-2024, 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  * 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  * We also make dependencies on lefttype/righttype, of the same strength as
  81  * the dependency on the operator or support func, unless these dependencies
  82  * are redundant with the dependency on the operator or support func.
  83  */
  84 typedef struct OpFamilyMember
  85 {
  86         bool            is_func;                /* is this an operator, or support func? */
  87         Oid                     object;                 /* operator or support func's OID */
  88         int                     number;                 /* strategy or support func number */
  89         Oid                     lefttype;               /* lefttype */
  90         Oid                     righttype;              /* righttype */
  91         Oid                     sortfamily;             /* ordering operator's sort opfamily, or 0 */
  92         bool            ref_is_hard;    /* hard or soft dependency? */
  93         bool            ref_is_family;  /* is dependency on opclass or opfamily? */
  94         Oid                     refobjid;               /* OID of opclass or opfamily */
  95 } OpFamilyMember;
  96
  97
  98 /*
  99  * Callback function signatures --- see indexam.sgml for more info.
 100  */
 101
 102 /* build new index */
 103 typedef IndexBuildResult *(*ambuild_function) (Relation heapRelation,
 104                                                                                            Relation indexRelation,
 105                                                                                            struct IndexInfo *indexInfo);
 106
 107 /* build empty index */
 108 typedef void (*ambuildempty_function) (Relation indexRelation);
 109
 110 /* insert this tuple */
 111 typedef bool (*aminsert_function) (Relation indexRelation,
 112                                                                    Datum *values,
 113                                                                    bool *isnull,
 114                                                                    ItemPointer heap_tid,
 115                                                                    Relation heapRelation,
 116                                                                    IndexUniqueCheck checkUnique,
 117                                                                    bool indexUnchanged,
 118                                                                    struct IndexInfo *indexInfo);
 119
 120 /* cleanup after insert */
 121 typedef void (*aminsertcleanup_function) (Relation indexRelation,
 122                                                                                   struct IndexInfo *indexInfo);
 123
 124 /* bulk delete */
 125 typedef IndexBulkDeleteResult *(*ambulkdelete_function) (IndexVacuumInfo *info,
 126                                                                                                                  IndexBulkDeleteResult *stats,
 127                                                                                                                  IndexBulkDeleteCallback callback,
 128                                                                                                                  void *callback_state);
 129
 130 /* post-VACUUM cleanup */
 131 typedef IndexBulkDeleteResult *(*amvacuumcleanup_function) (IndexVacuumInfo *info,
 132                                                                                                                         IndexBulkDeleteResult *stats);
 133
 134 /* can indexscan return IndexTuples? */
 135 typedef bool (*amcanreturn_function) (Relation indexRelation, int attno);
 136
 137 /* estimate cost of an indexscan */
 138 typedef void (*amcostestimate_function) (struct PlannerInfo *root,
 139                                                                                  struct IndexPath *path,
 140                                                                                  double loop_count,
 141                                                                                  Cost *indexStartupCost,
 142                                                                                  Cost *indexTotalCost,
 143                                                                                  Selectivity *indexSelectivity,
 144                                                                                  double *indexCorrelation,
 145                                                                                  double *indexPages);
 146
 147 /* estimate height of a tree-structured index
 148  *
 149  * XXX This just computes a value that is later used by amcostestimate.  This
 150  * API could be expanded to support passing more values if the need arises.
 151  */
 152 typedef int (*amgettreeheight_function) (Relation rel);
 153
 154 /* parse index reloptions */
 155 typedef bytea *(*amoptions_function) (Datum reloptions,
 156                                                                           bool validate);
 157
 158 /* report AM, index, or index column property */
 159 typedef bool (*amproperty_function) (Oid index_oid, int attno,
 160                                                                          IndexAMProperty prop, const char *propname,
 161                                                                          bool *res, bool *isnull);
 162
 163 /* name of phase as used in progress reporting */
 164 typedef char *(*ambuildphasename_function) (int64 phasenum);
 165
 166 /* validate definition of an opclass for this AM */
 167 typedef bool (*amvalidate_function) (Oid opclassoid);
 168
 169 /* validate operators and support functions to be added to an opclass/family */
 170 typedef void (*amadjustmembers_function) (Oid opfamilyoid,
 171                                                                                   Oid opclassoid,
 172                                                                                   List *operators,
 173                                                                                   List *functions);
 174
 175 /* prepare for index scan */
 176 typedef IndexScanDesc (*ambeginscan_function) (Relation indexRelation,
 177                                                                                            int nkeys,
 178                                                                                            int norderbys);
 179
 180 /* (re)start index scan */
 181 typedef void (*amrescan_function) (IndexScanDesc scan,
 182                                                                    ScanKey keys,
 183                                                                    int nkeys,
 184                                                                    ScanKey orderbys,
 185                                                                    int norderbys);
 186
 187 /* next valid tuple */
 188 typedef bool (*amgettuple_function) (IndexScanDesc scan,
 189                                                                          ScanDirection direction);
 190
 191 /* fetch all valid tuples */
 192 typedef int64 (*amgetbitmap_function) (IndexScanDesc scan,
 193                                                                            TIDBitmap *tbm);
 194
 195 /* end index scan */
 196 typedef void (*amendscan_function) (IndexScanDesc scan);
 197
 198 /* mark current scan position */
 199 typedef void (*ammarkpos_function) (IndexScanDesc scan);
 200
 201 /* restore marked scan position */
 202 typedef void (*amrestrpos_function) (IndexScanDesc scan);
 203
 204 /*
 205  * Callback function signatures - for parallel index scans.
 206  */
 207
 208 /* estimate size of parallel scan descriptor */
 209 typedef Size (*amestimateparallelscan_function) (int nkeys, int norderbys);
 210
 211 /* prepare for parallel index scan */
 212 typedef void (*aminitparallelscan_function) (void *target);
 213
 214 /* (re)start parallel index scan */
 215 typedef void (*amparallelrescan_function) (IndexScanDesc scan);
 216
 217 /*
 218  * API struct for an index AM.  Note this must be stored in a single palloc'd
 219  * chunk of memory.
 220  */
 221 typedef struct IndexAmRoutine
 222 {
 223         NodeTag         type;
 224
 225         /*
 226          * Total number of strategies (operators) by which we can traverse/search
 227          * this AM.  Zero if AM does not have a fixed set of strategy assignments.
 228          */
 229         uint16          amstrategies;
 230         /* total number of support functions that this AM uses */
 231         uint16          amsupport;
 232         /* opclass options support function number or 0 */
 233         uint16          amoptsprocnum;
 234         /* does AM support ORDER BY indexed column's value? */
 235         bool            amcanorder;
 236         /* does AM support ORDER BY result of an operator on indexed column? */
 237         bool            amcanorderbyop;
 238         /* does AM support backward scanning? */
 239         bool            amcanbackward;
 240         /* does AM support UNIQUE indexes? */
 241         bool            amcanunique;
 242         /* does AM support multi-column indexes? */
 243         bool            amcanmulticol;
 244         /* does AM require scans to have a constraint on the first index column? */
 245         bool            amoptionalkey;
 246         /* does AM handle ScalarArrayOpExpr quals? */
 247         bool            amsearcharray;
 248         /* does AM handle IS NULL/IS NOT NULL quals? */
 249         bool            amsearchnulls;
 250         /* can index storage data type differ from column data type? */
 251         bool            amstorage;
 252         /* can an index of this type be clustered on? */
 253         bool            amclusterable;
 254         /* does AM handle predicate locks? */
 255         bool            ampredlocks;
 256         /* does AM support parallel scan? */
 257         bool            amcanparallel;
 258         /* does AM support parallel build? */
 259         bool            amcanbuildparallel;
 260         /* does AM support columns included with clause INCLUDE? */
 261         bool            amcaninclude;
 262         /* does AM use maintenance_work_mem? */
 263         bool            amusemaintenanceworkmem;
 264         /* does AM store tuple information only at block granularity? */
 265         bool            amsummarizing;
 266         /* OR of parallel vacuum flags.  See vacuum.h for flags. */
 267         uint8           amparallelvacuumoptions;
 268         /* type of data stored in index, or InvalidOid if variable */
 269         Oid                     amkeytype;
 270
 271         /*
 272          * If you add new properties to either the above or the below lists, then
 273          * they should also (usually) be exposed via the property API (see
 274          * IndexAMProperty at the top of the file, and utils/adt/amutils.c).
 275          */
 276
 277         /* interface functions */
 278         ambuild_function ambuild;
 279         ambuildempty_function ambuildempty;
 280         aminsert_function aminsert;
 281         aminsertcleanup_function aminsertcleanup;
 282         ambulkdelete_function ambulkdelete;
 283         amvacuumcleanup_function amvacuumcleanup;
 284         amcanreturn_function amcanreturn;       /* can be NULL */
 285         amcostestimate_function amcostestimate;
 286         amgettreeheight_function amgettreeheight;       /* can be NULL */
 287         amoptions_function amoptions;
 288         amproperty_function amproperty; /* can be NULL */
 289         ambuildphasename_function ambuildphasename; /* can be NULL */
 290         amvalidate_function amvalidate;
 291         amadjustmembers_function amadjustmembers;       /* can be NULL */
 292         ambeginscan_function ambeginscan;
 293         amrescan_function amrescan;
 294         amgettuple_function amgettuple; /* can be NULL */
 295         amgetbitmap_function amgetbitmap;       /* can be NULL */
 296         amendscan_function amendscan;
 297         ammarkpos_function ammarkpos;   /* can be NULL */
 298         amrestrpos_function amrestrpos; /* can be NULL */
 299
 300         /* interface functions to support parallel index scans */
 301         amestimateparallelscan_function amestimateparallelscan; /* can be NULL */
 302         aminitparallelscan_function aminitparallelscan; /* can be NULL */
 303         amparallelrescan_function amparallelrescan; /* can be NULL */
 304 } IndexAmRoutine;
 305
 306
 307 /* Functions in access/index/amapi.c */
 308 extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
 309 extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
 310
 311 #endif                                                  /* AMAPI_H */