PostgreSQL Source Code git master
genam.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * genam.h
4 * POSTGRES generalized index access method definitions.
5 *
6 *
7 * Portions Copyright (c) 1996-2025, 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/htup.h"
18#include "access/sdir.h"
19#include "access/skey.h"
20#include "nodes/tidbitmap.h"
21#include "storage/buf.h"
22#include "storage/lockdefs.h"
23#include "utils/relcache.h"
24#include "utils/snapshot.h"
25
26/* We don't want this file to depend on execnodes.h. */
27struct IndexInfo;
28
29/*
30 * Struct for statistics maintained by amgettuple and amgetbitmap
31 *
32 * Note: IndexScanInstrumentation can't contain any pointers, since it is
33 * copied into a SharedIndexScanInstrumentation during parallel scans
34 */
36{
37 /* Index search count (incremented with pgstat_count_index_scan call) */
40
41/*
42 * Struct for every worker's IndexScanInstrumentation, stored in shared memory
43 */
45{
49
50/*
51 * Struct for statistics returned by ambuild
52 */
53typedef struct IndexBuildResult
54{
55 double heap_tuples; /* # of tuples seen in parent table */
56 double index_tuples; /* # of tuples inserted into index */
58
59/*
60 * Struct for input arguments passed to ambulkdelete and amvacuumcleanup
61 *
62 * num_heap_tuples is accurate only when estimated_count is false;
63 * otherwise it's just an estimate (currently, the estimate is the
64 * prior value of the relation's pg_class.reltuples field, so it could
65 * even be -1). It will always just be an estimate during ambulkdelete.
66 */
67typedef struct IndexVacuumInfo
68{
69 Relation index; /* the index being vacuumed */
70 Relation heaprel; /* the heap relation the index belongs to */
71 bool analyze_only; /* ANALYZE (without any actual vacuum) */
72 bool report_progress; /* emit progress.h status reports */
73 bool estimated_count; /* num_heap_tuples is an estimate */
74 int message_level; /* ereport level for progress messages */
75 double num_heap_tuples; /* tuples remaining in heap */
76 BufferAccessStrategy strategy; /* access strategy for reads */
78
79/*
80 * Struct for statistics returned by ambulkdelete and amvacuumcleanup
81 *
82 * This struct is normally allocated by the first ambulkdelete call and then
83 * passed along through subsequent ones until amvacuumcleanup; however,
84 * amvacuumcleanup must be prepared to allocate it in the case where no
85 * ambulkdelete calls were made (because no tuples needed deletion).
86 * Note that an index AM could choose to return a larger struct
87 * of which this is just the first field; this provides a way for ambulkdelete
88 * to communicate additional private data to amvacuumcleanup.
89 *
90 * Note: pages_newly_deleted is the number of pages in the index that were
91 * deleted by the current vacuum operation. pages_deleted and pages_free
92 * refer to free space within the index file.
93 *
94 * Note: Some index AMs may compute num_index_tuples by reference to
95 * num_heap_tuples, in which case they should copy the estimated_count field
96 * from IndexVacuumInfo.
97 */
99{
100 BlockNumber num_pages; /* pages remaining in index */
101 bool estimated_count; /* num_index_tuples is an estimate */
102 double num_index_tuples; /* tuples remaining */
103 double tuples_removed; /* # removed during vacuum operation */
104 BlockNumber pages_newly_deleted; /* # pages marked deleted by us */
105 BlockNumber pages_deleted; /* # pages marked deleted (could be by us) */
106 BlockNumber pages_free; /* # pages available for reuse */
108
109/* Typedef for callback function to determine if a tuple is bulk-deletable */
110typedef bool (*IndexBulkDeleteCallback) (ItemPointer itemptr, void *state);
111
112/* struct definitions appear in relscan.h */
115
117
118/*
119 * Enumeration specifying the type of uniqueness check to perform in
120 * index_insert().
121 *
122 * UNIQUE_CHECK_YES is the traditional Postgres immediate check, possibly
123 * blocking to see if a conflicting transaction commits.
124 *
125 * For deferrable unique constraints, UNIQUE_CHECK_PARTIAL is specified at
126 * insertion time. The index AM should test if the tuple is unique, but
127 * should not throw error, block, or prevent the insertion if the tuple
128 * appears not to be unique. We'll recheck later when it is time for the
129 * constraint to be enforced. The AM must return true if the tuple is
130 * known unique, false if it is possibly non-unique. In the "true" case
131 * it is safe to omit the later recheck.
132 *
133 * When it is time to recheck the deferred constraint, a pseudo-insertion
134 * call is made with UNIQUE_CHECK_EXISTING. The tuple is already in the
135 * index in this case, so it should not be inserted again. Rather, just
136 * check for conflicting live tuples (possibly blocking).
137 */
139{
140 UNIQUE_CHECK_NO, /* Don't do any uniqueness checking */
141 UNIQUE_CHECK_YES, /* Enforce uniqueness at insertion time */
142 UNIQUE_CHECK_PARTIAL, /* Test uniqueness, but no error */
143 UNIQUE_CHECK_EXISTING, /* Check if existing tuple is unique */
145
146
147/* Nullable "ORDER BY col op const" distance */
149{
150 double value;
151 bool isnull;
153
154/*
155 * generalized index_ interface routines (in indexam.c)
156 */
157
158/*
159 * IndexScanIsValid
160 * True iff the index scan is valid.
161 */
162#define IndexScanIsValid(scan) PointerIsValid(scan)
163
164extern Relation index_open(Oid relationId, LOCKMODE lockmode);
165extern Relation try_index_open(Oid relationId, LOCKMODE lockmode);
166extern void index_close(Relation relation, LOCKMODE lockmode);
167
168extern bool index_insert(Relation indexRelation,
169 Datum *values, bool *isnull,
170 ItemPointer heap_t_ctid,
171 Relation heapRelation,
172 IndexUniqueCheck checkUnique,
173 bool indexUnchanged,
174 struct IndexInfo *indexInfo);
175extern void index_insert_cleanup(Relation indexRelation,
176 struct IndexInfo *indexInfo);
177
178extern IndexScanDesc index_beginscan(Relation heapRelation,
179 Relation indexRelation,
180 Snapshot snapshot,
181 IndexScanInstrumentation *instrument,
182 int nkeys, int norderbys);
184 Snapshot snapshot,
185 IndexScanInstrumentation *instrument,
186 int nkeys);
187extern void index_rescan(IndexScanDesc scan,
188 ScanKey keys, int nkeys,
189 ScanKey orderbys, int norderbys);
190extern void index_endscan(IndexScanDesc scan);
191extern void index_markpos(IndexScanDesc scan);
192extern void index_restrpos(IndexScanDesc scan);
193extern Size index_parallelscan_estimate(Relation indexRelation,
194 int nkeys, int norderbys, Snapshot snapshot,
195 bool instrument, bool parallel_aware,
196 int nworkers);
197extern void index_parallelscan_initialize(Relation heapRelation,
198 Relation indexRelation, Snapshot snapshot,
199 bool instrument, bool parallel_aware,
200 int nworkers,
202 ParallelIndexScanDesc target);
203extern void index_parallelrescan(IndexScanDesc scan);
205 Relation indexrel,
206 IndexScanInstrumentation *instrument,
207 int nkeys, int norderbys,
210 ScanDirection direction);
211struct TupleTableSlot;
212extern bool index_fetch_heap(IndexScanDesc scan, struct TupleTableSlot *slot);
213extern bool index_getnext_slot(IndexScanDesc scan, ScanDirection direction,
214 struct TupleTableSlot *slot);
215extern int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap);
216
220 void *callback_state);
222 IndexBulkDeleteResult *istat);
223extern bool index_can_return(Relation indexRelation, int attno);
225 uint16 procnum);
227 uint16 procnum);
229 Oid *orderByTypes,
230 IndexOrderByDistance *distances,
231 bool recheckOrderBy);
233 Datum attoptions, bool validate);
234
235
236/*
237 * index access method support routines (in genam.c)
238 */
239extern IndexScanDesc RelationGetIndexScan(Relation indexRelation,
240 int nkeys, int norderbys);
241extern void IndexScanEnd(IndexScanDesc scan);
242extern char *BuildIndexValueDescription(Relation indexRelation,
243 const Datum *values, const bool *isnull);
245 Relation hrel,
246 Buffer ibuf,
247 OffsetNumber *itemnos,
248 int nitems);
249
250/*
251 * heap-or-index access to system catalogs (in genam.c)
252 */
253extern SysScanDesc systable_beginscan(Relation heapRelation,
254 Oid indexId,
255 bool indexOK,
256 Snapshot snapshot,
257 int nkeys, ScanKey key);
259extern bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup);
260extern void systable_endscan(SysScanDesc sysscan);
262 Relation indexRelation,
263 Snapshot snapshot,
264 int nkeys, ScanKey key);
266 ScanDirection direction);
267extern void systable_endscan_ordered(SysScanDesc sysscan);
268extern void systable_inplace_update_begin(Relation relation,
269 Oid indexId,
270 bool indexOK,
271 Snapshot snapshot,
272 int nkeys, const ScanKeyData *key,
273 HeapTuple *oldtupcopy,
274 void **state);
275extern void systable_inplace_update_finish(void *state, HeapTuple tuple);
276extern void systable_inplace_update_cancel(void *state);
277
278#endif /* GENAM_H */
int16 AttrNumber
Definition: attnum.h:21
static bool validate(Port *port, const char *auth)
Definition: auth-oauth.c:638
uint32 BlockNumber
Definition: block.h:31
static Datum values[MAXATTR]
Definition: bootstrap.c:151
int Buffer
Definition: buf.h:23
int64_t int64
Definition: c.h:499
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:434
regproc RegProcedure
Definition: c.h:621
uint64_t uint64
Definition: c.h:503
uint16_t uint16
Definition: c.h:501
uint32 TransactionId
Definition: c.h:623
size_t Size
Definition: c.h:576
char * BuildIndexValueDescription(Relation indexRelation, const Datum *values, const bool *isnull)
Definition: genam.c:178
void systable_endscan(SysScanDesc sysscan)
Definition: genam.c:603
void systable_inplace_update_cancel(void *state)
Definition: genam.c:902
void index_parallelscan_initialize(Relation heapRelation, Relation indexRelation, Snapshot snapshot, bool instrument, bool parallel_aware, int nworkers, SharedIndexScanInstrumentation **sharedinfo, ParallelIndexScanDesc target)
Definition: indexam.c:509
struct IndexOrderByDistance IndexOrderByDistance
bool systable_recheck_tuple(SysScanDesc sysscan, HeapTuple tup)
Definition: genam.c:573
bool index_insert(Relation indexRelation, Datum *values, bool *isnull, ItemPointer heap_t_ctid, Relation heapRelation, IndexUniqueCheck checkUnique, bool indexUnchanged, struct IndexInfo *indexInfo)
Definition: indexam.c:213
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:110
void IndexScanEnd(IndexScanDesc scan)
Definition: genam.c:145
IndexUniqueCheck
Definition: genam.h:139
@ UNIQUE_CHECK_NO
Definition: genam.h:140
@ UNIQUE_CHECK_EXISTING
Definition: genam.h:143
@ UNIQUE_CHECK_PARTIAL
Definition: genam.h:142
@ UNIQUE_CHECK_YES
Definition: genam.h:141
IndexScanDesc index_beginscan_parallel(Relation heaprel, Relation indexrel, IndexScanInstrumentation *instrument, int nkeys, int norderbys, ParallelIndexScanDesc pscan)
Definition: indexam.c:582
FmgrInfo * index_getprocinfo(Relation irel, AttrNumber attnum, uint16 procnum)
Definition: indexam.c:906
void index_restrpos(IndexScanDesc scan)
Definition: indexam.c:436
IndexBulkDeleteResult * index_vacuum_cleanup(IndexVacuumInfo *info, IndexBulkDeleteResult *istat)
Definition: indexam.c:815
bytea * index_opclass_options(Relation indrel, AttrNumber attnum, Datum attoptions, bool validate)
Definition: indexam.c:1042
IndexScanDesc index_beginscan(Relation heapRelation, Relation indexRelation, Snapshot snapshot, IndexScanInstrumentation *instrument, int nkeys, int norderbys)
Definition: indexam.c:256
IndexBulkDeleteResult * index_bulk_delete(IndexVacuumInfo *info, IndexBulkDeleteResult *istat, IndexBulkDeleteCallback callback, void *callback_state)
Definition: indexam.c:794
struct IndexVacuumInfo IndexVacuumInfo
void systable_inplace_update_begin(Relation relation, Oid indexId, bool indexOK, Snapshot snapshot, int nkeys, const ScanKeyData *key, HeapTuple *oldtupcopy, void **state)
Definition: genam.c:807
TransactionId index_compute_xid_horizon_for_tuples(Relation irel, Relation hrel, Buffer ibuf, OffsetNumber *itemnos, int nitems)
Definition: genam.c:295
void index_close(Relation relation, LOCKMODE lockmode)
Definition: indexam.c:177
bool index_can_return(Relation indexRelation, int attno)
Definition: indexam.c:834
struct IndexScanInstrumentation IndexScanInstrumentation
struct IndexBuildResult IndexBuildResult
ItemPointer index_getnext_tid(IndexScanDesc scan, ScanDirection direction)
Definition: indexam.c:620
SysScanDesc systable_beginscan_ordered(Relation heapRelation, Relation indexRelation, Snapshot snapshot, int nkeys, ScanKey key)
Definition: genam.c:650
void systable_inplace_update_finish(void *state, HeapTuple tuple)
Definition: genam.c:883
HeapTuple systable_getnext(SysScanDesc sysscan)
Definition: genam.c:514
RegProcedure index_getprocid(Relation irel, AttrNumber attnum, uint16 procnum)
Definition: indexam.c:872
bool index_getnext_slot(IndexScanDesc scan, ScanDirection direction, struct TupleTableSlot *slot)
Definition: indexam.c:719
void systable_endscan_ordered(SysScanDesc sysscan)
Definition: genam.c:757
HeapTuple systable_getnext_ordered(SysScanDesc sysscan, ScanDirection direction)
Definition: genam.c:732
void index_markpos(IndexScanDesc scan)
Definition: indexam.c:412
Relation try_index_open(Oid relationId, LOCKMODE lockmode)
Definition: indexam.c:152
void index_endscan(IndexScanDesc scan)
Definition: indexam.c:382
struct IndexBulkDeleteResult IndexBulkDeleteResult
IndexScanDesc index_beginscan_bitmap(Relation indexRelation, Snapshot snapshot, IndexScanInstrumentation *instrument, int nkeys)
Definition: indexam.c:289
Size index_parallelscan_estimate(Relation indexRelation, int nkeys, int norderbys, Snapshot snapshot, bool instrument, bool parallel_aware, int nworkers)
Definition: indexam.c:461
Relation index_open(Oid relationId, LOCKMODE lockmode)
Definition: indexam.c:133
struct SysScanDescData * SysScanDesc
Definition: genam.h:114
bool index_fetch_heap(IndexScanDesc scan, struct TupleTableSlot *slot)
Definition: indexam.c:678
int64 index_getbitmap(IndexScanDesc scan, TIDBitmap *bitmap)
Definition: indexam.c:764
void index_parallelrescan(IndexScanDesc scan)
Definition: indexam.c:564
void index_rescan(IndexScanDesc scan, ScanKey keys, int nkeys, ScanKey orderbys, int norderbys)
Definition: indexam.c:356
struct ParallelIndexScanDescData * ParallelIndexScanDesc
Definition: genam.h:116
struct IndexScanDescData * IndexScanDesc
Definition: genam.h:113
void index_insert_cleanup(Relation indexRelation, struct IndexInfo *indexInfo)
Definition: indexam.c:241
SysScanDesc systable_beginscan(Relation heapRelation, Oid indexId, bool indexOK, Snapshot snapshot, int nkeys, ScanKey key)
Definition: genam.c:388
struct SharedIndexScanInstrumentation SharedIndexScanInstrumentation
IndexScanDesc RelationGetIndexScan(Relation indexRelation, int nkeys, int norderbys)
Definition: genam.c:80
void index_store_float8_orderby_distances(IndexScanDesc scan, Oid *orderByTypes, IndexOrderByDistance *distances, bool recheckOrderBy)
Definition: indexam.c:974
#define nitems(x)
Definition: indent.h:31
int LOCKMODE
Definition: lockdefs.h:26
uint16 OffsetNumber
Definition: off.h:24
int16 attnum
Definition: pg_attribute.h:74
uintptr_t Datum
Definition: postgres.h:69
unsigned int Oid
Definition: postgres_ext.h:32
ScanDirection
Definition: sdir.h:25
Definition: fmgr.h:57
double heap_tuples
Definition: genam.h:55
double index_tuples
Definition: genam.h:56
BlockNumber pages_deleted
Definition: genam.h:105
BlockNumber pages_newly_deleted
Definition: genam.h:104
BlockNumber pages_free
Definition: genam.h:106
BlockNumber num_pages
Definition: genam.h:100
double tuples_removed
Definition: genam.h:103
double num_index_tuples
Definition: genam.h:102
Relation index
Definition: genam.h:69
double num_heap_tuples
Definition: genam.h:75
bool analyze_only
Definition: genam.h:71
BufferAccessStrategy strategy
Definition: genam.h:76
Relation heaprel
Definition: genam.h:70
bool report_progress
Definition: genam.h:72
int message_level
Definition: genam.h:74
bool estimated_count
Definition: genam.h:73
IndexScanInstrumentation winstrument[FLEXIBLE_ARRAY_MEMBER]
Definition: genam.h:47
Definition: regguts.h:323
Definition: c.h:658
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:46