src/include/access/skey.h

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