src/include/access/spgist.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * spgist.h
   4  *        Public header file for SP-GiST access method.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2024, 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) */
  72 } spgChooseResultType;
  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) */
 115 } spgPickSplitIn;
 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 */
 127 } spgPickSplitOut;
 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) */
 152 } spgInnerConsistentIn;
 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 */
 162 } spgInnerConsistentOut;
 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 */
 181 } spgLeafConsistentIn;
 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 */
 189 } spgLeafConsistentOut;
 190
 191
 192 /* spgutils.c */
 193 extern bytea *spgoptions(Datum reloptions, bool validate);
 194
 195 /* spginsert.c */
 196 extern IndexBuildResult *spgbuild(Relation heap, Relation index,
 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                                           bool indexUnchanged,
 203                                           struct IndexInfo *indexInfo);
 204
 205 /* spgscan.c */
 206 extern IndexScanDesc spgbeginscan(Relation rel, int keysz, int orderbysz);
 207 extern void spgendscan(IndexScanDesc scan);
 208 extern void spgrescan(IndexScanDesc scan, ScanKey scankey, int nscankeys,
 209                                           ScanKey orderbys, int norderbys);
 210 extern int64 spggetbitmap(IndexScanDesc scan, TIDBitmap *tbm);
 211 extern bool spggettuple(IndexScanDesc scan, ScanDirection dir);
 212 extern bool spgcanreturn(Relation index, int attno);
 213
 214 /* spgvacuum.c */
 215 extern IndexBulkDeleteResult *spgbulkdelete(IndexVacuumInfo *info,
 216                                                                                         IndexBulkDeleteResult *stats,
 217                                                                                         IndexBulkDeleteCallback callback,
 218                                                                                         void *callback_state);
 219 extern IndexBulkDeleteResult *spgvacuumcleanup(IndexVacuumInfo *info,
 220                                                                                            IndexBulkDeleteResult *stats);
 221
 222 /* spgvalidate.c */
 223 extern bool spgvalidate(Oid opclassoid);
 224 extern void spgadjustmembers(Oid opfamilyoid,
 225                                                          Oid opclassoid,
 226                                                          List *operators,
 227                                                          List *functions);
 228
 229 #endif                                                  /* SPGIST_H */