src/include/access/genam.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * genam.h
   4  *        POSTGRES generalized index access method definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2021, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/access/genam.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef GENAM_H
  15 #define GENAM_H
  16
  17 #include "access/sdir.h"
  18 #include "access/skey.h"
  19 #include "nodes/tidbitmap.h"
  20 #include "storage/lockdefs.h"
  21 #include "utils/relcache.h"
  22 #include "utils/snapshot.h"
  23
  24 /* We don't want this file to depend on execnodes.h. */
  25 struct IndexInfo;
  26
  27 /*
  28  * Struct for statistics returned by ambuild
  29  */
  30 typedef struct IndexBuildResult
  31 {
  32         double          heap_tuples;    /* # of tuples seen in parent table */
  33         double          index_tuples;   /* # of tuples inserted into index */
  34 } IndexBuildResult;
  35
  36 /*
  37  * Struct for input arguments passed to ambulkdelete and amvacuumcleanup
  38  *
  39  * num_heap_tuples is accurate only when estimated_count is false;
  40  * otherwise it's just an estimate (currently, the estimate is the
  41  * prior value of the relation's pg_class.reltuples field, so it could
  42  * even be -1).  It will always just be an estimate during ambulkdelete.
  43  */
  44 typedef struct IndexVacuumInfo
  45 {
  46         Relation        index;                  /* the index being vacuumed */
  47         bool            analyze_only;   /* ANALYZE (without any actual vacuum) */
  48         bool            report_progress;        /* emit progress.h status reports */
  49         bool            estimated_count;        /* num_heap_tuples is an estimate */
  50         int                     message_level;  /* ereport level for progress messages */
  51         double          num_heap_tuples;        /* tuples remaining in heap */
  52         BufferAccessStrategy strategy;  /* access strategy for reads */
  53 } IndexVacuumInfo;
  54
  55 /*
  56  * Struct for statistics returned by ambulkdelete and amvacuumcleanup
  57  *
  58  * This struct is normally allocated by the first ambulkdelete call and then
  59  * passed along through subsequent ones until amvacuumcleanup; however,
  60  * amvacuumcleanup must be prepared to allocate it in the case where no
  61  * ambulkdelete calls were made (because no tuples needed deletion).
  62  * Note that an index AM could choose to return a larger struct
  63  * of which this is just the first field; this provides a way for ambulkdelete
  64  * to communicate additional private data to amvacuumcleanup.
  65  *
  66  * Note: pages_newly_deleted is the number of pages in the index that were
  67  * deleted by the current vacuum operation.  pages_deleted and pages_free
  68  * refer to free space within the index file.
  69  *
  70  * Note: Some index AMs may compute num_index_tuples by reference to
  71  * num_heap_tuples, in which case they should copy the estimated_count field
  72  * from IndexVacuumInfo.
  73  */
  74 typedef struct IndexBulkDeleteResult
  75 {
  76         BlockNumber num_pages;          /* pages remaining in index */
  77         bool            estimated_count;        /* num_index_tuples is an estimate */
  78         double          num_index_tuples;       /* tuples remaining */
  79         double          tuples_removed; /* # removed during vacuum operation */
  80         BlockNumber pages_newly_deleted;        /* # pages marked deleted by us  */
  81         BlockNumber pages_deleted;      /* # pages marked deleted (could be by us) */
  82         BlockNumber pages_free;         /* # pages available for reuse */
  83 } IndexBulkDeleteResult;
  84
  85 /* Typedef for callback function to determine if a tuple is bulk-deletable */
  86 typedef bool (*IndexBulkDeleteCallback) (ItemPointer itemptr, void *state);
  87
  88 /* struct definitions appear in relscan.h */
  89 typedef struct IndexScanDescData *IndexScanDesc;
  90 typedef struct SysScanDescData *SysScanDesc;
  91
  92 typedef struct ParallelIndexScanDescData *ParallelIndexScanDesc;
  93
  94 /*
  95  * Enumeration specifying the type of uniqueness check to perform in
  96  * index_insert().
  97  *
  98  * UNIQUE_CHECK_YES is the traditional Postgres immediate check, possibly
  99  * blocking to see if a conflicting transaction commits.
 100  *
 101  * For deferrable unique constraints, UNIQUE_CHECK_PARTIAL is specified at
 102  * insertion time.  The index AM should test if the tuple is unique, but
 103  * should not throw error, block, or prevent the insertion if the tuple
 104  * appears not to be unique.  We'll recheck later when it is time for the
 105  * constraint to be enforced.  The AM must return true if the tuple is
 106  * known unique, false if it is possibly non-unique.  In the "true" case
 107  * it is safe to omit the later recheck.
 108  *
 109  * When it is time to recheck the deferred constraint, a pseudo-insertion
 110  * call is made with UNIQUE_CHECK_EXISTING.  The tuple is already in the
 111  * index in this case, so it should not be inserted again.  Rather, just
 112  * check for conflicting live tuples (possibly blocking).
 113  */
 114 typedef enum IndexUniqueCheck
 115 {
 116         UNIQUE_CHECK_NO,                        /* Don't do any uniqueness checking */
 117         UNIQUE_CHECK_YES,                       /* Enforce uniqueness at insertion time */
 118         UNIQUE_CHECK_PARTIAL,           /* Test uniqueness, but no error */
 119         UNIQUE_CHECK_EXISTING           /* Check if existing tuple is unique */
 120 } IndexUniqueCheck;
 121
 122
 123 /* Nullable "ORDER BY col op const" distance */
 124 typedef struct IndexOrderByDistance
 125 {
 126         double          value;
 127         bool            isnull;
 128 } IndexOrderByDistance;
 129
 130 /*
 131  * generalized index_ interface routines (in indexam.c)
 132  */
 133
 134 /*
 135  * IndexScanIsValid
 136  *              True iff the index scan is valid.
 137  */
 138 #define IndexScanIsValid(scan) PointerIsValid(scan)
 139
 140 extern Relation index_open(Oid relationId, LOCKMODE lockmode);
 141 extern void index_close(Relation relation, LOCKMODE lockmode);
 142
 143 extern bool index_insert(Relation indexRelation,
 144                                                  Datum *values, bool *isnull,
 145                                                  ItemPointer heap_t_ctid,
 146                                                  Relation heapRelation,
 147                                                  IndexUniqueCheck checkUnique,
 148                                                  bool indexUnchanged,
 149                                                  struct IndexInfo *indexInfo);
 150
 151 extern IndexScanDesc index_beginscan(Relation heapRelation,
 152                                                                          Relation indexRelation,
 153                                                                          Snapshot snapshot,
 154                                                                          int nkeys, int norderbys);
 155 extern IndexScanDesc index_beginscan_bitmap(Relation indexRelation,
 156                                                                                         Snapshot snapshot,
 157                                                                                         int nkeys);
 158 extern void index_rescan(IndexScanDesc scan,
 159                                                  ScanKey keys, int nkeys,
 160                                                  ScanKey orderbys, int norderbys);
 161 extern void index_endscan(IndexScanDesc scan);
 162 extern void index_markpos(IndexScanDesc scan);
 163 extern void index_restrpos(IndexScanDesc scan);
 164 extern Size index_parallelscan_estimate(Relation indexrel, Snapshot snapshot);
 165 extern void index_parallelscan_initialize(Relation heaprel, Relation indexrel,
 166                                                                                   Snapshot snapshot, ParallelIndexScanDesc target);
 167 extern void index_parallelrescan(IndexScanDesc scan);
 168 extern IndexScanDesc index_beginscan_parallel(Relation heaprel,
 169                                                                                           Relation indexrel, int nkeys, int norderbys,
 170                                                                                           ParallelIndexScanDesc pscan);
 171 extern ItemPointer index_getnext_tid(IndexScanDesc scan,
 172                                                                          ScanDirection direction);
 173 struct TupleTableSlot;
 174 extern bool index_fetch_heap(IndexScanDesc scan, struct TupleTableSlot *slot);
 175 extern bool index_getnext_slot(IndexScanDesc scan, ScanDirection direction,
 176                                                            struct TupleTableSlot *slot);
 177 extern int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap);
 178
 179 extern IndexBulkDeleteResult *index_bulk_delete(IndexVacuumInfo *info,
 180                                                                                                 IndexBulkDeleteResult *istat,
 181                                                                                                 IndexBulkDeleteCallback callback,
 182                                                                                                 void *callback_state);
 183 extern IndexBulkDeleteResult *index_vacuum_cleanup(IndexVacuumInfo *info,
 184                                                                                                    IndexBulkDeleteResult *istat);
 185 extern bool index_can_return(Relation indexRelation, int attno);
 186 extern RegProcedure index_getprocid(Relation irel, AttrNumber attnum,
 187                                                                         uint16 procnum);
 188 extern FmgrInfo *index_getprocinfo(Relation irel, AttrNumber attnum,
 189                                                                    uint16 procnum);
 190 extern void index_store_float8_orderby_distances(IndexScanDesc scan,
 191                                                                                                  Oid *orderByTypes,
 192                                                                                                  IndexOrderByDistance *distances,
 193                                                                                                  bool recheckOrderBy);
 194 extern bytea *index_opclass_options(Relation relation, AttrNumber attnum,
 195                                                                         Datum attoptions, bool validate);
 196
 197
 198 /*
 199  * index access method support routines (in genam.c)
 200  */
 201 extern IndexScanDesc RelationGetIndexScan(Relation indexRelation,
 202                                                                                   int nkeys, int norderbys);
 203 extern void IndexScanEnd(IndexScanDesc scan);
 204 extern char *BuildIndexValueDescription(Relation indexRelation,
 205                                                                                 Datum *values, bool *isnull);
 206 extern TransactionId index_compute_xid_horizon_for_tuples(Relation irel,
 207                                                                                                                   Relation hrel,
 208                                                                                                                   Buffer ibuf,
 209                                                                                                                   OffsetNumber *itemnos,
 210                                                                                                                   int nitems);
 211
 212 /*
 213  * heap-or-index access to system catalogs (in genam.c)
 214  */
 215 extern SysScanDesc systable_beginscan(Relation heapRelation,
 216                                                                           Oid indexId,
 217                                                                           bool indexOK,
 218                                                                           Snapshot snapshot,
 219                                                                           int nkeys, ScanKey key);
 220 extern HeapTuple systable_getnext(SysScanDesc sysscan);
 221 extern bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup);
 222 extern void systable_endscan(SysScanDesc sysscan);
 223 extern SysScanDesc systable_beginscan_ordered(Relation heapRelation,
 224                                                                                           Relation indexRelation,
 225                                                                                           Snapshot snapshot,
 226                                                                                           int nkeys, ScanKey key);
 227 extern HeapTuple systable_getnext_ordered(SysScanDesc sysscan,
 228                                                                                   ScanDirection direction);
 229 extern void systable_endscan_ordered(SysScanDesc sysscan);
 230
 231 #endif                                                  /* GENAM_H */