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 "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 */
40typedef struct spgConfigIn
41{
42 Oid attType; /* Data type to be indexed */
43} spgConfigIn;
44
45typedef 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 */
57typedef 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
71typedef 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) */
76} spgChooseResultType;
77
78typedef 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 */
114typedef 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) */
119} spgPickSplitIn;
120
121typedef 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 */
131} spgPickSplitOut;
132
133/*
134 * Argument structs for spg_inner_consistent method
135 */
136typedef struct spgInnerConsistentIn
137{
138 ScanKey scankeys; /* array of operators and comparison values */
139 ScanKey orderbys; /* array of ordering operators and comparison
140 * values */
141 int nkeys; /* length of scankeys array */
142 int norderbys; /* length of orderbys array */
143
144 Datum reconstructedValue; /* value reconstructed at parent */
145 void *traversalValue; /* opclass-specific traverse value */
146 MemoryContext traversalMemoryContext; /* put new traverse values here */
147 int level; /* current level (counting from zero) */
148 bool returnData; /* original data must be returned? */
149
150 /* Data from current inner tuple */
151 bool allTheSame; /* tuple is marked all-the-same? */
152 bool hasPrefix; /* tuple has a prefix? */
153 Datum prefixDatum; /* if so, the prefix value */
154 int nNodes; /* number of nodes in the inner tuple */
155 Datum *nodeLabels; /* node label values (NULL if none) */
156} spgInnerConsistentIn;
157
158typedef struct spgInnerConsistentOut
159{
160 int nNodes; /* number of child nodes to be visited */
161 int *nodeNumbers; /* their indexes in the node array */
162 int *levelAdds; /* increment level by this much for each */
163 Datum *reconstructedValues; /* associated reconstructed values */
164 void **traversalValues; /* opclass-specific traverse values */
165 double **distances; /* associated distances */
166} spgInnerConsistentOut;
167
168/*
169 * Argument structs for spg_leaf_consistent method
170 */
171typedef struct spgLeafConsistentIn
172{
173 ScanKey scankeys; /* array of operators and comparison values */
174 ScanKey orderbys; /* array of ordering operators and comparison
175 * values */
176 int nkeys; /* length of scankeys array */
177 int norderbys; /* length of orderbys array */
178
179 Datum reconstructedValue; /* value reconstructed at parent */
180 void *traversalValue; /* opclass-specific traverse value */
181 int level; /* current level (counting from zero) */
182 bool returnData; /* original data must be returned? */
183
184 Datum leafDatum; /* datum in leaf tuple */
185} spgLeafConsistentIn;
186
187typedef struct spgLeafConsistentOut
188{
189 Datum leafValue; /* reconstructed original data, if any */
190 bool recheck; /* set true if operator must be rechecked */
191 bool recheckDistances; /* set true if distances must be rechecked */
192 double *distances; /* associated distances */
193} spgLeafConsistentOut;
194
195
196/* spgutils.c */
197extern bytea *spgoptions(Datum reloptions, bool validate);
198
199/* spginsert.c */
200extern IndexBuildResult *spgbuild(Relation heap, Relation index,
201 struct IndexInfo *indexInfo);
202extern void spgbuildempty(Relation index);
203extern bool spginsert(Relation index, Datum *values, bool *isnull,
204 ItemPointer ht_ctid, Relation heapRel,
205 IndexUniqueCheck checkUnique,
206 struct IndexInfo *indexInfo);
207
208/* spgscan.c */
209extern IndexScanDesc spgbeginscan(Relation rel, int keysz, int orderbysz);
210extern void spgendscan(IndexScanDesc scan);
211extern void spgrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
212 ScanKey orderbys, int norderbys);
213extern int64 spggetbitmap(IndexScanDesc scan, TIDBitmap *tbm);
214extern bool spggettuple(IndexScanDesc scan, ScanDirection dir);
215extern bool spgcanreturn(Relation index, int attno);
216
217/* spgvacuum.c */
218extern IndexBulkDeleteResult *spgbulkdelete(IndexVacuumInfo *info,
219 IndexBulkDeleteResult *stats,
220 IndexBulkDeleteCallback callback,
221 void *callback_state);
222extern IndexBulkDeleteResult *spgvacuumcleanup(IndexVacuumInfo *info,
223 IndexBulkDeleteResult *stats);
224
225/* spgvalidate.c */
226extern bool spgvalidate(Oid opclassoid);
227
228#endif /* SPGIST_H */
229