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