1 /*-------------------------------------------------------------------------
4 * POSTGRES scan key definitions.
7 * Portions Copyright (c) 1996-2014, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/access/skey.h
12 *-------------------------------------------------------------------------
17 #include "access/attnum.h"
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.
26 typedef uint16 StrategyNumber;
28 #define InvalidStrategy ((StrategyNumber) 0)
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.
34 #define BTLessStrategyNumber 1
35 #define BTLessEqualStrategyNumber 2
36 #define BTEqualStrategyNumber 3
37 #define BTGreaterEqualStrategyNumber 4
38 #define BTGreaterStrategyNumber 5
40 #define BTMaxStrategyNumber 5
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.)
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.
55 * If the operator is collation-sensitive, sk_collation must be set
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.
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).
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.
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.
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.
85 typedef struct ScanKeyData
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 */
96 typedef ScanKeyData *ScanKey;
99 * About row comparisons:
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
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.
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.
130 * ScanKeyData sk_flags
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.
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
145 #define SK_ORDER_BY 0x0100 /* scankey is for ORDER BY op */
149 * prototypes for functions in access/common/scankey.c
151 extern void ScanKeyInit(ScanKey entry,
152 AttrNumber attributeNumber,
153 StrategyNumber strategy,
154 RegProcedure procedure,
156 extern void ScanKeyEntryInitialize(ScanKey entry,
158 AttrNumber attributeNumber,
159 StrategyNumber strategy,
162 RegProcedure procedure,
164 extern void ScanKeyEntryInitializeWithInfo(ScanKey entry,
166 AttrNumber attributeNumber,
167 StrategyNumber strategy,