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