granicus.if.org Git - postgresql/blob - src/include/access/skey.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * skey.h
   4  *        POSTGRES scan key definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2013, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/access/skey.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef SKEY_H
  15 #define SKEY_H
  16
  17 #include "access/attnum.h"
  18 #include "fmgr.h"
  19
  20
  21 /*
  22  * Strategy numbers identify the semantics that particular operators have
  23  * with respect to particular operator classes.  In some cases a strategy
  24  * subtype (an OID) is used as further information.
  25  */
  26 typedef uint16 StrategyNumber;
  27
  28 #define InvalidStrategy ((StrategyNumber) 0)
  29
  30 /*
  31  * We define the strategy numbers for B-tree indexes here, to avoid having
  32  * to import access/nbtree.h into a lot of places that shouldn't need it.
  33  */
  34 #define BTLessStrategyNumber                    1
  35 #define BTLessEqualStrategyNumber               2
  36 #define BTEqualStrategyNumber                   3
  37 #define BTGreaterEqualStrategyNumber    4
  38 #define BTGreaterStrategyNumber                 5
  39
  40 #define BTMaxStrategyNumber                             5
  41
  42
  43 /*
  44  * A ScanKey represents the application of a comparison operator between
  45  * a table or index column and a constant.      When it's part of an array of
  46  * ScanKeys, the comparison conditions are implicitly ANDed.  The index
  47  * column is the left argument of the operator, if it's a binary operator.
  48  * (The data structure can support unary indexable operators too; in that
  49  * case sk_argument would go unused.  This is not currently implemented.)
  50  *
  51  * For an index scan, sk_strategy and sk_subtype must be set correctly for
  52  * the operator.  When using a ScanKey in a heap scan, these fields are not
  53  * used and may be set to InvalidStrategy/InvalidOid.
  54  *
  55  * If the operator is collation-sensitive, sk_collation must be set
  56  * correctly as well.
  57  *
  58  * A ScanKey can also represent a ScalarArrayOpExpr, that is a condition
  59  * "column op ANY(ARRAY[...])".  This is signaled by the SK_SEARCHARRAY
  60  * flag bit.  The sk_argument is not a value of the operator's right-hand
  61  * argument type, but rather an array of such values, and the per-element
  62  * comparisons are to be ORed together.
  63  *
  64  * A ScanKey can also represent a condition "column IS NULL" or "column
  65  * IS NOT NULL"; these cases are signaled by the SK_SEARCHNULL and
  66  * SK_SEARCHNOTNULL flag bits respectively.  The argument is always NULL,
  67  * and the sk_strategy, sk_subtype, sk_collation, and sk_func fields are
  68  * not used (unless set by the index AM).
  69  *
  70  * SK_SEARCHARRAY, SK_SEARCHNULL and SK_SEARCHNOTNULL are supported only
  71  * for index scans, not heap scans; and not all index AMs support them,
  72  * only those that set amsearcharray or amsearchnulls respectively.
  73  *
  74  * A ScanKey can also represent an ordering operator invocation, that is
  75  * an ordering requirement "ORDER BY indexedcol op constant".  This looks
  76  * the same as a comparison operator, except that the operator doesn't
  77  * (usually) yield boolean.  We mark such ScanKeys with SK_ORDER_BY.
  78  * SK_SEARCHARRAY, SK_SEARCHNULL, SK_SEARCHNOTNULL cannot be used here.
  79  *
  80  * Note: in some places, ScanKeys are used as a convenient representation
  81  * for the invocation of an access method support procedure.  In this case
  82  * sk_strategy/sk_subtype are not meaningful (but sk_collation can be); and
  83  * sk_func may refer to a function that returns something other than boolean.
  84  */
  85 typedef struct ScanKeyData
  86 {
  87         int                     sk_flags;               /* flags, see below */
  88         AttrNumber      sk_attno;               /* table or index column number */
  89         StrategyNumber sk_strategy; /* operator strategy number */
  90         Oid                     sk_subtype;             /* strategy subtype */
  91         Oid                     sk_collation;   /* collation to use, if needed */
  92         FmgrInfo        sk_func;                /* lookup info for function to call */
  93         Datum           sk_argument;    /* data to compare */
  94 } ScanKeyData;
  95
  96 typedef ScanKeyData *ScanKey;
  97
  98 /*
  99  * About row comparisons:
 100  *
 101  * The ScanKey data structure also supports row comparisons, that is ordered
 102  * tuple comparisons like (x, y) > (c1, c2), having the SQL-spec semantics
 103  * "x > c1 OR (x = c1 AND y > c2)".  Note that this is currently only
 104  * implemented for btree index searches, not for heapscans or any other index
 105  * type.  A row comparison is represented by a "header" ScanKey entry plus
 106  * a separate array of ScanKeys, one for each column of the row comparison.
 107  * The header entry has these properties:
 108  *              sk_flags = SK_ROW_HEADER
 109  *              sk_attno = index column number for leading column of row comparison
 110  *              sk_strategy = btree strategy code for semantics of row comparison
 111  *                              (ie, < <= > or >=)
 112  *              sk_subtype, sk_collation, sk_func: not used
 113  *              sk_argument: pointer to subsidiary ScanKey array
 114  * If the header is part of a ScanKey array that's sorted by attno, it
 115  * must be sorted according to the leading column number.
 116  *
 117  * The subsidiary ScanKey array appears in logical column order of the row
 118  * comparison, which may be different from index column order.  The array
 119  * elements are like a normal ScanKey array except that:
 120  *              sk_flags must include SK_ROW_MEMBER, plus SK_ROW_END in the last
 121  *                              element (needed since row header does not include a count)
 122  *              sk_func points to the btree comparison support function for the
 123  *                              opclass, NOT the operator's implementation function.
 124  * sk_strategy must be the same in all elements of the subsidiary array,
 125  * that is, the same as in the header entry.
 126  * SK_SEARCHARRAY, SK_SEARCHNULL, SK_SEARCHNOTNULL cannot be used here.
 127  */
 128
 129 /*
 130  * ScanKeyData sk_flags
 131  *
 132  * sk_flags bits 0-15 are reserved for system-wide use (symbols for those
 133  * bits should be defined here).  Bits 16-31 are reserved for use within
 134  * individual index access methods.
 135  */
 136 #define SK_ISNULL                       0x0001          /* sk_argument is NULL */
 137 #define SK_UNARY                        0x0002          /* unary operator (not supported!) */
 138 #define SK_ROW_HEADER           0x0004          /* row comparison header (see above) */
 139 #define SK_ROW_MEMBER           0x0008          /* row comparison member (see above) */
 140 #define SK_ROW_END                      0x0010          /* last row comparison member */
 141 #define SK_SEARCHARRAY          0x0020          /* scankey represents ScalarArrayOp */
 142 #define SK_SEARCHNULL           0x0040          /* scankey represents "col IS NULL" */
 143 #define SK_SEARCHNOTNULL        0x0080          /* scankey represents "col IS NOT
 144                                                                                  * NULL" */
 145 #define SK_ORDER_BY                     0x0100          /* scankey is for ORDER BY op */
 146
 147
 148 /*
 149  * prototypes for functions in access/common/scankey.c
 150  */
 151 extern void ScanKeyInit(ScanKey entry,
 152                         AttrNumber attributeNumber,
 153                         StrategyNumber strategy,
 154                         RegProcedure procedure,
 155                         Datum argument);
 156 extern void ScanKeyEntryInitialize(ScanKey entry,
 157                                            int flags,
 158                                            AttrNumber attributeNumber,
 159                                            StrategyNumber strategy,
 160                                            Oid subtype,
 161                                            Oid collation,
 162                                            RegProcedure procedure,
 163                                            Datum argument);
 164 extern void ScanKeyEntryInitializeWithInfo(ScanKey entry,
 165                                                            int flags,
 166                                                            AttrNumber attributeNumber,
 167                                                            StrategyNumber strategy,
 168                                                            Oid subtype,
 169                                                            Oid collation,
 170                                                            FmgrInfo *finfo,
 171                                                            Datum argument);
 172
 173 #endif   /* SKEY_H */