PostgreSQL Source Code  git master
spgist.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * spgist.h
4  * Public header file for SP-GiST access method.
5  *
6  *
7  * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/access/spgist.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef SPGIST_H
15 #define SPGIST_H
16 
17 #include "access/amapi.h"
18 #include "access/xlogreader.h"
19 #include "lib/stringinfo.h"
20 
21 
22 /* SPGiST opclass support function numbers */
23 #define SPGIST_CONFIG_PROC 1
24 #define SPGIST_CHOOSE_PROC 2
25 #define SPGIST_PICKSPLIT_PROC 3
26 #define SPGIST_INNER_CONSISTENT_PROC 4
27 #define SPGIST_LEAF_CONSISTENT_PROC 5
28 #define SPGIST_COMPRESS_PROC 6
29 #define SPGIST_OPTIONS_PROC 7
30 #define SPGISTNRequiredProc 5
31 #define SPGISTNProc 7
32 
33 /*
34  * Argument structs for spg_config method
35  */
36 typedef struct spgConfigIn
37 {
38  Oid attType; /* Data type to be indexed */
39 } spgConfigIn;
40 
41 typedef struct spgConfigOut
42 {
43  Oid prefixType; /* Data type of inner-tuple prefixes */
44  Oid labelType; /* Data type of inner-tuple node labels */
45  Oid leafType; /* Data type of leaf-tuple values */
46  bool canReturnData; /* Opclass can reconstruct original data */
47  bool longValuesOK; /* Opclass can cope with values > 1 page */
48 } spgConfigOut;
49 
50 /*
51  * Argument structs for spg_choose method
52  */
53 typedef struct spgChooseIn
54 {
55  Datum datum; /* original datum to be indexed */
56  Datum leafDatum; /* current datum to be stored at leaf */
57  int level; /* current level (counting from zero) */
58 
59  /* Data from current inner tuple */
60  bool allTheSame; /* tuple is marked all-the-same? */
61  bool hasPrefix; /* tuple has a prefix? */
62  Datum prefixDatum; /* if so, the prefix value */
63  int nNodes; /* number of nodes in the inner tuple */
64  Datum *nodeLabels; /* node label values (NULL if none) */
65 } spgChooseIn;
66 
67 typedef enum spgChooseResultType
68 {
69  spgMatchNode = 1, /* descend into existing node */
70  spgAddNode, /* add a node to the inner tuple */
71  spgSplitTuple /* split inner tuple (change its prefix) */
73 
74 typedef struct spgChooseOut
75 {
76  spgChooseResultType resultType; /* action code, see above */
77  union
78  {
79  struct /* results for spgMatchNode */
80  {
81  int nodeN; /* descend to this node (index from 0) */
82  int levelAdd; /* increment level by this much */
83  Datum restDatum; /* new leaf datum */
84  } matchNode;
85  struct /* results for spgAddNode */
86  {
87  Datum nodeLabel; /* new node's label */
88  int nodeN; /* where to insert it (index from 0) */
89  } addNode;
90  struct /* results for spgSplitTuple */
91  {
92  /* Info to form new upper-level inner tuple with one child tuple */
93  bool prefixHasPrefix; /* tuple should have a prefix? */
94  Datum prefixPrefixDatum; /* if so, its value */
95  int prefixNNodes; /* number of nodes */
96  Datum *prefixNodeLabels; /* their labels (or NULL for no
97  * labels) */
98  int childNodeN; /* which node gets child tuple */
99 
100  /* Info to form new lower-level inner tuple with all old nodes */
101  bool postfixHasPrefix; /* tuple should have a prefix? */
102  Datum postfixPrefixDatum; /* if so, its value */
103  } splitTuple;
104  } result;
105 } spgChooseOut;
106 
107 /*
108  * Argument structs for spg_picksplit method
109  */
110 typedef struct spgPickSplitIn
111 {
112  int nTuples; /* number of leaf tuples */
113  Datum *datums; /* their datums (array of length nTuples) */
114  int level; /* current level (counting from zero) */
116 
117 typedef struct spgPickSplitOut
118 {
119  bool hasPrefix; /* new inner tuple should have a prefix? */
120  Datum prefixDatum; /* if so, its value */
121 
122  int nNodes; /* number of nodes for new inner tuple */
123  Datum *nodeLabels; /* their labels (or NULL for no labels) */
124 
125  int *mapTuplesToNodes; /* node index for each leaf tuple */
126  Datum *leafTupleDatums; /* datum to store in each new leaf tuple */
128 
129 /*
130  * Argument structs for spg_inner_consistent method
131  */
132 typedef struct spgInnerConsistentIn
133 {
134  ScanKey scankeys; /* array of operators and comparison values */
135  ScanKey orderbys; /* array of ordering operators and comparison
136  * values */
137  int nkeys; /* length of scankeys array */
138  int norderbys; /* length of orderbys array */
139 
140  Datum reconstructedValue; /* value reconstructed at parent */
141  void *traversalValue; /* opclass-specific traverse value */
142  MemoryContext traversalMemoryContext; /* put new traverse values here */
143  int level; /* current level (counting from zero) */
144  bool returnData; /* original data must be returned? */
145 
146  /* Data from current inner tuple */
147  bool allTheSame; /* tuple is marked all-the-same? */
148  bool hasPrefix; /* tuple has a prefix? */
149  Datum prefixDatum; /* if so, the prefix value */
150  int nNodes; /* number of nodes in the inner tuple */
151  Datum *nodeLabels; /* node label values (NULL if none) */
153 
154 typedef struct spgInnerConsistentOut
155 {
156  int nNodes; /* number of child nodes to be visited */
157  int *nodeNumbers; /* their indexes in the node array */
158  int *levelAdds; /* increment level by this much for each */
159  Datum *reconstructedValues; /* associated reconstructed values */
160  void **traversalValues; /* opclass-specific traverse values */
161  double **distances; /* associated distances */
163 
164 /*
165  * Argument structs for spg_leaf_consistent method
166  */
167 typedef struct spgLeafConsistentIn
168 {
169  ScanKey scankeys; /* array of operators and comparison values */
170  ScanKey orderbys; /* array of ordering operators and comparison
171  * values */
172  int nkeys; /* length of scankeys array */
173  int norderbys; /* length of orderbys array */
174 
175  Datum reconstructedValue; /* value reconstructed at parent */
176  void *traversalValue; /* opclass-specific traverse value */
177  int level; /* current level (counting from zero) */
178  bool returnData; /* original data must be returned? */
179 
180  Datum leafDatum; /* datum in leaf tuple */
182 
183 typedef struct spgLeafConsistentOut
184 {
185  Datum leafValue; /* reconstructed original data, if any */
186  bool recheck; /* set true if operator must be rechecked */
187  bool recheckDistances; /* set true if distances must be rechecked */
188  double *distances; /* associated distances */
190 
191 
192 /* spgutils.c */
193 extern bytea *spgoptions(Datum reloptions, bool validate);
194 
195 /* spginsert.c */
197  struct IndexInfo *indexInfo);
198 extern void spgbuildempty(Relation index);
199 extern bool spginsert(Relation index, Datum *values, bool *isnull,
200  ItemPointer ht_ctid, Relation heapRel,
201  IndexUniqueCheck checkUnique,
202  struct IndexInfo *indexInfo);
203 
204 /* spgscan.c */
205 extern IndexScanDesc spgbeginscan(Relation rel, int keysz, int orderbysz);
206 extern void spgendscan(IndexScanDesc scan);
207 extern void spgrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
208  ScanKey orderbys, int norderbys);
209 extern int64 spggetbitmap(IndexScanDesc scan, TIDBitmap *tbm);
210 extern bool spggettuple(IndexScanDesc scan, ScanDirection dir);
211 extern bool spgcanreturn(Relation index, int attno);
212 
213 /* spgvacuum.c */
215  IndexBulkDeleteResult *stats,
217  void *callback_state);
219  IndexBulkDeleteResult *stats);
220 
221 /* spgvalidate.c */
222 extern bool spgvalidate(Oid opclassoid);
223 
224 #endif /* SPGIST_H */
Datum reconstructedValue
Definition: spgist.h:175
struct spgInnerConsistentOut spgInnerConsistentOut
Datum prefixPrefixDatum
Definition: spgist.h:94
Datum datum
Definition: spgist.h:55
bool hasPrefix
Definition: spgist.h:61
int level
Definition: spgist.h:57
bool canReturnData
Definition: spgist.h:46
bool spginsert(Relation index, Datum *values, bool *isnull, ItemPointer ht_ctid, Relation heapRel, IndexUniqueCheck checkUnique, struct IndexInfo *indexInfo)
Definition: spginsert.c:207
Datum * leafTupleDatums
Definition: spgist.h:126
Datum * datums
Definition: spgist.h:113
struct spgChooseOut spgChooseOut
ScanKey orderbys
Definition: spgist.h:135
void * traversalValue
Definition: spgist.h:141
struct spgPickSplitOut spgPickSplitOut
Datum prefixDatum
Definition: spgist.h:62
Datum * prefixNodeLabels
Definition: spgist.h:96
IndexBulkDeleteResult * spgbulkdelete(IndexVacuumInfo *info, IndexBulkDeleteResult *stats, IndexBulkDeleteCallback callback, void *callback_state)
Definition: spgvacuum.c:901
Oid attType
Definition: spgist.h:38
unsigned int Oid
Definition: postgres_ext.h:31
bool spgcanreturn(Relation index, int attno)
Definition: spgscan.c:1018
void spgendscan(IndexScanDesc scan)
Definition: spgscan.c:411
Datum reconstructedValue
Definition: spgist.h:140
Definition: type.h:89
IndexScanDesc spgbeginscan(Relation rel, int keysz, int orderbysz)
Definition: spgscan.c:295
IndexUniqueCheck
Definition: genam.h:112
static SpGistInnerTuple addNode(SpGistState *state, SpGistInnerTuple tuple, Datum label, int offset)
Definition: spgdoinsert.c:78
int nodeN
Definition: spgist.h:81
MemoryContext traversalMemoryContext
Definition: spgist.h:142
ScanKey orderbys
Definition: spgist.h:170
Datum * nodeLabels
Definition: spgist.h:123
int childNodeN
Definition: spgist.h:98
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:48
ScanKey scankeys
Definition: spgist.h:169
struct spgConfigIn spgConfigIn
double * distances
Definition: spgist.h:188
ScanDirection
Definition: sdir.h:22
struct spgLeafConsistentIn spgLeafConsistentIn
void ** traversalValues
Definition: spgist.h:160
int levelAdd
Definition: spgist.h:82
int nNodes
Definition: spgist.h:63
bool postfixHasPrefix
Definition: spgist.h:101
struct spgConfigOut spgConfigOut
Datum restDatum
Definition: spgist.h:83
bytea * spgoptions(Datum reloptions, bool validate)
Definition: spgutils.c:591
int64 spggetbitmap(IndexScanDesc scan, TIDBitmap *tbm)
Definition: spgscan.c:888
bool longValuesOK
Definition: spgist.h:47
uintptr_t Datum
Definition: postgres.h:367
spgChooseResultType
Definition: spgist.h:67
double ** distances
Definition: spgist.h:161
int prefixNNodes
Definition: spgist.h:95
struct spgLeafConsistentOut spgLeafConsistentOut
Oid prefixType
Definition: spgist.h:43
Datum * nodeLabels
Definition: spgist.h:151
spgChooseResultType resultType
Definition: spgist.h:76
Datum postfixPrefixDatum
Definition: spgist.h:102
bool spggettuple(IndexScanDesc scan, ScanDirection dir)
Definition: spgscan.c:960
struct spgChooseIn spgChooseIn
Datum leafDatum
Definition: spgist.h:56
bool hasPrefix
Definition: spgist.h:119
void spgrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys, ScanKey orderbys, int norderbys)
Definition: spgscan.c:365
Datum nodeLabel
Definition: spgist.h:87
Datum * reconstructedValues
Definition: spgist.h:159
ScanKey scankeys
Definition: spgist.h:134
static Datum values[MAXATTR]
Definition: bootstrap.c:167
Datum * nodeLabels
Definition: spgist.h:64
struct spgInnerConsistentIn spgInnerConsistentIn
Oid labelType
Definition: spgist.h:44
int * mapTuplesToNodes
Definition: spgist.h:125
Oid leafType
Definition: spgist.h:45
bool prefixHasPrefix
Definition: spgist.h:93
bool allTheSame
Definition: spgist.h:60
void * traversalValue
Definition: spgist.h:176
Datum prefixDatum
Definition: spgist.h:120
Definition: c.h:555
IndexBulkDeleteResult * spgvacuumcleanup(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
Definition: spgvacuum.c:932
struct spgPickSplitIn spgPickSplitIn
bool spgvalidate(Oid opclassoid)
Definition: spgvalidate.c:39
void spgbuildempty(Relation index)
Definition: spginsert.c:156
IndexBuildResult * spgbuild(Relation heap, Relation index, struct IndexInfo *indexInfo)
Definition: spginsert.c:75
bool(* IndexBulkDeleteCallback)(ItemPointer itemptr, void *state)
Definition: genam.h:84