1 /*-------------------------------------------------------------------------
4 * POSTGRES scan key definitions.
7 * Portions Copyright (c) 1996-2019, 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"
18 #include "access/stratnum.h"
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.)
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.
34 * If the operator is collation-sensitive, sk_collation must be set
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.
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).
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.
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.
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.
64 typedef struct ScanKeyData
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 */
75 typedef ScanKeyData *ScanKey;
78 * About row comparisons:
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
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.
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.
109 * ScanKeyData sk_flags
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.
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 */
127 * prototypes for functions in access/common/scankey.c
129 extern void ScanKeyInit(ScanKey entry,
130 AttrNumber attributeNumber,
131 StrategyNumber strategy,
132 RegProcedure procedure,
134 extern void ScanKeyEntryInitialize(ScanKey entry,
136 AttrNumber attributeNumber,
137 StrategyNumber strategy,
140 RegProcedure procedure,
142 extern void ScanKeyEntryInitializeWithInfo(ScanKey entry,
144 AttrNumber attributeNumber,
145 StrategyNumber strategy,