Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * nbtutils.c
4 : * Utility code for Postgres btree implementation.
5 : *
6 : * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
7 : * Portions Copyright (c) 1994, Regents of the University of California
8 : *
9 : *
10 : * IDENTIFICATION
11 : * src/backend/access/nbtree/nbtutils.c
12 : *
13 : *-------------------------------------------------------------------------
14 : */
15 :
16 : #include "postgres.h"
17 :
18 : #include <time.h>
19 :
20 : #include "access/nbtree.h"
21 : #include "access/reloptions.h"
22 : #include "access/relscan.h"
23 : #include "commands/progress.h"
24 : #include "lib/qunique.h"
25 : #include "miscadmin.h"
26 : #include "utils/array.h"
27 : #include "utils/datum.h"
28 : #include "utils/lsyscache.h"
29 : #include "utils/memutils.h"
30 : #include "utils/rel.h"
31 :
32 : #define LOOK_AHEAD_REQUIRED_RECHECKS 3
33 : #define LOOK_AHEAD_DEFAULT_DISTANCE 5
34 :
35 : typedef struct BTSortArrayContext
36 : {
37 : FmgrInfo *sortproc;
38 : Oid collation;
39 : bool reverse;
40 : } BTSortArrayContext;
41 :
42 : typedef struct BTScanKeyPreproc
43 : {
44 : ScanKey inkey;
45 : int inkeyi;
46 : int arrayidx;
47 : } BTScanKeyPreproc;
48 :
49 : static void _bt_setup_array_cmp(IndexScanDesc scan, ScanKey skey, Oid elemtype,
50 : FmgrInfo *orderproc, FmgrInfo **sortprocp);
51 : static Datum _bt_find_extreme_element(IndexScanDesc scan, ScanKey skey,
52 : Oid elemtype, StrategyNumber strat,
53 : Datum *elems, int nelems);
54 : static int _bt_sort_array_elements(ScanKey skey, FmgrInfo *sortproc,
55 : bool reverse, Datum *elems, int nelems);
56 : static bool _bt_merge_arrays(IndexScanDesc scan, ScanKey skey,
57 : FmgrInfo *sortproc, bool reverse,
58 : Oid origelemtype, Oid nextelemtype,
59 : Datum *elems_orig, int *nelems_orig,
60 : Datum *elems_next, int nelems_next);
61 : static bool _bt_compare_array_scankey_args(IndexScanDesc scan,
62 : ScanKey arraysk, ScanKey skey,
63 : FmgrInfo *orderproc, BTArrayKeyInfo *array,
64 : bool *qual_ok);
65 : static ScanKey _bt_preprocess_array_keys(IndexScanDesc scan, int *new_numberOfKeys);
66 : static void _bt_preprocess_array_keys_final(IndexScanDesc scan, int *keyDataMap);
67 : static int _bt_compare_array_elements(const void *a, const void *b, void *arg);
68 : static inline int32 _bt_compare_array_skey(FmgrInfo *orderproc,
69 : Datum tupdatum, bool tupnull,
70 : Datum arrdatum, ScanKey cur);
71 : static int _bt_binsrch_array_skey(FmgrInfo *orderproc,
72 : bool cur_elem_trig, ScanDirection dir,
73 : Datum tupdatum, bool tupnull,
74 : BTArrayKeyInfo *array, ScanKey cur,
75 : int32 *set_elem_result);
76 : static bool _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir);
77 : static void _bt_rewind_nonrequired_arrays(IndexScanDesc scan, ScanDirection dir);
78 : static bool _bt_tuple_before_array_skeys(IndexScanDesc scan, ScanDirection dir,
79 : IndexTuple tuple, TupleDesc tupdesc, int tupnatts,
80 : bool readpagetup, int sktrig, bool *scanBehind);
81 : static bool _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
82 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
83 : int sktrig, bool sktrig_required);
84 : #ifdef USE_ASSERT_CHECKING
85 : static bool _bt_verify_arrays_bt_first(IndexScanDesc scan, ScanDirection dir);
86 : static bool _bt_verify_keys_with_arraykeys(IndexScanDesc scan);
87 : #endif
88 : static bool _bt_compare_scankey_args(IndexScanDesc scan, ScanKey op,
89 : ScanKey leftarg, ScanKey rightarg,
90 : BTArrayKeyInfo *array, FmgrInfo *orderproc,
91 : bool *result);
92 : static bool _bt_fix_scankey_strategy(ScanKey skey, int16 *indoption);
93 : static void _bt_mark_scankey_required(ScanKey skey);
94 : static bool _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
95 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
96 : bool advancenonrequired, bool prechecked, bool firstmatch,
97 : bool *continuescan, int *ikey);
98 : static bool _bt_check_rowcompare(ScanKey skey,
99 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
100 : ScanDirection dir, bool *continuescan);
101 : static void _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
102 : int tupnatts, TupleDesc tupdesc);
103 : static int _bt_keep_natts(Relation rel, IndexTuple lastleft,
104 : IndexTuple firstright, BTScanInsert itup_key);
105 :
106 :
107 : /*
108 : * _bt_mkscankey
109 : * Build an insertion scan key that contains comparison data from itup
110 : * as well as comparator routines appropriate to the key datatypes.
111 : *
112 : * The result is intended for use with _bt_compare() and _bt_truncate().
113 : * Callers that don't need to fill out the insertion scankey arguments
114 : * (e.g. they use an ad-hoc comparison routine, or only need a scankey
115 : * for _bt_truncate()) can pass a NULL index tuple. The scankey will
116 : * be initialized as if an "all truncated" pivot tuple was passed
117 : * instead.
118 : *
119 : * Note that we may occasionally have to share lock the metapage to
120 : * determine whether or not the keys in the index are expected to be
121 : * unique (i.e. if this is a "heapkeyspace" index). We assume a
122 : * heapkeyspace index when caller passes a NULL tuple, allowing index
123 : * build callers to avoid accessing the non-existent metapage. We
124 : * also assume that the index is _not_ allequalimage when a NULL tuple
125 : * is passed; CREATE INDEX callers call _bt_allequalimage() to set the
126 : * field themselves.
127 : */
128 : BTScanInsert
129 11366308 : _bt_mkscankey(Relation rel, IndexTuple itup)
130 : {
131 : BTScanInsert key;
132 : ScanKey skey;
133 : TupleDesc itupdesc;
134 : int indnkeyatts;
135 : int16 *indoption;
136 : int tupnatts;
137 : int i;
138 :
139 11366308 : itupdesc = RelationGetDescr(rel);
140 11366308 : indnkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
141 11366308 : indoption = rel->rd_indoption;
142 11366308 : tupnatts = itup ? BTreeTupleGetNAtts(itup, rel) : 0;
143 :
144 : Assert(tupnatts <= IndexRelationGetNumberOfAttributes(rel));
145 :
146 : /*
147 : * We'll execute search using scan key constructed on key columns.
148 : * Truncated attributes and non-key attributes are omitted from the final
149 : * scan key.
150 : */
151 11366308 : key = palloc(offsetof(BTScanInsertData, scankeys) +
152 11366308 : sizeof(ScanKeyData) * indnkeyatts);
153 11366308 : if (itup)
154 11231608 : _bt_metaversion(rel, &key->heapkeyspace, &key->allequalimage);
155 : else
156 : {
157 : /* Utility statement callers can set these fields themselves */
158 134700 : key->heapkeyspace = true;
159 134700 : key->allequalimage = false;
160 : }
161 11366308 : key->anynullkeys = false; /* initial assumption */
162 11366308 : key->nextkey = false; /* usual case, required by btinsert */
163 11366308 : key->backward = false; /* usual case, required by btinsert */
164 11366308 : key->keysz = Min(indnkeyatts, tupnatts);
165 11366308 : key->scantid = key->heapkeyspace && itup ?
166 22732616 : BTreeTupleGetHeapTID(itup) : NULL;
167 11366308 : skey = key->scankeys;
168 30531136 : for (i = 0; i < indnkeyatts; i++)
169 : {
170 : FmgrInfo *procinfo;
171 : Datum arg;
172 : bool null;
173 : int flags;
174 :
175 : /*
176 : * We can use the cached (default) support procs since no cross-type
177 : * comparison can be needed.
178 : */
179 19164828 : procinfo = index_getprocinfo(rel, i + 1, BTORDER_PROC);
180 :
181 : /*
182 : * Key arguments built from truncated attributes (or when caller
183 : * provides no tuple) are defensively represented as NULL values. They
184 : * should never be used.
185 : */
186 19164828 : if (i < tupnatts)
187 18922522 : arg = index_getattr(itup, i + 1, itupdesc, &null);
188 : else
189 : {
190 242306 : arg = (Datum) 0;
191 242306 : null = true;
192 : }
193 19164828 : flags = (null ? SK_ISNULL : 0) | (indoption[i] << SK_BT_INDOPTION_SHIFT);
194 19164828 : ScanKeyEntryInitializeWithInfo(&skey[i],
195 : flags,
196 19164828 : (AttrNumber) (i + 1),
197 : InvalidStrategy,
198 : InvalidOid,
199 19164828 : rel->rd_indcollation[i],
200 : procinfo,
201 : arg);
202 : /* Record if any key attribute is NULL (or truncated) */
203 19164828 : if (null)
204 262876 : key->anynullkeys = true;
205 : }
206 :
207 : /*
208 : * In NULLS NOT DISTINCT mode, we pretend that there are no null keys, so
209 : * that full uniqueness check is done.
210 : */
211 11366308 : if (rel->rd_index->indnullsnotdistinct)
212 186 : key->anynullkeys = false;
213 :
214 11366308 : return key;
215 : }
216 :
217 : /*
218 : * free a retracement stack made by _bt_search.
219 : */
220 : void
221 19258850 : _bt_freestack(BTStack stack)
222 : {
223 : BTStack ostack;
224 :
225 35468604 : while (stack != NULL)
226 : {
227 16209754 : ostack = stack;
228 16209754 : stack = stack->bts_parent;
229 16209754 : pfree(ostack);
230 : }
231 19258850 : }
232 :
233 :
234 : /*
235 : * _bt_preprocess_array_keys() -- Preprocess SK_SEARCHARRAY scan keys
236 : *
237 : * If there are any SK_SEARCHARRAY scan keys, deconstruct the array(s) and
238 : * set up BTArrayKeyInfo info for each one that is an equality-type key.
239 : * Returns modified scan keys as input for further, standard preprocessing.
240 : *
241 : * Currently we perform two kinds of preprocessing to deal with redundancies.
242 : * For inequality array keys, it's sufficient to find the extreme element
243 : * value and replace the whole array with that scalar value. This eliminates
244 : * all but one array element as redundant. Similarly, we are capable of
245 : * "merging together" multiple equality array keys (from two or more input
246 : * scan keys) into a single output scan key containing only the intersecting
247 : * array elements. This can eliminate many redundant array elements, as well
248 : * as eliminating whole array scan keys as redundant. It can also allow us to
249 : * detect contradictory quals.
250 : *
251 : * Caller must pass *new_numberOfKeys to give us a way to change the number of
252 : * scan keys that caller treats as input to standard preprocessing steps. The
253 : * returned array is smaller than scan->keyData[] when we could eliminate a
254 : * redundant array scan key (redundant with another array scan key). It is
255 : * convenient for _bt_preprocess_keys caller to have to deal with no more than
256 : * one equality strategy array scan key per index attribute. We'll always be
257 : * able to set things up that way when complete opfamilies are used.
258 : *
259 : * We set the scan key references from the scan's BTArrayKeyInfo info array to
260 : * offsets into the temp modified input array returned to caller. Scans that
261 : * have array keys should call _bt_preprocess_array_keys_final when standard
262 : * preprocessing steps are complete. This will convert the scan key offset
263 : * references into references to the scan's so->keyData[] output scan keys.
264 : *
265 : * Note: the reason we need to return a temp scan key array, rather than just
266 : * scribbling on scan->keyData, is that callers are permitted to call btrescan
267 : * without supplying a new set of scankey data.
268 : */
269 : static ScanKey
270 13012024 : _bt_preprocess_array_keys(IndexScanDesc scan, int *new_numberOfKeys)
271 : {
272 13012024 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
273 13012024 : Relation rel = scan->indexRelation;
274 13012024 : int numberOfKeys = scan->numberOfKeys;
275 13012024 : int16 *indoption = rel->rd_indoption;
276 : int numArrayKeys,
277 13012024 : output_ikey = 0;
278 13012024 : int origarrayatt = InvalidAttrNumber,
279 13012024 : origarraykey = -1;
280 13012024 : Oid origelemtype = InvalidOid;
281 : ScanKey cur;
282 : MemoryContext oldContext;
283 : ScanKey arrayKeyData; /* modified copy of scan->keyData */
284 :
285 : Assert(numberOfKeys);
286 :
287 : /* Quick check to see if there are any array keys */
288 13012024 : numArrayKeys = 0;
289 33770828 : for (int i = 0; i < numberOfKeys; i++)
290 : {
291 20758804 : cur = &scan->keyData[i];
292 20758804 : if (cur->sk_flags & SK_SEARCHARRAY)
293 : {
294 1276 : numArrayKeys++;
295 : Assert(!(cur->sk_flags & (SK_ROW_HEADER | SK_SEARCHNULL | SK_SEARCHNOTNULL)));
296 : /* If any arrays are null as a whole, we can quit right now. */
297 1276 : if (cur->sk_flags & SK_ISNULL)
298 : {
299 0 : so->qual_ok = false;
300 0 : return NULL;
301 : }
302 : }
303 : }
304 :
305 : /* Quit if nothing to do. */
306 13012024 : if (numArrayKeys == 0)
307 13010922 : return NULL;
308 :
309 : /*
310 : * Make a scan-lifespan context to hold array-associated data, or reset it
311 : * if we already have one from a previous rescan cycle.
312 : */
313 1102 : if (so->arrayContext == NULL)
314 1102 : so->arrayContext = AllocSetContextCreate(CurrentMemoryContext,
315 : "BTree array context",
316 : ALLOCSET_SMALL_SIZES);
317 : else
318 0 : MemoryContextReset(so->arrayContext);
319 :
320 1102 : oldContext = MemoryContextSwitchTo(so->arrayContext);
321 :
322 : /* Create output scan keys in the workspace context */
323 1102 : arrayKeyData = (ScanKey) palloc(numberOfKeys * sizeof(ScanKeyData));
324 :
325 : /* Allocate space for per-array data in the workspace context */
326 1102 : so->arrayKeys = (BTArrayKeyInfo *) palloc(numArrayKeys * sizeof(BTArrayKeyInfo));
327 :
328 : /* Allocate space for ORDER procs used to help _bt_checkkeys */
329 1102 : so->orderProcs = (FmgrInfo *) palloc(numberOfKeys * sizeof(FmgrInfo));
330 :
331 : /* Now process each array key */
332 1102 : numArrayKeys = 0;
333 2842 : for (int input_ikey = 0; input_ikey < numberOfKeys; input_ikey++)
334 : {
335 : FmgrInfo sortproc;
336 1746 : FmgrInfo *sortprocp = &sortproc;
337 : Oid elemtype;
338 : bool reverse;
339 : ArrayType *arrayval;
340 : int16 elmlen;
341 : bool elmbyval;
342 : char elmalign;
343 : int num_elems;
344 : Datum *elem_values;
345 : bool *elem_nulls;
346 : int num_nonnulls;
347 : int j;
348 :
349 : /*
350 : * Provisionally copy scan key into arrayKeyData[] array we'll return
351 : * to _bt_preprocess_keys caller
352 : */
353 1746 : cur = &arrayKeyData[output_ikey];
354 1746 : *cur = scan->keyData[input_ikey];
355 :
356 1746 : if (!(cur->sk_flags & SK_SEARCHARRAY))
357 : {
358 470 : output_ikey++; /* keep this non-array scan key */
359 488 : continue;
360 : }
361 :
362 : /*
363 : * Deconstruct the array into elements
364 : */
365 1276 : arrayval = DatumGetArrayTypeP(cur->sk_argument);
366 : /* We could cache this data, but not clear it's worth it */
367 1276 : get_typlenbyvalalign(ARR_ELEMTYPE(arrayval),
368 : &elmlen, &elmbyval, &elmalign);
369 1276 : deconstruct_array(arrayval,
370 : ARR_ELEMTYPE(arrayval),
371 : elmlen, elmbyval, elmalign,
372 : &elem_values, &elem_nulls, &num_elems);
373 :
374 : /*
375 : * Compress out any null elements. We can ignore them since we assume
376 : * all btree operators are strict.
377 : */
378 1276 : num_nonnulls = 0;
379 6192 : for (j = 0; j < num_elems; j++)
380 : {
381 4916 : if (!elem_nulls[j])
382 4916 : elem_values[num_nonnulls++] = elem_values[j];
383 : }
384 :
385 : /* We could pfree(elem_nulls) now, but not worth the cycles */
386 :
387 : /* If there's no non-nulls, the scan qual is unsatisfiable */
388 1276 : if (num_nonnulls == 0)
389 : {
390 0 : so->qual_ok = false;
391 6 : break;
392 : }
393 :
394 : /*
395 : * Determine the nominal datatype of the array elements. We have to
396 : * support the convention that sk_subtype == InvalidOid means the
397 : * opclass input type; this is a hack to simplify life for
398 : * ScanKeyInit().
399 : */
400 1276 : elemtype = cur->sk_subtype;
401 1276 : if (elemtype == InvalidOid)
402 0 : elemtype = rel->rd_opcintype[cur->sk_attno - 1];
403 :
404 : /*
405 : * If the comparison operator is not equality, then the array qual
406 : * degenerates to a simple comparison against the smallest or largest
407 : * non-null array element, as appropriate.
408 : */
409 1276 : switch (cur->sk_strategy)
410 : {
411 6 : case BTLessStrategyNumber:
412 : case BTLessEqualStrategyNumber:
413 6 : cur->sk_argument =
414 6 : _bt_find_extreme_element(scan, cur, elemtype,
415 : BTGreaterStrategyNumber,
416 : elem_values, num_nonnulls);
417 6 : output_ikey++; /* keep this transformed scan key */
418 6 : continue;
419 1264 : case BTEqualStrategyNumber:
420 : /* proceed with rest of loop */
421 1264 : break;
422 6 : case BTGreaterEqualStrategyNumber:
423 : case BTGreaterStrategyNumber:
424 6 : cur->sk_argument =
425 6 : _bt_find_extreme_element(scan, cur, elemtype,
426 : BTLessStrategyNumber,
427 : elem_values, num_nonnulls);
428 6 : output_ikey++; /* keep this transformed scan key */
429 6 : continue;
430 0 : default:
431 0 : elog(ERROR, "unrecognized StrategyNumber: %d",
432 : (int) cur->sk_strategy);
433 : break;
434 : }
435 :
436 : /*
437 : * We'll need a 3-way ORDER proc to perform binary searches for the
438 : * next matching array element. Set that up now.
439 : *
440 : * Array scan keys with cross-type equality operators will require a
441 : * separate same-type ORDER proc for sorting their array. Otherwise,
442 : * sortproc just points to the same proc used during binary searches.
443 : */
444 1264 : _bt_setup_array_cmp(scan, cur, elemtype,
445 1264 : &so->orderProcs[output_ikey], &sortprocp);
446 :
447 : /*
448 : * Sort the non-null elements and eliminate any duplicates. We must
449 : * sort in the same ordering used by the index column, so that the
450 : * arrays can be advanced in lockstep with the scan's progress through
451 : * the index's key space.
452 : */
453 1264 : reverse = (indoption[cur->sk_attno - 1] & INDOPTION_DESC) != 0;
454 1264 : num_elems = _bt_sort_array_elements(cur, sortprocp, reverse,
455 : elem_values, num_nonnulls);
456 :
457 1264 : if (origarrayatt == cur->sk_attno)
458 : {
459 12 : BTArrayKeyInfo *orig = &so->arrayKeys[origarraykey];
460 :
461 : /*
462 : * This array scan key is redundant with a previous equality
463 : * operator array scan key. Merge the two arrays together to
464 : * eliminate contradictory non-intersecting elements (or try to).
465 : *
466 : * We merge this next array back into attribute's original array.
467 : */
468 : Assert(arrayKeyData[orig->scan_key].sk_attno == cur->sk_attno);
469 : Assert(arrayKeyData[orig->scan_key].sk_collation ==
470 : cur->sk_collation);
471 12 : if (_bt_merge_arrays(scan, cur, sortprocp, reverse,
472 : origelemtype, elemtype,
473 : orig->elem_values, &orig->num_elems,
474 : elem_values, num_elems))
475 : {
476 : /* Successfully eliminated this array */
477 12 : pfree(elem_values);
478 :
479 : /*
480 : * If no intersecting elements remain in the original array,
481 : * the scan qual is unsatisfiable
482 : */
483 12 : if (orig->num_elems == 0)
484 : {
485 6 : so->qual_ok = false;
486 6 : break;
487 : }
488 :
489 : /* Throw away this scan key/array */
490 6 : continue;
491 : }
492 :
493 : /*
494 : * Unable to merge this array with previous array due to a lack of
495 : * suitable cross-type opfamily support. Will need to keep both
496 : * scan keys/arrays.
497 : */
498 : }
499 : else
500 : {
501 : /*
502 : * This array is the first for current index attribute.
503 : *
504 : * If it turns out to not be the last array (that is, if the next
505 : * array is redundantly applied to this same index attribute),
506 : * we'll then treat this array as the attribute's "original" array
507 : * when merging.
508 : */
509 1252 : origarrayatt = cur->sk_attno;
510 1252 : origarraykey = numArrayKeys;
511 1252 : origelemtype = elemtype;
512 : }
513 :
514 : /*
515 : * And set up the BTArrayKeyInfo data.
516 : *
517 : * Note: _bt_preprocess_array_keys_final will fix-up each array's
518 : * scan_key field later on, after so->keyData[] has been finalized.
519 : */
520 1252 : so->arrayKeys[numArrayKeys].scan_key = output_ikey;
521 1252 : so->arrayKeys[numArrayKeys].num_elems = num_elems;
522 1252 : so->arrayKeys[numArrayKeys].elem_values = elem_values;
523 1252 : numArrayKeys++;
524 1252 : output_ikey++; /* keep this scan key/array */
525 : }
526 :
527 : /* Set final number of equality-type array keys */
528 1102 : so->numArrayKeys = numArrayKeys;
529 : /* Set number of scan keys remaining in arrayKeyData[] */
530 1102 : *new_numberOfKeys = output_ikey;
531 :
532 1102 : MemoryContextSwitchTo(oldContext);
533 :
534 1102 : return arrayKeyData;
535 : }
536 :
537 : /*
538 : * _bt_preprocess_array_keys_final() -- fix up array scan key references
539 : *
540 : * When _bt_preprocess_array_keys performed initial array preprocessing, it
541 : * set each array's array->scan_key to its scankey's arrayKeyData[] offset.
542 : * This function handles translation of the scan key references from the
543 : * BTArrayKeyInfo info array, from input scan key references (to the keys in
544 : * arrayKeyData[]), into output references (to the keys in so->keyData[]).
545 : * Caller's keyDataMap[] array tells us how to perform this remapping.
546 : *
547 : * Also finalizes so->orderProcs[] for the scan. Arrays already have an ORDER
548 : * proc, which might need to be repositioned to its so->keyData[]-wise offset
549 : * (very much like the remapping that we apply to array->scan_key references).
550 : * Non-array equality strategy scan keys (that survived preprocessing) don't
551 : * yet have an so->orderProcs[] entry, so we set one for them here.
552 : *
553 : * Also converts single-element array scan keys into equivalent non-array
554 : * equality scan keys, which decrements so->numArrayKeys. It's possible that
555 : * this will leave this new btrescan without any arrays at all. This isn't
556 : * necessary for correctness; it's just an optimization. Non-array equality
557 : * scan keys are slightly faster than equivalent array scan keys at runtime.
558 : */
559 : static void
560 578 : _bt_preprocess_array_keys_final(IndexScanDesc scan, int *keyDataMap)
561 : {
562 578 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
563 578 : Relation rel = scan->indexRelation;
564 578 : int arrayidx = 0;
565 578 : int last_equal_output_ikey PG_USED_FOR_ASSERTS_ONLY = -1;
566 :
567 : Assert(so->qual_ok);
568 :
569 : /*
570 : * Nothing for us to do when _bt_preprocess_array_keys only had to deal
571 : * with array inequalities
572 : */
573 578 : if (so->numArrayKeys == 0)
574 0 : return;
575 :
576 1746 : for (int output_ikey = 0; output_ikey < so->numberOfKeys; output_ikey++)
577 : {
578 1180 : ScanKey outkey = so->keyData + output_ikey;
579 : int input_ikey;
580 1180 : bool found PG_USED_FOR_ASSERTS_ONLY = false;
581 :
582 : Assert(outkey->sk_strategy != InvalidStrategy);
583 :
584 1180 : if (outkey->sk_strategy != BTEqualStrategyNumber)
585 18 : continue;
586 :
587 1162 : input_ikey = keyDataMap[output_ikey];
588 :
589 : Assert(last_equal_output_ikey < output_ikey);
590 : Assert(last_equal_output_ikey < input_ikey);
591 1162 : last_equal_output_ikey = output_ikey;
592 :
593 : /*
594 : * We're lazy about looking up ORDER procs for non-array keys, since
595 : * not all input keys become output keys. Take care of it now.
596 : */
597 1162 : if (!(outkey->sk_flags & SK_SEARCHARRAY))
598 : {
599 : Oid elemtype;
600 :
601 : /* No need for an ORDER proc given an IS NULL scan key */
602 422 : if (outkey->sk_flags & SK_SEARCHNULL)
603 6 : continue;
604 :
605 : /*
606 : * A non-required scan key doesn't need an ORDER proc, either
607 : * (unless it's associated with an array, which this one isn't)
608 : */
609 416 : if (!(outkey->sk_flags & SK_BT_REQFWD))
610 90 : continue;
611 :
612 326 : elemtype = outkey->sk_subtype;
613 326 : if (elemtype == InvalidOid)
614 0 : elemtype = rel->rd_opcintype[outkey->sk_attno - 1];
615 :
616 326 : _bt_setup_array_cmp(scan, outkey, elemtype,
617 326 : &so->orderProcs[output_ikey], NULL);
618 326 : continue;
619 : }
620 :
621 : /*
622 : * Reorder existing array scan key so->orderProcs[] entries.
623 : *
624 : * Doing this in-place is safe because preprocessing is required to
625 : * output all equality strategy scan keys in original input order
626 : * (among each group of entries against the same index attribute).
627 : * This is also the order that the arrays themselves appear in.
628 : */
629 740 : so->orderProcs[output_ikey] = so->orderProcs[input_ikey];
630 :
631 : /* Fix-up array->scan_key references for arrays */
632 740 : for (; arrayidx < so->numArrayKeys; arrayidx++)
633 : {
634 740 : BTArrayKeyInfo *array = &so->arrayKeys[arrayidx];
635 :
636 : Assert(array->num_elems > 0);
637 :
638 740 : if (array->scan_key == input_ikey)
639 : {
640 : /* found it */
641 740 : array->scan_key = output_ikey;
642 740 : found = true;
643 :
644 : /*
645 : * Transform array scan keys that have exactly 1 element
646 : * remaining (following all prior preprocessing) into
647 : * equivalent non-array scan keys.
648 : */
649 740 : if (array->num_elems == 1)
650 : {
651 18 : outkey->sk_flags &= ~SK_SEARCHARRAY;
652 18 : outkey->sk_argument = array->elem_values[0];
653 18 : so->numArrayKeys--;
654 :
655 : /* If we're out of array keys, we can quit right away */
656 18 : if (so->numArrayKeys == 0)
657 12 : return;
658 :
659 : /* Shift other arrays forward */
660 6 : memmove(array, array + 1,
661 : sizeof(BTArrayKeyInfo) *
662 6 : (so->numArrayKeys - arrayidx));
663 :
664 : /*
665 : * Don't increment arrayidx (there was an entry that was
666 : * just shifted forward to the offset at arrayidx, which
667 : * will still need to be matched)
668 : */
669 : }
670 : else
671 : {
672 : /* Match found, so done with this array */
673 722 : arrayidx++;
674 : }
675 :
676 728 : break;
677 : }
678 : }
679 :
680 : Assert(found);
681 : }
682 :
683 : /*
684 : * Parallel index scans require space in shared memory to store the
685 : * current array elements (for arrays kept by preprocessing) to schedule
686 : * the next primitive index scan. The underlying structure is protected
687 : * using a spinlock, so defensively limit its size. In practice this can
688 : * only affect parallel scans that use an incomplete opfamily.
689 : */
690 566 : if (scan->parallel_scan && so->numArrayKeys > INDEX_MAX_KEYS)
691 0 : ereport(ERROR,
692 : (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
693 : errmsg_internal("number of array scan keys left by preprocessing (%d) exceeds the maximum allowed by parallel btree index scans (%d)",
694 : so->numArrayKeys, INDEX_MAX_KEYS)));
695 : }
696 :
697 : /*
698 : * _bt_setup_array_cmp() -- Set up array comparison functions
699 : *
700 : * Sets ORDER proc in caller's orderproc argument, which is used during binary
701 : * searches of arrays during the index scan. Also sets a same-type ORDER proc
702 : * in caller's *sortprocp argument, which is used when sorting the array.
703 : *
704 : * Preprocessing calls here with all equality strategy scan keys (when scan
705 : * uses equality array keys), including those not associated with any array.
706 : * See _bt_advance_array_keys for an explanation of why it'll need to treat
707 : * simple scalar equality scan keys as degenerate single element arrays.
708 : *
709 : * Caller should pass an orderproc pointing to space that'll store the ORDER
710 : * proc for the scan, and a *sortprocp pointing to its own separate space.
711 : * When calling here for a non-array scan key, sortprocp arg should be NULL.
712 : *
713 : * In the common case where we don't need to deal with cross-type operators,
714 : * only one ORDER proc is actually required by caller. We'll set *sortprocp
715 : * to point to the same memory that caller's orderproc continues to point to.
716 : * Otherwise, *sortprocp will continue to point to caller's own space. Either
717 : * way, *sortprocp will point to a same-type ORDER proc (since that's the only
718 : * safe way to sort/deduplicate the array associated with caller's scan key).
719 : */
720 : static void
721 1590 : _bt_setup_array_cmp(IndexScanDesc scan, ScanKey skey, Oid elemtype,
722 : FmgrInfo *orderproc, FmgrInfo **sortprocp)
723 : {
724 1590 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
725 1590 : Relation rel = scan->indexRelation;
726 : RegProcedure cmp_proc;
727 1590 : Oid opcintype = rel->rd_opcintype[skey->sk_attno - 1];
728 :
729 : Assert(skey->sk_strategy == BTEqualStrategyNumber);
730 : Assert(OidIsValid(elemtype));
731 :
732 : /*
733 : * If scankey operator is not a cross-type comparison, we can use the
734 : * cached comparison function; otherwise gotta look it up in the catalogs
735 : */
736 1590 : if (elemtype == opcintype)
737 : {
738 : /* Set same-type ORDER procs for caller */
739 1584 : *orderproc = *index_getprocinfo(rel, skey->sk_attno, BTORDER_PROC);
740 1584 : if (sortprocp)
741 1258 : *sortprocp = orderproc;
742 :
743 1584 : return;
744 : }
745 :
746 : /*
747 : * Look up the appropriate cross-type comparison function in the opfamily.
748 : *
749 : * Use the opclass input type as the left hand arg type, and the array
750 : * element type as the right hand arg type (since binary searches use an
751 : * index tuple's attribute value to search for a matching array element).
752 : *
753 : * Note: it's possible that this would fail, if the opfamily is
754 : * incomplete, but only in cases where it's quite likely that _bt_first
755 : * would fail in just the same way (had we not failed before it could).
756 : */
757 6 : cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
758 : opcintype, elemtype, BTORDER_PROC);
759 6 : if (!RegProcedureIsValid(cmp_proc))
760 0 : elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
761 : BTORDER_PROC, opcintype, elemtype, skey->sk_attno,
762 : RelationGetRelationName(rel));
763 :
764 : /* Set cross-type ORDER proc for caller */
765 6 : fmgr_info_cxt(cmp_proc, orderproc, so->arrayContext);
766 :
767 : /* Done if caller doesn't actually have an array they'll need to sort */
768 6 : if (!sortprocp)
769 0 : return;
770 :
771 : /*
772 : * Look up the appropriate same-type comparison function in the opfamily.
773 : *
774 : * Note: it's possible that this would fail, if the opfamily is
775 : * incomplete, but it seems quite unlikely that an opfamily would omit
776 : * non-cross-type comparison procs for any datatype that it supports at
777 : * all.
778 : */
779 6 : cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
780 : elemtype, elemtype, BTORDER_PROC);
781 6 : if (!RegProcedureIsValid(cmp_proc))
782 0 : elog(ERROR, "missing support function %d(%u,%u) for attribute %d of index \"%s\"",
783 : BTORDER_PROC, elemtype, elemtype,
784 : skey->sk_attno, RelationGetRelationName(rel));
785 :
786 : /* Set same-type ORDER proc for caller */
787 6 : fmgr_info_cxt(cmp_proc, *sortprocp, so->arrayContext);
788 : }
789 :
790 : /*
791 : * _bt_find_extreme_element() -- get least or greatest array element
792 : *
793 : * scan and skey identify the index column, whose opfamily determines the
794 : * comparison semantics. strat should be BTLessStrategyNumber to get the
795 : * least element, or BTGreaterStrategyNumber to get the greatest.
796 : */
797 : static Datum
798 12 : _bt_find_extreme_element(IndexScanDesc scan, ScanKey skey, Oid elemtype,
799 : StrategyNumber strat,
800 : Datum *elems, int nelems)
801 : {
802 12 : Relation rel = scan->indexRelation;
803 : Oid cmp_op;
804 : RegProcedure cmp_proc;
805 : FmgrInfo flinfo;
806 : Datum result;
807 : int i;
808 :
809 : /*
810 : * Look up the appropriate comparison operator in the opfamily.
811 : *
812 : * Note: it's possible that this would fail, if the opfamily is
813 : * incomplete, but it seems quite unlikely that an opfamily would omit
814 : * non-cross-type comparison operators for any datatype that it supports
815 : * at all.
816 : */
817 : Assert(skey->sk_strategy != BTEqualStrategyNumber);
818 : Assert(OidIsValid(elemtype));
819 12 : cmp_op = get_opfamily_member(rel->rd_opfamily[skey->sk_attno - 1],
820 : elemtype,
821 : elemtype,
822 : strat);
823 12 : if (!OidIsValid(cmp_op))
824 0 : elog(ERROR, "missing operator %d(%u,%u) in opfamily %u",
825 : strat, elemtype, elemtype,
826 : rel->rd_opfamily[skey->sk_attno - 1]);
827 12 : cmp_proc = get_opcode(cmp_op);
828 12 : if (!RegProcedureIsValid(cmp_proc))
829 0 : elog(ERROR, "missing oprcode for operator %u", cmp_op);
830 :
831 12 : fmgr_info(cmp_proc, &flinfo);
832 :
833 : Assert(nelems > 0);
834 12 : result = elems[0];
835 36 : for (i = 1; i < nelems; i++)
836 : {
837 24 : if (DatumGetBool(FunctionCall2Coll(&flinfo,
838 : skey->sk_collation,
839 24 : elems[i],
840 : result)))
841 6 : result = elems[i];
842 : }
843 :
844 12 : return result;
845 : }
846 :
847 : /*
848 : * _bt_sort_array_elements() -- sort and de-dup array elements
849 : *
850 : * The array elements are sorted in-place, and the new number of elements
851 : * after duplicate removal is returned.
852 : *
853 : * skey identifies the index column whose opfamily determines the comparison
854 : * semantics, and sortproc is a corresponding ORDER proc. If reverse is true,
855 : * we sort in descending order.
856 : */
857 : static int
858 1264 : _bt_sort_array_elements(ScanKey skey, FmgrInfo *sortproc, bool reverse,
859 : Datum *elems, int nelems)
860 : {
861 : BTSortArrayContext cxt;
862 :
863 1264 : if (nelems <= 1)
864 12 : return nelems; /* no work to do */
865 :
866 : /* Sort the array elements */
867 1252 : cxt.sortproc = sortproc;
868 1252 : cxt.collation = skey->sk_collation;
869 1252 : cxt.reverse = reverse;
870 1252 : qsort_arg(elems, nelems, sizeof(Datum),
871 : _bt_compare_array_elements, &cxt);
872 :
873 : /* Now scan the sorted elements and remove duplicates */
874 1252 : return qunique_arg(elems, nelems, sizeof(Datum),
875 : _bt_compare_array_elements, &cxt);
876 : }
877 :
878 : /*
879 : * _bt_merge_arrays() -- merge next array's elements into an original array
880 : *
881 : * Called when preprocessing encounters a pair of array equality scan keys,
882 : * both against the same index attribute (during initial array preprocessing).
883 : * Merging reorganizes caller's original array (the left hand arg) in-place,
884 : * without ever copying elements from one array into the other. (Mixing the
885 : * elements together like this would be wrong, since they don't necessarily
886 : * use the same underlying element type, despite all the other similarities.)
887 : *
888 : * Both arrays must have already been sorted and deduplicated by calling
889 : * _bt_sort_array_elements. sortproc is the same-type ORDER proc that was
890 : * just used to sort and deduplicate caller's "next" array. We'll usually be
891 : * able to reuse that order PROC to merge the arrays together now. If not,
892 : * then we'll perform a separate ORDER proc lookup.
893 : *
894 : * If the opfamily doesn't supply a complete set of cross-type ORDER procs we
895 : * may not be able to determine which elements are contradictory. If we have
896 : * the required ORDER proc then we return true (and validly set *nelems_orig),
897 : * guaranteeing that at least the next array can be considered redundant. We
898 : * return false if the required comparisons cannot not be made (caller must
899 : * keep both arrays when this happens).
900 : */
901 : static bool
902 12 : _bt_merge_arrays(IndexScanDesc scan, ScanKey skey, FmgrInfo *sortproc,
903 : bool reverse, Oid origelemtype, Oid nextelemtype,
904 : Datum *elems_orig, int *nelems_orig,
905 : Datum *elems_next, int nelems_next)
906 : {
907 12 : Relation rel = scan->indexRelation;
908 12 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
909 : BTSortArrayContext cxt;
910 12 : int nelems_orig_start = *nelems_orig,
911 12 : nelems_orig_merged = 0;
912 12 : FmgrInfo *mergeproc = sortproc;
913 : FmgrInfo crosstypeproc;
914 :
915 : Assert(skey->sk_strategy == BTEqualStrategyNumber);
916 : Assert(OidIsValid(origelemtype) && OidIsValid(nextelemtype));
917 :
918 12 : if (origelemtype != nextelemtype)
919 : {
920 : RegProcedure cmp_proc;
921 :
922 : /*
923 : * Cross-array-element-type merging is required, so can't just reuse
924 : * sortproc when merging
925 : */
926 6 : cmp_proc = get_opfamily_proc(rel->rd_opfamily[skey->sk_attno - 1],
927 : origelemtype, nextelemtype, BTORDER_PROC);
928 6 : if (!RegProcedureIsValid(cmp_proc))
929 : {
930 : /* Can't make the required comparisons */
931 0 : return false;
932 : }
933 :
934 : /* We have all we need to determine redundancy/contradictoriness */
935 6 : mergeproc = &crosstypeproc;
936 6 : fmgr_info_cxt(cmp_proc, mergeproc, so->arrayContext);
937 : }
938 :
939 12 : cxt.sortproc = mergeproc;
940 12 : cxt.collation = skey->sk_collation;
941 12 : cxt.reverse = reverse;
942 :
943 54 : for (int i = 0, j = 0; i < nelems_orig_start && j < nelems_next;)
944 : {
945 42 : Datum *oelem = elems_orig + i,
946 42 : *nelem = elems_next + j;
947 42 : int res = _bt_compare_array_elements(oelem, nelem, &cxt);
948 :
949 42 : if (res == 0)
950 : {
951 6 : elems_orig[nelems_orig_merged++] = *oelem;
952 6 : i++;
953 6 : j++;
954 : }
955 36 : else if (res < 0)
956 24 : i++;
957 : else /* res > 0 */
958 12 : j++;
959 : }
960 :
961 12 : *nelems_orig = nelems_orig_merged;
962 :
963 12 : return true;
964 : }
965 :
966 : /*
967 : * Compare an array scan key to a scalar scan key, eliminating contradictory
968 : * array elements such that the scalar scan key becomes redundant.
969 : *
970 : * Array elements can be eliminated as contradictory when excluded by some
971 : * other operator on the same attribute. For example, with an index scan qual
972 : * "WHERE a IN (1, 2, 3) AND a < 2", all array elements except the value "1"
973 : * are eliminated, and the < scan key is eliminated as redundant. Cases where
974 : * every array element is eliminated by a redundant scalar scan key have an
975 : * unsatisfiable qual, which we handle by setting *qual_ok=false for caller.
976 : *
977 : * If the opfamily doesn't supply a complete set of cross-type ORDER procs we
978 : * may not be able to determine which elements are contradictory. If we have
979 : * the required ORDER proc then we return true (and validly set *qual_ok),
980 : * guaranteeing that at least the scalar scan key can be considered redundant.
981 : * We return false if the comparison could not be made (caller must keep both
982 : * scan keys when this happens).
983 : */
984 : static bool
985 30 : _bt_compare_array_scankey_args(IndexScanDesc scan, ScanKey arraysk, ScanKey skey,
986 : FmgrInfo *orderproc, BTArrayKeyInfo *array,
987 : bool *qual_ok)
988 : {
989 30 : Relation rel = scan->indexRelation;
990 30 : Oid opcintype = rel->rd_opcintype[arraysk->sk_attno - 1];
991 30 : int cmpresult = 0,
992 30 : cmpexact = 0,
993 : matchelem,
994 30 : new_nelems = 0;
995 : FmgrInfo crosstypeproc;
996 30 : FmgrInfo *orderprocp = orderproc;
997 :
998 : Assert(arraysk->sk_attno == skey->sk_attno);
999 : Assert(array->num_elems > 0);
1000 : Assert(!(arraysk->sk_flags & (SK_ISNULL | SK_ROW_HEADER | SK_ROW_MEMBER)));
1001 : Assert((arraysk->sk_flags & SK_SEARCHARRAY) &&
1002 : arraysk->sk_strategy == BTEqualStrategyNumber);
1003 : Assert(!(skey->sk_flags & (SK_ISNULL | SK_ROW_HEADER | SK_ROW_MEMBER)));
1004 : Assert(!(skey->sk_flags & SK_SEARCHARRAY) ||
1005 : skey->sk_strategy != BTEqualStrategyNumber);
1006 :
1007 : /*
1008 : * _bt_binsrch_array_skey searches an array for the entry best matching a
1009 : * datum of opclass input type for the index's attribute (on-disk type).
1010 : * We can reuse the array's ORDER proc whenever the non-array scan key's
1011 : * type is a match for the corresponding attribute's input opclass type.
1012 : * Otherwise, we have to do another ORDER proc lookup so that our call to
1013 : * _bt_binsrch_array_skey applies the correct comparator.
1014 : *
1015 : * Note: we have to support the convention that sk_subtype == InvalidOid
1016 : * means the opclass input type; this is a hack to simplify life for
1017 : * ScanKeyInit().
1018 : */
1019 30 : if (skey->sk_subtype != opcintype && skey->sk_subtype != InvalidOid)
1020 : {
1021 : RegProcedure cmp_proc;
1022 : Oid arraysk_elemtype;
1023 :
1024 : /*
1025 : * Need an ORDER proc lookup to detect redundancy/contradictoriness
1026 : * with this pair of scankeys.
1027 : *
1028 : * Scalar scan key's argument will be passed to _bt_compare_array_skey
1029 : * as its tupdatum/lefthand argument (rhs arg is for array elements).
1030 : */
1031 6 : arraysk_elemtype = arraysk->sk_subtype;
1032 6 : if (arraysk_elemtype == InvalidOid)
1033 0 : arraysk_elemtype = rel->rd_opcintype[arraysk->sk_attno - 1];
1034 6 : cmp_proc = get_opfamily_proc(rel->rd_opfamily[arraysk->sk_attno - 1],
1035 : skey->sk_subtype, arraysk_elemtype,
1036 : BTORDER_PROC);
1037 6 : if (!RegProcedureIsValid(cmp_proc))
1038 : {
1039 : /* Can't make the comparison */
1040 0 : *qual_ok = false; /* suppress compiler warnings */
1041 0 : return false;
1042 : }
1043 :
1044 : /* We have all we need to determine redundancy/contradictoriness */
1045 6 : orderprocp = &crosstypeproc;
1046 6 : fmgr_info(cmp_proc, orderprocp);
1047 : }
1048 :
1049 30 : matchelem = _bt_binsrch_array_skey(orderprocp, false,
1050 : NoMovementScanDirection,
1051 : skey->sk_argument, false, array,
1052 : arraysk, &cmpresult);
1053 :
1054 30 : switch (skey->sk_strategy)
1055 : {
1056 6 : case BTLessStrategyNumber:
1057 6 : cmpexact = 1; /* exclude exact match, if any */
1058 : /* FALL THRU */
1059 6 : case BTLessEqualStrategyNumber:
1060 6 : if (cmpresult >= cmpexact)
1061 0 : matchelem++;
1062 : /* Resize, keeping elements from the start of the array */
1063 6 : new_nelems = matchelem;
1064 6 : break;
1065 12 : case BTEqualStrategyNumber:
1066 12 : if (cmpresult != 0)
1067 : {
1068 : /* qual is unsatisfiable */
1069 6 : new_nelems = 0;
1070 : }
1071 : else
1072 : {
1073 : /* Shift matching element to the start of the array, resize */
1074 6 : array->elem_values[0] = array->elem_values[matchelem];
1075 6 : new_nelems = 1;
1076 : }
1077 12 : break;
1078 6 : case BTGreaterEqualStrategyNumber:
1079 6 : cmpexact = 1; /* include exact match, if any */
1080 : /* FALL THRU */
1081 12 : case BTGreaterStrategyNumber:
1082 12 : if (cmpresult >= cmpexact)
1083 6 : matchelem++;
1084 : /* Shift matching elements to the start of the array, resize */
1085 12 : new_nelems = array->num_elems - matchelem;
1086 12 : memmove(array->elem_values, array->elem_values + matchelem,
1087 : sizeof(Datum) * new_nelems);
1088 12 : break;
1089 0 : default:
1090 0 : elog(ERROR, "unrecognized StrategyNumber: %d",
1091 : (int) skey->sk_strategy);
1092 : break;
1093 : }
1094 :
1095 : Assert(new_nelems >= 0);
1096 : Assert(new_nelems <= array->num_elems);
1097 :
1098 30 : array->num_elems = new_nelems;
1099 30 : *qual_ok = new_nelems > 0;
1100 :
1101 30 : return true;
1102 : }
1103 :
1104 : /*
1105 : * qsort_arg comparator for sorting array elements
1106 : */
1107 : static int
1108 9446 : _bt_compare_array_elements(const void *a, const void *b, void *arg)
1109 : {
1110 9446 : Datum da = *((const Datum *) a);
1111 9446 : Datum db = *((const Datum *) b);
1112 9446 : BTSortArrayContext *cxt = (BTSortArrayContext *) arg;
1113 : int32 compare;
1114 :
1115 9446 : compare = DatumGetInt32(FunctionCall2Coll(cxt->sortproc,
1116 : cxt->collation,
1117 : da, db));
1118 9446 : if (cxt->reverse)
1119 30 : INVERT_COMPARE_RESULT(compare);
1120 9446 : return compare;
1121 : }
1122 :
1123 : /*
1124 : * _bt_compare_array_skey() -- apply array comparison function
1125 : *
1126 : * Compares caller's tuple attribute value to a scan key/array element.
1127 : * Helper function used during binary searches of SK_SEARCHARRAY arrays.
1128 : *
1129 : * This routine returns:
1130 : * <0 if tupdatum < arrdatum;
1131 : * 0 if tupdatum == arrdatum;
1132 : * >0 if tupdatum > arrdatum.
1133 : *
1134 : * This is essentially the same interface as _bt_compare: both functions
1135 : * compare the value that they're searching for to a binary search pivot.
1136 : * However, unlike _bt_compare, this function's "tuple argument" comes first,
1137 : * while its "array/scankey argument" comes second.
1138 : */
1139 : static inline int32
1140 13770 : _bt_compare_array_skey(FmgrInfo *orderproc,
1141 : Datum tupdatum, bool tupnull,
1142 : Datum arrdatum, ScanKey cur)
1143 : {
1144 13770 : int32 result = 0;
1145 :
1146 : Assert(cur->sk_strategy == BTEqualStrategyNumber);
1147 :
1148 13770 : if (tupnull) /* NULL tupdatum */
1149 : {
1150 6 : if (cur->sk_flags & SK_ISNULL)
1151 6 : result = 0; /* NULL "=" NULL */
1152 0 : else if (cur->sk_flags & SK_BT_NULLS_FIRST)
1153 0 : result = -1; /* NULL "<" NOT_NULL */
1154 : else
1155 0 : result = 1; /* NULL ">" NOT_NULL */
1156 : }
1157 13764 : else if (cur->sk_flags & SK_ISNULL) /* NOT_NULL tupdatum, NULL arrdatum */
1158 : {
1159 6 : if (cur->sk_flags & SK_BT_NULLS_FIRST)
1160 0 : result = 1; /* NOT_NULL ">" NULL */
1161 : else
1162 6 : result = -1; /* NOT_NULL "<" NULL */
1163 : }
1164 : else
1165 : {
1166 : /*
1167 : * Like _bt_compare, we need to be careful of cross-type comparisons,
1168 : * so the left value has to be the value that came from an index tuple
1169 : */
1170 13758 : result = DatumGetInt32(FunctionCall2Coll(orderproc, cur->sk_collation,
1171 : tupdatum, arrdatum));
1172 :
1173 : /*
1174 : * We flip the sign by following the obvious rule: flip whenever the
1175 : * column is a DESC column.
1176 : *
1177 : * _bt_compare does it the wrong way around (flip when *ASC*) in order
1178 : * to compensate for passing its orderproc arguments backwards. We
1179 : * don't need to play these games because we find it natural to pass
1180 : * tupdatum as the left value (and arrdatum as the right value).
1181 : */
1182 13758 : if (cur->sk_flags & SK_BT_DESC)
1183 24 : INVERT_COMPARE_RESULT(result);
1184 : }
1185 :
1186 13770 : return result;
1187 : }
1188 :
1189 : /*
1190 : * _bt_binsrch_array_skey() -- Binary search for next matching array key
1191 : *
1192 : * Returns an index to the first array element >= caller's tupdatum argument.
1193 : * This convention is more natural for forwards scan callers, but that can't
1194 : * really matter to backwards scan callers. Both callers require handling for
1195 : * the case where the match we return is < tupdatum, and symmetric handling
1196 : * for the case where our best match is > tupdatum.
1197 : *
1198 : * Also sets *set_elem_result to the result _bt_compare_array_skey returned
1199 : * when we used it to compare the matching array element to tupdatum/tupnull.
1200 : *
1201 : * cur_elem_trig indicates if array advancement was triggered by this array's
1202 : * scan key, and that the array is for a required scan key. We can apply this
1203 : * information to find the next matching array element in the current scan
1204 : * direction using far fewer comparisons (fewer on average, compared to naive
1205 : * binary search). This scheme takes advantage of an important property of
1206 : * required arrays: required arrays always advance in lockstep with the index
1207 : * scan's progress through the index's key space.
1208 : */
1209 : static int
1210 4520 : _bt_binsrch_array_skey(FmgrInfo *orderproc,
1211 : bool cur_elem_trig, ScanDirection dir,
1212 : Datum tupdatum, bool tupnull,
1213 : BTArrayKeyInfo *array, ScanKey cur,
1214 : int32 *set_elem_result)
1215 : {
1216 4520 : int low_elem = 0,
1217 4520 : mid_elem = -1,
1218 4520 : high_elem = array->num_elems - 1,
1219 4520 : result = 0;
1220 : Datum arrdatum;
1221 :
1222 : Assert(cur->sk_flags & SK_SEARCHARRAY);
1223 : Assert(cur->sk_strategy == BTEqualStrategyNumber);
1224 :
1225 4520 : if (cur_elem_trig)
1226 : {
1227 : Assert(!ScanDirectionIsNoMovement(dir));
1228 : Assert(cur->sk_flags & SK_BT_REQFWD);
1229 :
1230 : /*
1231 : * When the scan key that triggered array advancement is a required
1232 : * array scan key, it is now certain that the current array element
1233 : * (plus all prior elements relative to the current scan direction)
1234 : * cannot possibly be at or ahead of the corresponding tuple value.
1235 : * (_bt_checkkeys must have called _bt_tuple_before_array_skeys, which
1236 : * makes sure this is true as a condition of advancing the arrays.)
1237 : *
1238 : * This makes it safe to exclude array elements up to and including
1239 : * the former-current array element from our search.
1240 : *
1241 : * Separately, when array advancement was triggered by a required scan
1242 : * key, the array element immediately after the former-current element
1243 : * is often either an exact tupdatum match, or a "close by" near-match
1244 : * (a near-match tupdatum is one whose key space falls _between_ the
1245 : * former-current and new-current array elements). We'll detect both
1246 : * cases via an optimistic comparison of the new search lower bound
1247 : * (or new search upper bound in the case of backwards scans).
1248 : */
1249 3990 : if (ScanDirectionIsForward(dir))
1250 : {
1251 3966 : low_elem = array->cur_elem + 1; /* old cur_elem exhausted */
1252 :
1253 : /* Compare prospective new cur_elem (also the new lower bound) */
1254 3966 : if (high_elem >= low_elem)
1255 : {
1256 3158 : arrdatum = array->elem_values[low_elem];
1257 3158 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
1258 : arrdatum, cur);
1259 :
1260 3158 : if (result <= 0)
1261 : {
1262 : /* Optimistic comparison optimization worked out */
1263 3072 : *set_elem_result = result;
1264 3072 : return low_elem;
1265 : }
1266 86 : mid_elem = low_elem;
1267 86 : low_elem++; /* this cur_elem exhausted, too */
1268 : }
1269 :
1270 894 : if (high_elem < low_elem)
1271 : {
1272 : /* Caller needs to perform "beyond end" array advancement */
1273 814 : *set_elem_result = 1;
1274 814 : return high_elem;
1275 : }
1276 : }
1277 : else
1278 : {
1279 24 : high_elem = array->cur_elem - 1; /* old cur_elem exhausted */
1280 :
1281 : /* Compare prospective new cur_elem (also the new upper bound) */
1282 24 : if (high_elem >= low_elem)
1283 : {
1284 18 : arrdatum = array->elem_values[high_elem];
1285 18 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
1286 : arrdatum, cur);
1287 :
1288 18 : if (result >= 0)
1289 : {
1290 : /* Optimistic comparison optimization worked out */
1291 18 : *set_elem_result = result;
1292 18 : return high_elem;
1293 : }
1294 0 : mid_elem = high_elem;
1295 0 : high_elem--; /* this cur_elem exhausted, too */
1296 : }
1297 :
1298 6 : if (high_elem < low_elem)
1299 : {
1300 : /* Caller needs to perform "beyond end" array advancement */
1301 6 : *set_elem_result = -1;
1302 6 : return low_elem;
1303 : }
1304 : }
1305 : }
1306 :
1307 1116 : while (high_elem > low_elem)
1308 : {
1309 650 : mid_elem = low_elem + ((high_elem - low_elem) / 2);
1310 650 : arrdatum = array->elem_values[mid_elem];
1311 :
1312 650 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
1313 : arrdatum, cur);
1314 :
1315 650 : if (result == 0)
1316 : {
1317 : /*
1318 : * It's safe to quit as soon as we see an equal array element.
1319 : * This often saves an extra comparison or two...
1320 : */
1321 144 : low_elem = mid_elem;
1322 144 : break;
1323 : }
1324 :
1325 506 : if (result > 0)
1326 446 : low_elem = mid_elem + 1;
1327 : else
1328 60 : high_elem = mid_elem;
1329 : }
1330 :
1331 : /*
1332 : * ...but our caller also cares about how its searched-for tuple datum
1333 : * compares to the low_elem datum. Must always set *set_elem_result with
1334 : * the result of that comparison specifically.
1335 : */
1336 610 : if (low_elem != mid_elem)
1337 418 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
1338 418 : array->elem_values[low_elem], cur);
1339 :
1340 610 : *set_elem_result = result;
1341 :
1342 610 : return low_elem;
1343 : }
1344 :
1345 : /*
1346 : * _bt_start_array_keys() -- Initialize array keys at start of a scan
1347 : *
1348 : * Set up the cur_elem counters and fill in the first sk_argument value for
1349 : * each array scankey.
1350 : */
1351 : void
1352 1920 : _bt_start_array_keys(IndexScanDesc scan, ScanDirection dir)
1353 : {
1354 1920 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1355 : int i;
1356 :
1357 : Assert(so->numArrayKeys);
1358 : Assert(so->qual_ok);
1359 :
1360 4152 : for (i = 0; i < so->numArrayKeys; i++)
1361 : {
1362 2232 : BTArrayKeyInfo *curArrayKey = &so->arrayKeys[i];
1363 2232 : ScanKey skey = &so->keyData[curArrayKey->scan_key];
1364 :
1365 : Assert(curArrayKey->num_elems > 0);
1366 : Assert(skey->sk_flags & SK_SEARCHARRAY);
1367 :
1368 2232 : if (ScanDirectionIsBackward(dir))
1369 1052 : curArrayKey->cur_elem = curArrayKey->num_elems - 1;
1370 : else
1371 1180 : curArrayKey->cur_elem = 0;
1372 2232 : skey->sk_argument = curArrayKey->elem_values[curArrayKey->cur_elem];
1373 : }
1374 1920 : so->scanBehind = so->oppositeDirCheck = false; /* reset */
1375 1920 : }
1376 :
1377 : /*
1378 : * _bt_advance_array_keys_increment() -- Advance to next set of array elements
1379 : *
1380 : * Advances the array keys by a single increment in the current scan
1381 : * direction. When there are multiple array keys this can roll over from the
1382 : * lowest order array to higher order arrays.
1383 : *
1384 : * Returns true if there is another set of values to consider, false if not.
1385 : * On true result, the scankeys are initialized with the next set of values.
1386 : * On false result, the scankeys stay the same, and the array keys are not
1387 : * advanced (every array remains at its final element for scan direction).
1388 : */
1389 : static bool
1390 928 : _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir)
1391 : {
1392 928 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1393 :
1394 : /*
1395 : * We must advance the last array key most quickly, since it will
1396 : * correspond to the lowest-order index column among the available
1397 : * qualifications
1398 : */
1399 1974 : for (int i = so->numArrayKeys - 1; i >= 0; i--)
1400 : {
1401 1084 : BTArrayKeyInfo *curArrayKey = &so->arrayKeys[i];
1402 1084 : ScanKey skey = &so->keyData[curArrayKey->scan_key];
1403 1084 : int cur_elem = curArrayKey->cur_elem;
1404 1084 : int num_elems = curArrayKey->num_elems;
1405 1084 : bool rolled = false;
1406 :
1407 1084 : if (ScanDirectionIsForward(dir) && ++cur_elem >= num_elems)
1408 : {
1409 1040 : cur_elem = 0;
1410 1040 : rolled = true;
1411 : }
1412 44 : else if (ScanDirectionIsBackward(dir) && --cur_elem < 0)
1413 : {
1414 6 : cur_elem = num_elems - 1;
1415 6 : rolled = true;
1416 : }
1417 :
1418 1084 : curArrayKey->cur_elem = cur_elem;
1419 1084 : skey->sk_argument = curArrayKey->elem_values[cur_elem];
1420 1084 : if (!rolled)
1421 38 : return true;
1422 :
1423 : /* Need to advance next array key, if any */
1424 : }
1425 :
1426 : /*
1427 : * The array keys are now exhausted.
1428 : *
1429 : * Restore the array keys to the state they were in immediately before we
1430 : * were called. This ensures that the arrays only ever ratchet in the
1431 : * current scan direction.
1432 : *
1433 : * Without this, scans could overlook matching tuples when the scan
1434 : * direction gets reversed just before btgettuple runs out of items to
1435 : * return, but just after _bt_readpage prepares all the items from the
1436 : * scan's final page in so->currPos. When we're on the final page it is
1437 : * typical for so->currPos to get invalidated once btgettuple finally
1438 : * returns false, which'll effectively invalidate the scan's array keys.
1439 : * That hasn't happened yet, though -- and in general it may never happen.
1440 : */
1441 890 : _bt_start_array_keys(scan, -dir);
1442 :
1443 890 : return false;
1444 : }
1445 :
1446 : /*
1447 : * _bt_rewind_nonrequired_arrays() -- Rewind non-required arrays
1448 : *
1449 : * Called when _bt_advance_array_keys decides to start a new primitive index
1450 : * scan on the basis of the current scan position being before the position
1451 : * that _bt_first is capable of repositioning the scan to by applying an
1452 : * inequality operator required in the opposite-to-scan direction only.
1453 : *
1454 : * Although equality strategy scan keys (for both arrays and non-arrays alike)
1455 : * are either marked required in both directions or in neither direction,
1456 : * there is a sense in which non-required arrays behave like required arrays.
1457 : * With a qual such as "WHERE a IN (100, 200) AND b >= 3 AND c IN (5, 6, 7)",
1458 : * the scan key on "c" is non-required, but nevertheless enables positioning
1459 : * the scan at the first tuple >= "(100, 3, 5)" on the leaf level during the
1460 : * first descent of the tree by _bt_first. Later on, there could also be a
1461 : * second descent, that places the scan right before tuples >= "(200, 3, 5)".
1462 : * _bt_first must never be allowed to build an insertion scan key whose "c"
1463 : * entry is set to a value other than 5, the "c" array's first element/value.
1464 : * (Actually, it's the first in the current scan direction. This example uses
1465 : * a forward scan.)
1466 : *
1467 : * Calling here resets the array scan key elements for the scan's non-required
1468 : * arrays. This is strictly necessary for correctness in a subset of cases
1469 : * involving "required in opposite direction"-triggered primitive index scans.
1470 : * Not all callers are at risk of _bt_first using a non-required array like
1471 : * this, but advancement always resets the arrays when another primitive scan
1472 : * is scheduled, just to keep things simple. Array advancement even makes
1473 : * sure to reset non-required arrays during scans that have no inequalities.
1474 : * (Advancement still won't call here when there are no inequalities, though
1475 : * that's just because it's all handled indirectly instead.)
1476 : *
1477 : * Note: _bt_verify_arrays_bt_first is called by an assertion to enforce that
1478 : * everybody got this right.
1479 : */
1480 : static void
1481 0 : _bt_rewind_nonrequired_arrays(IndexScanDesc scan, ScanDirection dir)
1482 : {
1483 0 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1484 0 : int arrayidx = 0;
1485 :
1486 0 : for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
1487 : {
1488 0 : ScanKey cur = so->keyData + ikey;
1489 0 : BTArrayKeyInfo *array = NULL;
1490 : int first_elem_dir;
1491 :
1492 0 : if (!(cur->sk_flags & SK_SEARCHARRAY) ||
1493 0 : cur->sk_strategy != BTEqualStrategyNumber)
1494 0 : continue;
1495 :
1496 0 : array = &so->arrayKeys[arrayidx++];
1497 : Assert(array->scan_key == ikey);
1498 :
1499 0 : if ((cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)))
1500 0 : continue;
1501 :
1502 0 : if (ScanDirectionIsForward(dir))
1503 0 : first_elem_dir = 0;
1504 : else
1505 0 : first_elem_dir = array->num_elems - 1;
1506 :
1507 0 : if (array->cur_elem != first_elem_dir)
1508 : {
1509 0 : array->cur_elem = first_elem_dir;
1510 0 : cur->sk_argument = array->elem_values[first_elem_dir];
1511 : }
1512 : }
1513 0 : }
1514 :
1515 : /*
1516 : * _bt_tuple_before_array_skeys() -- too early to advance required arrays?
1517 : *
1518 : * We always compare the tuple using the current array keys (which we assume
1519 : * are already set in so->keyData[]). readpagetup indicates if tuple is the
1520 : * scan's current _bt_readpage-wise tuple.
1521 : *
1522 : * readpagetup callers must only call here when _bt_check_compare already set
1523 : * continuescan=false. We help these callers deal with _bt_check_compare's
1524 : * inability to distinguishing between the < and > cases (it uses equality
1525 : * operator scan keys, whereas we use 3-way ORDER procs). These callers pass
1526 : * a _bt_check_compare-set sktrig value that indicates which scan key
1527 : * triggered the call (!readpagetup callers just pass us sktrig=0 instead).
1528 : * This information allows us to avoid wastefully checking earlier scan keys
1529 : * that were already deemed to have been satisfied inside _bt_check_compare.
1530 : *
1531 : * Returns false when caller's tuple is >= the current required equality scan
1532 : * keys (or <=, in the case of backwards scans). This happens to readpagetup
1533 : * callers when the scan has reached the point of needing its array keys
1534 : * advanced; caller will need to advance required and non-required arrays at
1535 : * scan key offsets >= sktrig, plus scan keys < sktrig iff sktrig rolls over.
1536 : * (When we return false to readpagetup callers, tuple can only be == current
1537 : * required equality scan keys when caller's sktrig indicates that the arrays
1538 : * need to be advanced due to an unsatisfied required inequality key trigger.)
1539 : *
1540 : * Returns true when caller passes a tuple that is < the current set of
1541 : * equality keys for the most significant non-equal required scan key/column
1542 : * (or > the keys, during backwards scans). This happens to readpagetup
1543 : * callers when tuple is still before the start of matches for the scan's
1544 : * required equality strategy scan keys. (sktrig can't have indicated that an
1545 : * inequality strategy scan key wasn't satisfied in _bt_check_compare when we
1546 : * return true. In fact, we automatically return false when passed such an
1547 : * inequality sktrig by readpagetup callers -- _bt_check_compare's initial
1548 : * continuescan=false doesn't really need to be confirmed here by us.)
1549 : *
1550 : * !readpagetup callers optionally pass us *scanBehind, which tracks whether
1551 : * any missing truncated attributes might have affected array advancement
1552 : * (compared to what would happen if it was shown the first non-pivot tuple on
1553 : * the page to the right of caller's finaltup/high key tuple instead). It's
1554 : * only possible that we'll set *scanBehind to true when caller passes us a
1555 : * pivot tuple (with truncated -inf attributes) that we return false for.
1556 : */
1557 : static bool
1558 9052 : _bt_tuple_before_array_skeys(IndexScanDesc scan, ScanDirection dir,
1559 : IndexTuple tuple, TupleDesc tupdesc, int tupnatts,
1560 : bool readpagetup, int sktrig, bool *scanBehind)
1561 : {
1562 9052 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1563 :
1564 : Assert(so->numArrayKeys);
1565 : Assert(so->numberOfKeys);
1566 : Assert(sktrig == 0 || readpagetup);
1567 : Assert(!readpagetup || scanBehind == NULL);
1568 :
1569 9052 : if (scanBehind)
1570 1154 : *scanBehind = false;
1571 :
1572 9206 : for (int ikey = sktrig; ikey < so->numberOfKeys; ikey++)
1573 : {
1574 9162 : ScanKey cur = so->keyData + ikey;
1575 : Datum tupdatum;
1576 : bool tupnull;
1577 : int32 result;
1578 :
1579 : /* readpagetup calls require one ORDER proc comparison (at most) */
1580 : Assert(!readpagetup || ikey == sktrig);
1581 :
1582 : /*
1583 : * Once we reach a non-required scan key, we're completely done.
1584 : *
1585 : * Note: we deliberately don't consider the scan direction here.
1586 : * _bt_advance_array_keys caller requires that we track *scanBehind
1587 : * without concern for scan direction.
1588 : */
1589 9162 : if ((cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) == 0)
1590 : {
1591 : Assert(!readpagetup);
1592 : Assert(ikey > sktrig || ikey == 0);
1593 9008 : return false;
1594 : }
1595 :
1596 9162 : if (cur->sk_attno > tupnatts)
1597 : {
1598 : Assert(!readpagetup);
1599 :
1600 : /*
1601 : * When we reach a high key's truncated attribute, assume that the
1602 : * tuple attribute's value is >= the scan's equality constraint
1603 : * scan keys (but set *scanBehind to let interested callers know
1604 : * that a truncated attribute might have affected our answer).
1605 : */
1606 6 : if (scanBehind)
1607 6 : *scanBehind = true;
1608 :
1609 6 : return false;
1610 : }
1611 :
1612 : /*
1613 : * Deal with inequality strategy scan keys that _bt_check_compare set
1614 : * continuescan=false for
1615 : */
1616 9156 : if (cur->sk_strategy != BTEqualStrategyNumber)
1617 : {
1618 : /*
1619 : * When _bt_check_compare indicated that a required inequality
1620 : * scan key wasn't satisfied, there's no need to verify anything;
1621 : * caller always calls _bt_advance_array_keys with this sktrig.
1622 : */
1623 6 : if (readpagetup)
1624 6 : return false;
1625 :
1626 : /*
1627 : * Otherwise we can't give up, since we must check all required
1628 : * scan keys (required in either direction) in order to correctly
1629 : * track *scanBehind for caller
1630 : */
1631 0 : continue;
1632 : }
1633 :
1634 9150 : tupdatum = index_getattr(tuple, cur->sk_attno, tupdesc, &tupnull);
1635 :
1636 9150 : result = _bt_compare_array_skey(&so->orderProcs[ikey],
1637 : tupdatum, tupnull,
1638 : cur->sk_argument, cur);
1639 :
1640 : /*
1641 : * Does this comparison indicate that caller must _not_ advance the
1642 : * scan's arrays just yet?
1643 : */
1644 9150 : if ((ScanDirectionIsForward(dir) && result < 0) ||
1645 60 : (ScanDirectionIsBackward(dir) && result > 0))
1646 3824 : return true;
1647 :
1648 : /*
1649 : * Does this comparison indicate that caller should now advance the
1650 : * scan's arrays? (Must be if we get here during a readpagetup call.)
1651 : */
1652 5326 : if (readpagetup || result != 0)
1653 : {
1654 : Assert(result != 0);
1655 5172 : return false;
1656 : }
1657 :
1658 : /*
1659 : * Inconclusive -- need to check later scan keys, too.
1660 : *
1661 : * This must be a finaltup precheck, or a call made from an assertion.
1662 : */
1663 : Assert(result == 0);
1664 : }
1665 :
1666 : Assert(!readpagetup);
1667 :
1668 44 : return false;
1669 : }
1670 :
1671 : /*
1672 : * _bt_start_prim_scan() -- start scheduled primitive index scan?
1673 : *
1674 : * Returns true if _bt_checkkeys scheduled another primitive index scan, just
1675 : * as the last one ended. Otherwise returns false, indicating that the array
1676 : * keys are now fully exhausted.
1677 : *
1678 : * Only call here during scans with one or more equality type array scan keys,
1679 : * after _bt_first or _bt_next return false.
1680 : */
1681 : bool
1682 1726 : _bt_start_prim_scan(IndexScanDesc scan, ScanDirection dir)
1683 : {
1684 1726 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1685 :
1686 : Assert(so->numArrayKeys);
1687 :
1688 1726 : so->scanBehind = so->oppositeDirCheck = false; /* reset */
1689 :
1690 : /*
1691 : * Array keys are advanced within _bt_checkkeys when the scan reaches the
1692 : * leaf level (more precisely, they're advanced when the scan reaches the
1693 : * end of each distinct set of array elements). This process avoids
1694 : * repeat access to leaf pages (across multiple primitive index scans) by
1695 : * advancing the scan's array keys when it allows the primitive index scan
1696 : * to find nearby matching tuples (or when it eliminates ranges of array
1697 : * key space that can't possibly be satisfied by any index tuple).
1698 : *
1699 : * _bt_checkkeys sets a simple flag variable to schedule another primitive
1700 : * index scan. The flag tells us what to do.
1701 : *
1702 : * We cannot rely on _bt_first always reaching _bt_checkkeys. There are
1703 : * various cases where that won't happen. For example, if the index is
1704 : * completely empty, then _bt_first won't call _bt_readpage/_bt_checkkeys.
1705 : * We also don't expect a call to _bt_checkkeys during searches for a
1706 : * non-existent value that happens to be lower/higher than any existing
1707 : * value in the index.
1708 : *
1709 : * We don't require special handling for these cases -- we don't need to
1710 : * be explicitly instructed to _not_ perform another primitive index scan.
1711 : * It's up to code under the control of _bt_first to always set the flag
1712 : * when another primitive index scan will be required.
1713 : *
1714 : * This works correctly, even with the tricky cases listed above, which
1715 : * all involve access to leaf pages "near the boundaries of the key space"
1716 : * (whether it's from a leftmost/rightmost page, or an imaginary empty
1717 : * leaf root page). If _bt_checkkeys cannot be reached by a primitive
1718 : * index scan for one set of array keys, then it also won't be reached for
1719 : * any later set ("later" in terms of the direction that we scan the index
1720 : * and advance the arrays). The array keys won't have advanced in these
1721 : * cases, but that's the correct behavior (even _bt_advance_array_keys
1722 : * won't always advance the arrays at the point they become "exhausted").
1723 : */
1724 1726 : if (so->needPrimScan)
1725 : {
1726 : Assert(_bt_verify_arrays_bt_first(scan, dir));
1727 :
1728 : /*
1729 : * Flag was set -- must call _bt_first again, which will reset the
1730 : * scan's needPrimScan flag
1731 : */
1732 654 : return true;
1733 : }
1734 :
1735 : /* The top-level index scan ran out of tuples in this scan direction */
1736 1072 : if (scan->parallel_scan != NULL)
1737 30 : _bt_parallel_done(scan);
1738 :
1739 1072 : return false;
1740 : }
1741 :
1742 : /*
1743 : * _bt_advance_array_keys() -- Advance array elements using a tuple
1744 : *
1745 : * The scan always gets a new qual as a consequence of calling here (except
1746 : * when we determine that the top-level scan has run out of matching tuples).
1747 : * All later _bt_check_compare calls also use the same new qual that was first
1748 : * used here (at least until the next call here advances the keys once again).
1749 : * It's convenient to structure _bt_check_compare rechecks of caller's tuple
1750 : * (using the new qual) as one the steps of advancing the scan's array keys,
1751 : * so this function works as a wrapper around _bt_check_compare.
1752 : *
1753 : * Like _bt_check_compare, we'll set pstate.continuescan on behalf of the
1754 : * caller, and return a boolean indicating if caller's tuple satisfies the
1755 : * scan's new qual. But unlike _bt_check_compare, we set so->needPrimScan
1756 : * when we set continuescan=false, indicating if a new primitive index scan
1757 : * has been scheduled (otherwise, the top-level scan has run out of tuples in
1758 : * the current scan direction).
1759 : *
1760 : * Caller must use _bt_tuple_before_array_skeys to determine if the current
1761 : * place in the scan is >= the current array keys _before_ calling here.
1762 : * We're responsible for ensuring that caller's tuple is <= the newly advanced
1763 : * required array keys once we return. We try to find an exact match, but
1764 : * failing that we'll advance the array keys to whatever set of array elements
1765 : * comes next in the key space for the current scan direction. Required array
1766 : * keys "ratchet forwards" (or backwards). They can only advance as the scan
1767 : * itself advances through the index/key space.
1768 : *
1769 : * (The rules are the same for backwards scans, except that the operators are
1770 : * flipped: just replace the precondition's >= operator with a <=, and the
1771 : * postcondition's <= operator with a >=. In other words, just swap the
1772 : * precondition with the postcondition.)
1773 : *
1774 : * We also deal with "advancing" non-required arrays here. Callers whose
1775 : * sktrig scan key is non-required specify sktrig_required=false. These calls
1776 : * are the only exception to the general rule about always advancing the
1777 : * required array keys (the scan may not even have a required array). These
1778 : * callers should just pass a NULL pstate (since there is never any question
1779 : * of stopping the scan). No call to _bt_tuple_before_array_skeys is required
1780 : * ahead of these calls (it's already clear that any required scan keys must
1781 : * be satisfied by caller's tuple).
1782 : *
1783 : * Note that we deal with non-array required equality strategy scan keys as
1784 : * degenerate single element arrays here. Obviously, they can never really
1785 : * advance in the way that real arrays can, but they must still affect how we
1786 : * advance real array scan keys (exactly like true array equality scan keys).
1787 : * We have to keep around a 3-way ORDER proc for these (using the "=" operator
1788 : * won't do), since in general whether the tuple is < or > _any_ unsatisfied
1789 : * required equality key influences how the scan's real arrays must advance.
1790 : *
1791 : * Note also that we may sometimes need to advance the array keys when the
1792 : * existing required array keys (and other required equality keys) are already
1793 : * an exact match for every corresponding value from caller's tuple. We must
1794 : * do this for inequalities that _bt_check_compare set continuescan=false for.
1795 : * They'll advance the array keys here, just like any other scan key that
1796 : * _bt_check_compare stops on. (This can even happen _after_ we advance the
1797 : * array keys, in which case we'll advance the array keys a second time. That
1798 : * way _bt_checkkeys caller always has its required arrays advance to the
1799 : * maximum possible extent that its tuple will allow.)
1800 : */
1801 : static bool
1802 4334 : _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
1803 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
1804 : int sktrig, bool sktrig_required)
1805 : {
1806 4334 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1807 4334 : Relation rel = scan->indexRelation;
1808 4334 : ScanDirection dir = so->currPos.dir;
1809 4334 : int arrayidx = 0;
1810 4334 : bool beyond_end_advance = false,
1811 4334 : has_required_opposite_direction_only = false,
1812 4334 : oppodir_inequality_sktrig = false,
1813 4334 : all_required_satisfied = true,
1814 4334 : all_satisfied = true;
1815 :
1816 : /*
1817 : * Unset so->scanBehind (and so->oppositeDirCheck) in case they're still
1818 : * set from back when we dealt with the previous page's high key/finaltup
1819 : */
1820 4334 : so->scanBehind = so->oppositeDirCheck = false;
1821 :
1822 4334 : if (sktrig_required)
1823 : {
1824 : /*
1825 : * Precondition array state assertion
1826 : */
1827 : Assert(!_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc,
1828 : tupnatts, false, 0, NULL));
1829 :
1830 : /*
1831 : * Required scan key wasn't satisfied, so required arrays will have to
1832 : * advance. Invalidate page-level state that tracks whether the
1833 : * scan's required-in-opposite-direction-only keys are known to be
1834 : * satisfied by page's remaining tuples.
1835 : */
1836 4074 : pstate->firstmatch = false;
1837 :
1838 : /* Shouldn't have to invalidate 'prechecked', though */
1839 : Assert(!pstate->prechecked);
1840 :
1841 : /*
1842 : * Once we return we'll have a new set of required array keys, so
1843 : * reset state used by "look ahead" optimization
1844 : */
1845 4074 : pstate->rechecks = 0;
1846 4074 : pstate->targetdistance = 0;
1847 : }
1848 :
1849 : Assert(_bt_verify_keys_with_arraykeys(scan));
1850 :
1851 11926 : for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
1852 : {
1853 7814 : ScanKey cur = so->keyData + ikey;
1854 7814 : BTArrayKeyInfo *array = NULL;
1855 : Datum tupdatum;
1856 7814 : bool required = false,
1857 7814 : required_opposite_direction_only = false,
1858 : tupnull;
1859 : int32 result;
1860 7814 : int set_elem = 0;
1861 :
1862 7814 : if (cur->sk_strategy == BTEqualStrategyNumber)
1863 : {
1864 : /* Manage array state */
1865 7550 : if (cur->sk_flags & SK_SEARCHARRAY)
1866 : {
1867 5198 : array = &so->arrayKeys[arrayidx++];
1868 : Assert(array->scan_key == ikey);
1869 : }
1870 : }
1871 : else
1872 : {
1873 : /*
1874 : * Are any inequalities required in the opposite direction only
1875 : * present here?
1876 : */
1877 264 : if (((ScanDirectionIsForward(dir) &&
1878 264 : (cur->sk_flags & (SK_BT_REQBKWD))) ||
1879 120 : (ScanDirectionIsBackward(dir) &&
1880 120 : (cur->sk_flags & (SK_BT_REQFWD)))))
1881 138 : has_required_opposite_direction_only =
1882 138 : required_opposite_direction_only = true;
1883 : }
1884 :
1885 : /* Optimization: skip over known-satisfied scan keys */
1886 7814 : if (ikey < sktrig)
1887 2948 : continue;
1888 :
1889 6990 : if (cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))
1890 : {
1891 : Assert(sktrig_required);
1892 :
1893 5546 : required = true;
1894 :
1895 5546 : if (cur->sk_attno > tupnatts)
1896 : {
1897 : /* Set this just like _bt_tuple_before_array_skeys */
1898 : Assert(sktrig < ikey);
1899 0 : so->scanBehind = true;
1900 : }
1901 : }
1902 :
1903 : /*
1904 : * Handle a required non-array scan key that the initial call to
1905 : * _bt_check_compare indicated triggered array advancement, if any.
1906 : *
1907 : * The non-array scan key's strategy will be <, <=, or = during a
1908 : * forwards scan (or any one of =, >=, or > during a backwards scan).
1909 : * It follows that the corresponding tuple attribute's value must now
1910 : * be either > or >= the scan key value (for backwards scans it must
1911 : * be either < or <= that value).
1912 : *
1913 : * If this is a required equality strategy scan key, this is just an
1914 : * optimization; _bt_tuple_before_array_skeys already confirmed that
1915 : * this scan key places us ahead of caller's tuple. There's no need
1916 : * to repeat that work now. (The same underlying principle also gets
1917 : * applied by the cur_elem_trig optimization used to speed up searches
1918 : * for the next array element.)
1919 : *
1920 : * If this is a required inequality strategy scan key, we _must_ rely
1921 : * on _bt_check_compare like this; we aren't capable of directly
1922 : * evaluating required inequality strategy scan keys here, on our own.
1923 : */
1924 6990 : if (ikey == sktrig && !array)
1925 : {
1926 : Assert(sktrig_required && required && all_required_satisfied);
1927 :
1928 : /* Use "beyond end" advancement. See below for an explanation. */
1929 84 : beyond_end_advance = true;
1930 84 : all_satisfied = all_required_satisfied = false;
1931 :
1932 : /*
1933 : * Set a flag that remembers that this was an inequality required
1934 : * in the opposite scan direction only, that nevertheless
1935 : * triggered the call here.
1936 : *
1937 : * This only happens when an inequality operator (which must be
1938 : * strict) encounters a group of NULLs that indicate the end of
1939 : * non-NULL values for tuples in the current scan direction.
1940 : */
1941 84 : if (unlikely(required_opposite_direction_only))
1942 0 : oppodir_inequality_sktrig = true;
1943 :
1944 84 : continue;
1945 : }
1946 :
1947 : /*
1948 : * Nothing more for us to do with an inequality strategy scan key that
1949 : * wasn't the one that _bt_check_compare stopped on, though.
1950 : *
1951 : * Note: if our later call to _bt_check_compare (to recheck caller's
1952 : * tuple) sets continuescan=false due to finding this same inequality
1953 : * unsatisfied (possible when it's required in the scan direction),
1954 : * we'll deal with it via a recursive "second pass" call.
1955 : */
1956 6906 : else if (cur->sk_strategy != BTEqualStrategyNumber)
1957 18 : continue;
1958 :
1959 : /*
1960 : * Nothing for us to do with an equality strategy scan key that isn't
1961 : * marked required, either -- unless it's a non-required array
1962 : */
1963 6888 : else if (!required && !array)
1964 1170 : continue;
1965 :
1966 : /*
1967 : * Here we perform steps for all array scan keys after a required
1968 : * array scan key whose binary search triggered "beyond end of array
1969 : * element" array advancement due to encountering a tuple attribute
1970 : * value > the closest matching array key (or < for backwards scans).
1971 : */
1972 5718 : if (beyond_end_advance)
1973 : {
1974 : int final_elem_dir;
1975 :
1976 346 : if (ScanDirectionIsBackward(dir) || !array)
1977 144 : final_elem_dir = 0;
1978 : else
1979 202 : final_elem_dir = array->num_elems - 1;
1980 :
1981 346 : if (array && array->cur_elem != final_elem_dir)
1982 : {
1983 42 : array->cur_elem = final_elem_dir;
1984 42 : cur->sk_argument = array->elem_values[final_elem_dir];
1985 : }
1986 :
1987 346 : continue;
1988 : }
1989 :
1990 : /*
1991 : * Here we perform steps for all array scan keys after a required
1992 : * array scan key whose tuple attribute was < the closest matching
1993 : * array key when we dealt with it (or > for backwards scans).
1994 : *
1995 : * This earlier required array key already puts us ahead of caller's
1996 : * tuple in the key space (for the current scan direction). We must
1997 : * make sure that subsequent lower-order array keys do not put us too
1998 : * far ahead (ahead of tuples that have yet to be seen by our caller).
1999 : * For example, when a tuple "(a, b) = (42, 5)" advances the array
2000 : * keys on "a" from 40 to 45, we must also set "b" to whatever the
2001 : * first array element for "b" is. It would be wrong to allow "b" to
2002 : * be set based on the tuple value.
2003 : *
2004 : * Perform the same steps with truncated high key attributes. You can
2005 : * think of this as a "binary search" for the element closest to the
2006 : * value -inf. Again, the arrays must never get ahead of the scan.
2007 : */
2008 5372 : if (!all_required_satisfied || cur->sk_attno > tupnatts)
2009 : {
2010 : int first_elem_dir;
2011 :
2012 506 : if (ScanDirectionIsForward(dir) || !array)
2013 506 : first_elem_dir = 0;
2014 : else
2015 0 : first_elem_dir = array->num_elems - 1;
2016 :
2017 506 : if (array && array->cur_elem != first_elem_dir)
2018 : {
2019 192 : array->cur_elem = first_elem_dir;
2020 192 : cur->sk_argument = array->elem_values[first_elem_dir];
2021 : }
2022 :
2023 506 : continue;
2024 : }
2025 :
2026 : /*
2027 : * Search in scankey's array for the corresponding tuple attribute
2028 : * value from caller's tuple
2029 : */
2030 4866 : tupdatum = index_getattr(tuple, cur->sk_attno, tupdesc, &tupnull);
2031 :
2032 4866 : if (array)
2033 : {
2034 4490 : bool cur_elem_trig = (sktrig_required && ikey == sktrig);
2035 :
2036 : /*
2037 : * Binary search for closest match that's available from the array
2038 : */
2039 4490 : set_elem = _bt_binsrch_array_skey(&so->orderProcs[ikey],
2040 : cur_elem_trig, dir,
2041 : tupdatum, tupnull, array, cur,
2042 : &result);
2043 :
2044 : Assert(set_elem >= 0 && set_elem < array->num_elems);
2045 : }
2046 : else
2047 : {
2048 : Assert(sktrig_required && required);
2049 :
2050 : /*
2051 : * This is a required non-array equality strategy scan key, which
2052 : * we'll treat as a degenerate single element array.
2053 : *
2054 : * This scan key's imaginary "array" can't really advance, but it
2055 : * can still roll over like any other array. (Actually, this is
2056 : * no different to real single value arrays, which never advance
2057 : * without rolling over -- they can never truly advance, either.)
2058 : */
2059 376 : result = _bt_compare_array_skey(&so->orderProcs[ikey],
2060 : tupdatum, tupnull,
2061 : cur->sk_argument, cur);
2062 : }
2063 :
2064 : /*
2065 : * Consider "beyond end of array element" array advancement.
2066 : *
2067 : * When the tuple attribute value is > the closest matching array key
2068 : * (or < in the backwards scan case), we need to ratchet this array
2069 : * forward (backward) by one increment, so that caller's tuple ends up
2070 : * being < final array value instead (or > final array value instead).
2071 : * This process has to work for all of the arrays, not just this one:
2072 : * it must "carry" to higher-order arrays when the set_elem that we
2073 : * just found happens to be the final one for the scan's direction.
2074 : * Incrementing (decrementing) set_elem itself isn't good enough.
2075 : *
2076 : * Our approach is to provisionally use set_elem as if it was an exact
2077 : * match now, then set each later/less significant array to whatever
2078 : * its final element is. Once outside the loop we'll then "increment
2079 : * this array's set_elem" by calling _bt_advance_array_keys_increment.
2080 : * That way the process rolls over to higher order arrays as needed.
2081 : *
2082 : * Under this scheme any required arrays only ever ratchet forwards
2083 : * (or backwards), and always do so to the maximum possible extent
2084 : * that we can know will be safe without seeing the scan's next tuple.
2085 : * We don't need any special handling for required scan keys that lack
2086 : * a real array to advance, nor for redundant scan keys that couldn't
2087 : * be eliminated by _bt_preprocess_keys. It won't matter if some of
2088 : * our "true" array scan keys (or even all of them) are non-required.
2089 : */
2090 4866 : if (required &&
2091 4606 : ((ScanDirectionIsForward(dir) && result > 0) ||
2092 24 : (ScanDirectionIsBackward(dir) && result < 0)))
2093 844 : beyond_end_advance = true;
2094 :
2095 : Assert(all_required_satisfied && all_satisfied);
2096 4866 : if (result != 0)
2097 : {
2098 : /*
2099 : * Track whether caller's tuple satisfies our new post-advancement
2100 : * qual, for required scan keys, as well as for the entire set of
2101 : * interesting scan keys (all required scan keys plus non-required
2102 : * array scan keys are considered interesting.)
2103 : */
2104 2316 : all_satisfied = false;
2105 2316 : if (required)
2106 2094 : all_required_satisfied = false;
2107 : else
2108 : {
2109 : /*
2110 : * There's no need to advance the arrays using the best
2111 : * available match for a non-required array. Give up now.
2112 : * (Though note that sktrig_required calls still have to do
2113 : * all the usual post-advancement steps, including the recheck
2114 : * call to _bt_check_compare.)
2115 : */
2116 222 : break;
2117 : }
2118 : }
2119 :
2120 : /* Advance array keys, even when set_elem isn't an exact match */
2121 4644 : if (array && array->cur_elem != set_elem)
2122 : {
2123 3430 : array->cur_elem = set_elem;
2124 3430 : cur->sk_argument = array->elem_values[set_elem];
2125 : }
2126 : }
2127 :
2128 : /*
2129 : * Advance the array keys incrementally whenever "beyond end of array
2130 : * element" array advancement happens, so that advancement will carry to
2131 : * higher-order arrays (might exhaust all the scan's arrays instead, which
2132 : * ends the top-level scan).
2133 : */
2134 4334 : if (beyond_end_advance && !_bt_advance_array_keys_increment(scan, dir))
2135 890 : goto end_toplevel_scan;
2136 :
2137 : Assert(_bt_verify_keys_with_arraykeys(scan));
2138 :
2139 : /*
2140 : * Does tuple now satisfy our new qual? Recheck with _bt_check_compare.
2141 : *
2142 : * Calls triggered by an unsatisfied required scan key, whose tuple now
2143 : * satisfies all required scan keys, but not all nonrequired array keys,
2144 : * will still require a recheck call to _bt_check_compare. They'll still
2145 : * need its "second pass" handling of required inequality scan keys.
2146 : * (Might have missed a still-unsatisfied required inequality scan key
2147 : * that caller didn't detect as the sktrig scan key during its initial
2148 : * _bt_check_compare call that used the old/original qual.)
2149 : *
2150 : * Calls triggered by an unsatisfied nonrequired array scan key never need
2151 : * "second pass" handling of required inequalities (nor any other handling
2152 : * of any required scan key). All that matters is whether caller's tuple
2153 : * satisfies the new qual, so it's safe to just skip the _bt_check_compare
2154 : * recheck when we've already determined that it can only return 'false'.
2155 : */
2156 3444 : if ((sktrig_required && all_required_satisfied) ||
2157 1548 : (!sktrig_required && all_satisfied))
2158 : {
2159 1934 : int nsktrig = sktrig + 1;
2160 : bool continuescan;
2161 :
2162 : Assert(all_required_satisfied);
2163 :
2164 : /* Recheck _bt_check_compare on behalf of caller */
2165 1934 : if (_bt_check_compare(scan, dir, tuple, tupnatts, tupdesc,
2166 : false, false, false,
2167 1928 : &continuescan, &nsktrig) &&
2168 1928 : !so->scanBehind)
2169 : {
2170 : /* This tuple satisfies the new qual */
2171 : Assert(all_satisfied && continuescan);
2172 :
2173 1928 : if (pstate)
2174 1890 : pstate->continuescan = true;
2175 :
2176 1928 : return true;
2177 : }
2178 :
2179 : /*
2180 : * Consider "second pass" handling of required inequalities.
2181 : *
2182 : * It's possible that our _bt_check_compare call indicated that the
2183 : * scan should end due to some unsatisfied inequality that wasn't
2184 : * initially recognized as such by us. Handle this by calling
2185 : * ourselves recursively, this time indicating that the trigger is the
2186 : * inequality that we missed first time around (and using a set of
2187 : * required array/equality keys that are now exact matches for tuple).
2188 : *
2189 : * We make a strong, general guarantee that every _bt_checkkeys call
2190 : * here will advance the array keys to the maximum possible extent
2191 : * that we can know to be safe based on caller's tuple alone. If we
2192 : * didn't perform this step, then that guarantee wouldn't quite hold.
2193 : */
2194 6 : if (unlikely(!continuescan))
2195 : {
2196 : bool satisfied PG_USED_FOR_ASSERTS_ONLY;
2197 :
2198 : Assert(sktrig_required);
2199 : Assert(so->keyData[nsktrig].sk_strategy != BTEqualStrategyNumber);
2200 :
2201 : /*
2202 : * The tuple must use "beyond end" advancement during the
2203 : * recursive call, so we cannot possibly end up back here when
2204 : * recursing. We'll consume a small, fixed amount of stack space.
2205 : */
2206 : Assert(!beyond_end_advance);
2207 :
2208 : /* Advance the array keys a second time using same tuple */
2209 0 : satisfied = _bt_advance_array_keys(scan, pstate, tuple, tupnatts,
2210 : tupdesc, nsktrig, true);
2211 :
2212 : /* This tuple doesn't satisfy the inequality */
2213 : Assert(!satisfied);
2214 0 : return false;
2215 : }
2216 :
2217 : /*
2218 : * Some non-required scan key (from new qual) still not satisfied.
2219 : *
2220 : * All scan keys required in the current scan direction must still be
2221 : * satisfied, though, so we can trust all_required_satisfied below.
2222 : */
2223 : }
2224 :
2225 : /*
2226 : * When we were called just to deal with "advancing" non-required arrays,
2227 : * this is as far as we can go (cannot stop the scan for these callers)
2228 : */
2229 1516 : if (!sktrig_required)
2230 : {
2231 : /* Caller's tuple doesn't match any qual */
2232 222 : return false;
2233 : }
2234 :
2235 : /*
2236 : * Postcondition array state assertion (for still-unsatisfied tuples).
2237 : *
2238 : * By here we have established that the scan's required arrays (scan must
2239 : * have at least one required array) advanced, without becoming exhausted.
2240 : *
2241 : * Caller's tuple is now < the newly advanced array keys (or > when this
2242 : * is a backwards scan), except in the case where we only got this far due
2243 : * to an unsatisfied non-required scan key. Verify that with an assert.
2244 : *
2245 : * Note: we don't just quit at this point when all required scan keys were
2246 : * found to be satisfied because we need to consider edge-cases involving
2247 : * scan keys required in the opposite direction only; those aren't tracked
2248 : * by all_required_satisfied. (Actually, oppodir_inequality_sktrig trigger
2249 : * scan keys are tracked by all_required_satisfied, since it's convenient
2250 : * for _bt_check_compare to behave as if they are required in the current
2251 : * scan direction to deal with NULLs. We'll account for that separately.)
2252 : */
2253 : Assert(_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts,
2254 : false, 0, NULL) ==
2255 : !all_required_satisfied);
2256 :
2257 : /*
2258 : * We generally permit primitive index scans to continue onto the next
2259 : * sibling page when the page's finaltup satisfies all required scan keys
2260 : * at the point where we're between pages.
2261 : *
2262 : * If caller's tuple is also the page's finaltup, and we see that required
2263 : * scan keys still aren't satisfied, start a new primitive index scan.
2264 : */
2265 1294 : if (!all_required_satisfied && pstate->finaltup == tuple)
2266 0 : goto new_prim_scan;
2267 :
2268 : /*
2269 : * Proactively check finaltup (don't wait until finaltup is reached by the
2270 : * scan) when it might well turn out to not be satisfied later on.
2271 : *
2272 : * Note: if so->scanBehind hasn't already been set for finaltup by us,
2273 : * it'll be set during this call to _bt_tuple_before_array_skeys. Either
2274 : * way, it'll be set correctly (for the whole page) after this point.
2275 : */
2276 2448 : if (!all_required_satisfied && pstate->finaltup &&
2277 2308 : _bt_tuple_before_array_skeys(scan, dir, pstate->finaltup, tupdesc,
2278 2308 : BTreeTupleGetNAtts(pstate->finaltup, rel),
2279 : false, 0, &so->scanBehind))
2280 654 : goto new_prim_scan;
2281 :
2282 : /*
2283 : * When we encounter a truncated finaltup high key attribute, we're
2284 : * optimistic about the chances of its corresponding required scan key
2285 : * being satisfied when we go on to check it against tuples from this
2286 : * page's right sibling leaf page. We consider truncated attributes to be
2287 : * satisfied by required scan keys, which allows the primitive index scan
2288 : * to continue to the next leaf page. We must set so->scanBehind to true
2289 : * to remember that the last page's finaltup had "satisfied" required scan
2290 : * keys for one or more truncated attribute values (scan keys required in
2291 : * _either_ scan direction).
2292 : *
2293 : * There is a chance that _bt_checkkeys (which checks so->scanBehind) will
2294 : * find that even the sibling leaf page's finaltup is < the new array
2295 : * keys. When that happens, our optimistic policy will have incurred a
2296 : * single extra leaf page access that could have been avoided.
2297 : *
2298 : * A pessimistic policy would give backward scans a gratuitous advantage
2299 : * over forward scans. We'd punish forward scans for applying more
2300 : * accurate information from the high key, rather than just using the
2301 : * final non-pivot tuple as finaltup, in the style of backward scans.
2302 : * Being pessimistic would also give some scans with non-required arrays a
2303 : * perverse advantage over similar scans that use required arrays instead.
2304 : *
2305 : * You can think of this as a speculative bet on what the scan is likely
2306 : * to find on the next page. It's not much of a gamble, though, since the
2307 : * untruncated prefix of attributes must strictly satisfy the new qual
2308 : * (though it's okay if any non-required scan keys fail to be satisfied).
2309 : */
2310 640 : if (so->scanBehind && has_required_opposite_direction_only)
2311 : {
2312 : /*
2313 : * However, we need to work harder whenever the scan involves a scan
2314 : * key required in the opposite direction to the scan only, along with
2315 : * a finaltup with at least one truncated attribute that's associated
2316 : * with a scan key marked required (required in either direction).
2317 : *
2318 : * _bt_check_compare simply won't stop the scan for a scan key that's
2319 : * marked required in the opposite scan direction only. That leaves
2320 : * us without an automatic way of reconsidering any opposite-direction
2321 : * inequalities if it turns out that starting a new primitive index
2322 : * scan will allow _bt_first to skip ahead by a great many leaf pages.
2323 : *
2324 : * We deal with this by explicitly scheduling a finaltup recheck on
2325 : * the right sibling page. _bt_readpage calls _bt_oppodir_checkkeys
2326 : * for next page's finaltup (and we skip it for this page's finaltup).
2327 : */
2328 0 : so->oppositeDirCheck = true; /* recheck next page's high key */
2329 : }
2330 :
2331 : /*
2332 : * Handle inequalities marked required in the opposite scan direction.
2333 : * They can also signal that we should start a new primitive index scan.
2334 : *
2335 : * It's possible that the scan is now positioned where "matching" tuples
2336 : * begin, and that caller's tuple satisfies all scan keys required in the
2337 : * current scan direction. But if caller's tuple still doesn't satisfy
2338 : * other scan keys that are required in the opposite scan direction only
2339 : * (e.g., a required >= strategy scan key when scan direction is forward),
2340 : * it's still possible that there are many leaf pages before the page that
2341 : * _bt_first could skip straight to. Groveling through all those pages
2342 : * will always give correct answers, but it can be very inefficient. We
2343 : * must avoid needlessly scanning extra pages.
2344 : *
2345 : * Separately, it's possible that _bt_check_compare set continuescan=false
2346 : * for a scan key that's required in the opposite direction only. This is
2347 : * a special case, that happens only when _bt_check_compare sees that the
2348 : * inequality encountered a NULL value. This signals the end of non-NULL
2349 : * values in the current scan direction, which is reason enough to end the
2350 : * (primitive) scan. If this happens at the start of a large group of
2351 : * NULL values, then we shouldn't expect to be called again until after
2352 : * the scan has already read indefinitely-many leaf pages full of tuples
2353 : * with NULL suffix values. We need a separate test for this case so that
2354 : * we don't miss our only opportunity to skip over such a group of pages.
2355 : * (_bt_first is expected to skip over the group of NULLs by applying a
2356 : * similar "deduce NOT NULL" rule, where it finishes its insertion scan
2357 : * key by consing up an explicit SK_SEARCHNOTNULL key.)
2358 : *
2359 : * Apply a test against finaltup to detect and recover from the problem:
2360 : * if even finaltup doesn't satisfy such an inequality, we just skip by
2361 : * starting a new primitive index scan. When we skip, we know for sure
2362 : * that all of the tuples on the current page following caller's tuple are
2363 : * also before the _bt_first-wise start of tuples for our new qual. That
2364 : * at least suggests many more skippable pages beyond the current page.
2365 : * (when so->oppositeDirCheck was set, this'll happen on the next page.)
2366 : */
2367 640 : else if (has_required_opposite_direction_only && pstate->finaltup &&
2368 0 : (all_required_satisfied || oppodir_inequality_sktrig) &&
2369 0 : unlikely(!_bt_oppodir_checkkeys(scan, dir, pstate->finaltup)))
2370 : {
2371 : /*
2372 : * Make sure that any non-required arrays are set to the first array
2373 : * element for the current scan direction
2374 : */
2375 0 : _bt_rewind_nonrequired_arrays(scan, dir);
2376 0 : goto new_prim_scan;
2377 : }
2378 :
2379 : /*
2380 : * Stick with the ongoing primitive index scan for now.
2381 : *
2382 : * It's possible that later tuples will also turn out to have values that
2383 : * are still < the now-current array keys (or > the current array keys).
2384 : * Our caller will handle this by performing what amounts to a linear
2385 : * search of the page, implemented by calling _bt_check_compare and then
2386 : * _bt_tuple_before_array_skeys for each tuple.
2387 : *
2388 : * This approach has various advantages over a binary search of the page.
2389 : * Repeated binary searches of the page (one binary search for every array
2390 : * advancement) won't outperform a continuous linear search. While there
2391 : * are workloads that a naive linear search won't handle well, our caller
2392 : * has a "look ahead" fallback mechanism to deal with that problem.
2393 : */
2394 640 : pstate->continuescan = true; /* Override _bt_check_compare */
2395 640 : so->needPrimScan = false; /* _bt_readpage has more tuples to check */
2396 :
2397 640 : if (so->scanBehind)
2398 : {
2399 : /* Optimization: skip by setting "look ahead" mechanism's offnum */
2400 : Assert(ScanDirectionIsForward(dir));
2401 6 : pstate->skip = pstate->maxoff + 1;
2402 : }
2403 :
2404 : /* Caller's tuple doesn't match the new qual */
2405 640 : return false;
2406 :
2407 654 : new_prim_scan:
2408 :
2409 : Assert(pstate->finaltup); /* not on rightmost/leftmost page */
2410 :
2411 : /*
2412 : * End this primitive index scan, but schedule another.
2413 : *
2414 : * Note: We make a soft assumption that the current scan direction will
2415 : * also be used within _bt_next, when it is asked to step off this page.
2416 : * It is up to _bt_next to cancel this scheduled primitive index scan
2417 : * whenever it steps to a page in the direction opposite currPos.dir.
2418 : */
2419 654 : pstate->continuescan = false; /* Tell _bt_readpage we're done... */
2420 654 : so->needPrimScan = true; /* ...but call _bt_first again */
2421 :
2422 654 : if (scan->parallel_scan)
2423 36 : _bt_parallel_primscan_schedule(scan, so->currPos.currPage);
2424 :
2425 : /* Caller's tuple doesn't match the new qual */
2426 654 : return false;
2427 :
2428 890 : end_toplevel_scan:
2429 :
2430 : /*
2431 : * End the current primitive index scan, but don't schedule another.
2432 : *
2433 : * This ends the entire top-level scan in the current scan direction.
2434 : *
2435 : * Note: The scan's arrays (including any non-required arrays) are now in
2436 : * their final positions for the current scan direction. If the scan
2437 : * direction happens to change, then the arrays will already be in their
2438 : * first positions for what will then be the current scan direction.
2439 : */
2440 890 : pstate->continuescan = false; /* Tell _bt_readpage we're done... */
2441 890 : so->needPrimScan = false; /* ...don't call _bt_first again, though */
2442 :
2443 : /* Caller's tuple doesn't match any qual */
2444 890 : return false;
2445 : }
2446 :
2447 : /*
2448 : * _bt_preprocess_keys() -- Preprocess scan keys
2449 : *
2450 : * The given search-type keys (taken from scan->keyData[])
2451 : * are copied to so->keyData[] with possible transformation.
2452 : * scan->numberOfKeys is the number of input keys, so->numberOfKeys gets
2453 : * the number of output keys. Calling here a second or subsequent time
2454 : * (during the same btrescan) is a no-op.
2455 : *
2456 : * The output keys are marked with additional sk_flags bits beyond the
2457 : * system-standard bits supplied by the caller. The DESC and NULLS_FIRST
2458 : * indoption bits for the relevant index attribute are copied into the flags.
2459 : * Also, for a DESC column, we commute (flip) all the sk_strategy numbers
2460 : * so that the index sorts in the desired direction.
2461 : *
2462 : * One key purpose of this routine is to discover which scan keys must be
2463 : * satisfied to continue the scan. It also attempts to eliminate redundant
2464 : * keys and detect contradictory keys. (If the index opfamily provides
2465 : * incomplete sets of cross-type operators, we may fail to detect redundant
2466 : * or contradictory keys, but we can survive that.)
2467 : *
2468 : * The output keys must be sorted by index attribute. Presently we expect
2469 : * (but verify) that the input keys are already so sorted --- this is done
2470 : * by match_clauses_to_index() in indxpath.c. Some reordering of the keys
2471 : * within each attribute may be done as a byproduct of the processing here.
2472 : * That process must leave array scan keys (within an attribute) in the same
2473 : * order as corresponding entries from the scan's BTArrayKeyInfo array info.
2474 : *
2475 : * The output keys are marked with flags SK_BT_REQFWD and/or SK_BT_REQBKWD
2476 : * if they must be satisfied in order to continue the scan forward or backward
2477 : * respectively. _bt_checkkeys uses these flags. For example, if the quals
2478 : * are "x = 1 AND y < 4 AND z < 5", then _bt_checkkeys will reject a tuple
2479 : * (1,2,7), but we must continue the scan in case there are tuples (1,3,z).
2480 : * But once we reach tuples like (1,4,z) we can stop scanning because no
2481 : * later tuples could match. This is reflected by marking the x and y keys,
2482 : * but not the z key, with SK_BT_REQFWD. In general, the keys for leading
2483 : * attributes with "=" keys are marked both SK_BT_REQFWD and SK_BT_REQBKWD.
2484 : * For the first attribute without an "=" key, any "<" and "<=" keys are
2485 : * marked SK_BT_REQFWD while any ">" and ">=" keys are marked SK_BT_REQBKWD.
2486 : * This can be seen to be correct by considering the above example. Note
2487 : * in particular that if there are no keys for a given attribute, the keys for
2488 : * subsequent attributes can never be required; for instance "WHERE y = 4"
2489 : * requires a full-index scan.
2490 : *
2491 : * If possible, redundant keys are eliminated: we keep only the tightest
2492 : * >/>= bound and the tightest </<= bound, and if there's an = key then
2493 : * that's the only one returned. (So, we return either a single = key,
2494 : * or one or two boundary-condition keys for each attr.) However, if we
2495 : * cannot compare two keys for lack of a suitable cross-type operator,
2496 : * we cannot eliminate either. If there are two such keys of the same
2497 : * operator strategy, the second one is just pushed into the output array
2498 : * without further processing here. We may also emit both >/>= or both
2499 : * </<= keys if we can't compare them. The logic about required keys still
2500 : * works if we don't eliminate redundant keys.
2501 : *
2502 : * Note that one reason we need direction-sensitive required-key flags is
2503 : * precisely that we may not be able to eliminate redundant keys. Suppose
2504 : * we have "x > 4::int AND x > 10::bigint", and we are unable to determine
2505 : * which key is more restrictive for lack of a suitable cross-type operator.
2506 : * _bt_first will arbitrarily pick one of the keys to do the initial
2507 : * positioning with. If it picks x > 4, then the x > 10 condition will fail
2508 : * until we reach index entries > 10; but we can't stop the scan just because
2509 : * x > 10 is failing. On the other hand, if we are scanning backwards, then
2510 : * failure of either key is indeed enough to stop the scan. (In general, when
2511 : * inequality keys are present, the initial-positioning code only promises to
2512 : * position before the first possible match, not exactly at the first match,
2513 : * for a forward scan; or after the last match for a backward scan.)
2514 : *
2515 : * As a byproduct of this work, we can detect contradictory quals such
2516 : * as "x = 1 AND x > 2". If we see that, we return so->qual_ok = false,
2517 : * indicating the scan need not be run at all since no tuples can match.
2518 : * (In this case we do not bother completing the output key array!)
2519 : * Again, missing cross-type operators might cause us to fail to prove the
2520 : * quals contradictory when they really are, but the scan will work correctly.
2521 : *
2522 : * Row comparison keys are currently also treated without any smarts:
2523 : * we just transfer them into the preprocessed array without any
2524 : * editorialization. We can treat them the same as an ordinary inequality
2525 : * comparison on the row's first index column, for the purposes of the logic
2526 : * about required keys.
2527 : *
2528 : * Note: the reason we have to copy the preprocessed scan keys into private
2529 : * storage is that we are modifying the array based on comparisons of the
2530 : * key argument values, which could change on a rescan. Therefore we can't
2531 : * overwrite the source data.
2532 : */
2533 : void
2534 13024964 : _bt_preprocess_keys(IndexScanDesc scan)
2535 : {
2536 13024964 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2537 13024964 : int numberOfKeys = scan->numberOfKeys;
2538 13024964 : int16 *indoption = scan->indexRelation->rd_indoption;
2539 : int new_numberOfKeys;
2540 : int numberOfEqualCols;
2541 : ScanKey inkeys;
2542 : BTScanKeyPreproc xform[BTMaxStrategyNumber];
2543 : bool test_result;
2544 : AttrNumber attno;
2545 : ScanKey arrayKeyData;
2546 13024964 : int *keyDataMap = NULL;
2547 13024964 : int arrayidx = 0;
2548 :
2549 13024964 : if (so->numberOfKeys > 0)
2550 : {
2551 : /*
2552 : * Only need to do preprocessing once per btrescan, at most. All
2553 : * calls after the first are handled as no-ops.
2554 : *
2555 : * If there are array scan keys in so->keyData[], then the now-current
2556 : * array elements must already be present in each array's scan key.
2557 : * Verify that that happened using an assertion.
2558 : */
2559 : Assert(_bt_verify_keys_with_arraykeys(scan));
2560 6596676 : return;
2561 : }
2562 :
2563 : /* initialize result variables */
2564 13024310 : so->qual_ok = true;
2565 13024310 : so->numberOfKeys = 0;
2566 :
2567 13024310 : if (numberOfKeys < 1)
2568 12286 : return; /* done if qual-less scan */
2569 :
2570 : /* If any keys are SK_SEARCHARRAY type, set up array-key info */
2571 13012024 : arrayKeyData = _bt_preprocess_array_keys(scan, &numberOfKeys);
2572 13012024 : if (!so->qual_ok)
2573 : {
2574 : /* unmatchable array, so give up */
2575 6 : return;
2576 : }
2577 :
2578 : /*
2579 : * Treat arrayKeyData[] (a partially preprocessed copy of scan->keyData[])
2580 : * as our input if _bt_preprocess_array_keys just allocated it, else just
2581 : * use scan->keyData[]
2582 : */
2583 13012018 : if (arrayKeyData)
2584 : {
2585 1096 : inkeys = arrayKeyData;
2586 :
2587 : /* Also maintain keyDataMap for remapping so->orderProc[] later */
2588 1096 : keyDataMap = MemoryContextAlloc(so->arrayContext,
2589 : numberOfKeys * sizeof(int));
2590 : }
2591 : else
2592 13010922 : inkeys = scan->keyData;
2593 :
2594 : /* we check that input keys are correctly ordered */
2595 13012018 : if (inkeys[0].sk_attno < 1)
2596 0 : elog(ERROR, "btree index keys must be ordered by attribute");
2597 :
2598 : /* We can short-circuit most of the work if there's just one key */
2599 13012018 : if (numberOfKeys == 1)
2600 : {
2601 : /* Apply indoption to scankey (might change sk_strategy!) */
2602 6583670 : if (!_bt_fix_scankey_strategy(&inkeys[0], indoption))
2603 972 : so->qual_ok = false;
2604 6583670 : memcpy(&so->keyData[0], &inkeys[0], sizeof(ScanKeyData));
2605 6583670 : so->numberOfKeys = 1;
2606 : /* We can mark the qual as required if it's for first index col */
2607 6583670 : if (inkeys[0].sk_attno == 1)
2608 6580958 : _bt_mark_scankey_required(&so->keyData[0]);
2609 : if (arrayKeyData)
2610 : {
2611 : /*
2612 : * Don't call _bt_preprocess_array_keys_final in this fast path
2613 : * (we'll miss out on the single value array transformation, but
2614 : * that's not nearly as important when there's only one scan key)
2615 : */
2616 : Assert(so->keyData[0].sk_flags & SK_SEARCHARRAY);
2617 : Assert(so->keyData[0].sk_strategy != BTEqualStrategyNumber ||
2618 : (so->arrayKeys[0].scan_key == 0 &&
2619 : OidIsValid(so->orderProcs[0].fn_oid)));
2620 : }
2621 :
2622 6583670 : return;
2623 : }
2624 :
2625 : /*
2626 : * Otherwise, do the full set of pushups.
2627 : */
2628 6428348 : new_numberOfKeys = 0;
2629 6428348 : numberOfEqualCols = 0;
2630 :
2631 : /*
2632 : * Initialize for processing of keys for attr 1.
2633 : *
2634 : * xform[i] points to the currently best scan key of strategy type i+1; it
2635 : * is NULL if we haven't yet found such a key for this attr.
2636 : */
2637 6428348 : attno = 1;
2638 6428348 : memset(xform, 0, sizeof(xform));
2639 :
2640 : /*
2641 : * Loop iterates from 0 to numberOfKeys inclusive; we use the last pass to
2642 : * handle after-last-key processing. Actual exit from the loop is at the
2643 : * "break" statement below.
2644 : */
2645 6428348 : for (int i = 0;; i++)
2646 14175092 : {
2647 20603440 : ScanKey inkey = inkeys + i;
2648 : int j;
2649 :
2650 20603440 : if (i < numberOfKeys)
2651 : {
2652 : /* Apply indoption to scankey (might change sk_strategy!) */
2653 14175116 : if (!_bt_fix_scankey_strategy(inkey, indoption))
2654 : {
2655 : /* NULL can't be matched, so give up */
2656 18 : so->qual_ok = false;
2657 18 : return;
2658 : }
2659 : }
2660 :
2661 : /*
2662 : * If we are at the end of the keys for a particular attr, finish up
2663 : * processing and emit the cleaned-up keys.
2664 : */
2665 20603422 : if (i == numberOfKeys || inkey->sk_attno != attno)
2666 : {
2667 14172962 : int priorNumberOfEqualCols = numberOfEqualCols;
2668 :
2669 : /* check input keys are correctly ordered */
2670 14172962 : if (i < numberOfKeys && inkey->sk_attno < attno)
2671 0 : elog(ERROR, "btree index keys must be ordered by attribute");
2672 :
2673 : /*
2674 : * If = has been specified, all other keys can be eliminated as
2675 : * redundant. Note that this is no less true if the = key is
2676 : * SEARCHARRAY; the only real difference is that the inequality
2677 : * key _becomes_ redundant by making _bt_compare_scankey_args
2678 : * eliminate the subset of elements that won't need to be matched.
2679 : *
2680 : * If we have a case like "key = 1 AND key > 2", we set qual_ok to
2681 : * false and abandon further processing. We'll do the same thing
2682 : * given a case like "key IN (0, 1) AND key > 2".
2683 : *
2684 : * We also have to deal with the case of "key IS NULL", which is
2685 : * unsatisfiable in combination with any other index condition. By
2686 : * the time we get here, that's been classified as an equality
2687 : * check, and we've rejected any combination of it with a regular
2688 : * equality condition; but not with other types of conditions.
2689 : */
2690 14172962 : if (xform[BTEqualStrategyNumber - 1].inkey)
2691 : {
2692 12862108 : ScanKey eq = xform[BTEqualStrategyNumber - 1].inkey;
2693 12862108 : BTArrayKeyInfo *array = NULL;
2694 12862108 : FmgrInfo *orderproc = NULL;
2695 :
2696 12862108 : if (arrayKeyData && (eq->sk_flags & SK_SEARCHARRAY))
2697 : {
2698 : int eq_in_ikey,
2699 : eq_arrayidx;
2700 :
2701 752 : eq_in_ikey = xform[BTEqualStrategyNumber - 1].inkeyi;
2702 752 : eq_arrayidx = xform[BTEqualStrategyNumber - 1].arrayidx;
2703 752 : array = &so->arrayKeys[eq_arrayidx - 1];
2704 752 : orderproc = so->orderProcs + eq_in_ikey;
2705 :
2706 : Assert(array->scan_key == eq_in_ikey);
2707 : Assert(OidIsValid(orderproc->fn_oid));
2708 : }
2709 :
2710 77172492 : for (j = BTMaxStrategyNumber; --j >= 0;)
2711 : {
2712 64310420 : ScanKey chk = xform[j].inkey;
2713 :
2714 64310420 : if (!chk || j == (BTEqualStrategyNumber - 1))
2715 64310190 : continue;
2716 :
2717 230 : if (eq->sk_flags & SK_SEARCHNULL)
2718 : {
2719 : /* IS NULL is contradictory to anything else */
2720 24 : so->qual_ok = false;
2721 24 : return;
2722 : }
2723 :
2724 206 : if (_bt_compare_scankey_args(scan, chk, eq, chk,
2725 : array, orderproc,
2726 : &test_result))
2727 : {
2728 206 : if (!test_result)
2729 : {
2730 : /* keys proven mutually contradictory */
2731 12 : so->qual_ok = false;
2732 12 : return;
2733 : }
2734 : /* else discard the redundant non-equality key */
2735 : Assert(!array || array->num_elems > 0);
2736 194 : xform[j].inkey = NULL;
2737 194 : xform[j].inkeyi = -1;
2738 : }
2739 : /* else, cannot determine redundancy, keep both keys */
2740 : }
2741 : /* track number of attrs for which we have "=" keys */
2742 12862072 : numberOfEqualCols++;
2743 : }
2744 :
2745 : /* try to keep only one of <, <= */
2746 14172926 : if (xform[BTLessStrategyNumber - 1].inkey &&
2747 1984 : xform[BTLessEqualStrategyNumber - 1].inkey)
2748 : {
2749 6 : ScanKey lt = xform[BTLessStrategyNumber - 1].inkey;
2750 6 : ScanKey le = xform[BTLessEqualStrategyNumber - 1].inkey;
2751 :
2752 6 : if (_bt_compare_scankey_args(scan, le, lt, le, NULL, NULL,
2753 : &test_result))
2754 : {
2755 6 : if (test_result)
2756 6 : xform[BTLessEqualStrategyNumber - 1].inkey = NULL;
2757 : else
2758 0 : xform[BTLessStrategyNumber - 1].inkey = NULL;
2759 : }
2760 : }
2761 :
2762 : /* try to keep only one of >, >= */
2763 14172926 : if (xform[BTGreaterStrategyNumber - 1].inkey &&
2764 1306486 : xform[BTGreaterEqualStrategyNumber - 1].inkey)
2765 : {
2766 6 : ScanKey gt = xform[BTGreaterStrategyNumber - 1].inkey;
2767 6 : ScanKey ge = xform[BTGreaterEqualStrategyNumber - 1].inkey;
2768 :
2769 6 : if (_bt_compare_scankey_args(scan, ge, gt, ge, NULL, NULL,
2770 : &test_result))
2771 : {
2772 6 : if (test_result)
2773 0 : xform[BTGreaterEqualStrategyNumber - 1].inkey = NULL;
2774 : else
2775 6 : xform[BTGreaterStrategyNumber - 1].inkey = NULL;
2776 : }
2777 : }
2778 :
2779 : /*
2780 : * Emit the cleaned-up keys into the so->keyData[] array, and then
2781 : * mark them if they are required. They are required (possibly
2782 : * only in one direction) if all attrs before this one had "=".
2783 : */
2784 85037556 : for (j = BTMaxStrategyNumber; --j >= 0;)
2785 : {
2786 70864630 : if (xform[j].inkey)
2787 : {
2788 14174748 : ScanKey outkey = &so->keyData[new_numberOfKeys++];
2789 :
2790 14174748 : memcpy(outkey, xform[j].inkey, sizeof(ScanKeyData));
2791 14174748 : if (arrayKeyData)
2792 1180 : keyDataMap[new_numberOfKeys - 1] = xform[j].inkeyi;
2793 14174748 : if (priorNumberOfEqualCols == attno - 1)
2794 14173884 : _bt_mark_scankey_required(outkey);
2795 : }
2796 : }
2797 :
2798 : /*
2799 : * Exit loop here if done.
2800 : */
2801 14172926 : if (i == numberOfKeys)
2802 6428288 : break;
2803 :
2804 : /* Re-initialize for new attno */
2805 7744638 : attno = inkey->sk_attno;
2806 7744638 : memset(xform, 0, sizeof(xform));
2807 : }
2808 :
2809 : /* check strategy this key's operator corresponds to */
2810 14175098 : j = inkey->sk_strategy - 1;
2811 :
2812 : /* if row comparison, push it directly to the output array */
2813 14175098 : if (inkey->sk_flags & SK_ROW_HEADER)
2814 : {
2815 0 : ScanKey outkey = &so->keyData[new_numberOfKeys++];
2816 :
2817 0 : memcpy(outkey, inkey, sizeof(ScanKeyData));
2818 0 : if (arrayKeyData)
2819 0 : keyDataMap[new_numberOfKeys - 1] = i;
2820 0 : if (numberOfEqualCols == attno - 1)
2821 0 : _bt_mark_scankey_required(outkey);
2822 :
2823 : /*
2824 : * We don't support RowCompare using equality; such a qual would
2825 : * mess up the numberOfEqualCols tracking.
2826 : */
2827 : Assert(j != (BTEqualStrategyNumber - 1));
2828 0 : continue;
2829 : }
2830 :
2831 14175098 : if (inkey->sk_strategy == BTEqualStrategyNumber &&
2832 12862150 : (inkey->sk_flags & SK_SEARCHARRAY))
2833 : {
2834 : /* must track how input scan keys map to arrays */
2835 : Assert(arrayKeyData);
2836 758 : arrayidx++;
2837 : }
2838 :
2839 : /*
2840 : * have we seen a scan key for this same attribute and using this same
2841 : * operator strategy before now?
2842 : */
2843 14175098 : if (xform[j].inkey == NULL)
2844 : {
2845 : /* nope, so this scan key wins by default (at least for now) */
2846 14175050 : xform[j].inkey = inkey;
2847 14175050 : xform[j].inkeyi = i;
2848 14175050 : xform[j].arrayidx = arrayidx;
2849 : }
2850 : else
2851 : {
2852 48 : FmgrInfo *orderproc = NULL;
2853 48 : BTArrayKeyInfo *array = NULL;
2854 :
2855 : /*
2856 : * Seen one of these before, so keep only the more restrictive key
2857 : * if possible
2858 : */
2859 48 : if (j == (BTEqualStrategyNumber - 1) && arrayKeyData)
2860 : {
2861 : /*
2862 : * Have to set up array keys
2863 : */
2864 12 : if (inkey->sk_flags & SK_SEARCHARRAY)
2865 : {
2866 0 : array = &so->arrayKeys[arrayidx - 1];
2867 0 : orderproc = so->orderProcs + i;
2868 :
2869 : Assert(array->scan_key == i);
2870 : Assert(OidIsValid(orderproc->fn_oid));
2871 : }
2872 12 : else if (xform[j].inkey->sk_flags & SK_SEARCHARRAY)
2873 : {
2874 12 : array = &so->arrayKeys[xform[j].arrayidx - 1];
2875 12 : orderproc = so->orderProcs + xform[j].inkeyi;
2876 :
2877 : Assert(array->scan_key == xform[j].inkeyi);
2878 : Assert(OidIsValid(orderproc->fn_oid));
2879 : }
2880 :
2881 : /*
2882 : * Both scan keys might have arrays, in which case we'll
2883 : * arbitrarily pass only one of the arrays. That won't
2884 : * matter, since _bt_compare_scankey_args is aware that two
2885 : * SEARCHARRAY scan keys mean that _bt_preprocess_array_keys
2886 : * failed to eliminate redundant arrays through array merging.
2887 : * _bt_compare_scankey_args just returns false when it sees
2888 : * this; it won't even try to examine either array.
2889 : */
2890 : }
2891 :
2892 48 : if (_bt_compare_scankey_args(scan, inkey, inkey, xform[j].inkey,
2893 : array, orderproc, &test_result))
2894 : {
2895 : /* Have all we need to determine redundancy */
2896 48 : if (test_result)
2897 : {
2898 : Assert(!array || array->num_elems > 0);
2899 :
2900 : /*
2901 : * New key is more restrictive, and so replaces old key...
2902 : */
2903 42 : if (j != (BTEqualStrategyNumber - 1) ||
2904 12 : !(xform[j].inkey->sk_flags & SK_SEARCHARRAY))
2905 : {
2906 36 : xform[j].inkey = inkey;
2907 36 : xform[j].inkeyi = i;
2908 36 : xform[j].arrayidx = arrayidx;
2909 : }
2910 : else
2911 : {
2912 : /*
2913 : * ...unless we have to keep the old key because it's
2914 : * an array that rendered the new key redundant. We
2915 : * need to make sure that we don't throw away an array
2916 : * scan key. _bt_preprocess_array_keys_final expects
2917 : * us to keep all of the arrays that weren't already
2918 : * eliminated by _bt_preprocess_array_keys earlier on.
2919 : */
2920 : Assert(!(inkey->sk_flags & SK_SEARCHARRAY));
2921 : }
2922 : }
2923 6 : else if (j == (BTEqualStrategyNumber - 1))
2924 : {
2925 : /* key == a && key == b, but a != b */
2926 6 : so->qual_ok = false;
2927 6 : return;
2928 : }
2929 : /* else old key is more restrictive, keep it */
2930 : }
2931 : else
2932 : {
2933 : /*
2934 : * We can't determine which key is more restrictive. Push
2935 : * xform[j] directly to the output array, then set xform[j] to
2936 : * the new scan key.
2937 : *
2938 : * Note: We do things this way around so that our arrays are
2939 : * always in the same order as their corresponding scan keys,
2940 : * even with incomplete opfamilies. _bt_advance_array_keys
2941 : * depends on this.
2942 : */
2943 0 : ScanKey outkey = &so->keyData[new_numberOfKeys++];
2944 :
2945 0 : memcpy(outkey, xform[j].inkey, sizeof(ScanKeyData));
2946 0 : if (arrayKeyData)
2947 0 : keyDataMap[new_numberOfKeys - 1] = xform[j].inkeyi;
2948 0 : if (numberOfEqualCols == attno - 1)
2949 0 : _bt_mark_scankey_required(outkey);
2950 0 : xform[j].inkey = inkey;
2951 0 : xform[j].inkeyi = i;
2952 0 : xform[j].arrayidx = arrayidx;
2953 : }
2954 : }
2955 : }
2956 :
2957 6428288 : so->numberOfKeys = new_numberOfKeys;
2958 :
2959 : /*
2960 : * Now that we've built a temporary mapping from so->keyData[] (output
2961 : * scan keys) to arrayKeyData[] (our input scan keys), fix array->scan_key
2962 : * references. Also consolidate the so->orderProcs[] array such that it
2963 : * can be subscripted using so->keyData[]-wise offsets.
2964 : */
2965 6428288 : if (arrayKeyData)
2966 578 : _bt_preprocess_array_keys_final(scan, keyDataMap);
2967 :
2968 : /* Could pfree arrayKeyData/keyDataMap now, but not worth the cycles */
2969 : }
2970 :
2971 : #ifdef USE_ASSERT_CHECKING
2972 : /*
2973 : * Verify that the scan's qual state matches what we expect at the point that
2974 : * _bt_start_prim_scan is about to start a just-scheduled new primitive scan.
2975 : *
2976 : * We enforce a rule against non-required array scan keys: they must start out
2977 : * with whatever element is the first for the scan's current scan direction.
2978 : * See _bt_rewind_nonrequired_arrays comments for an explanation.
2979 : */
2980 : static bool
2981 : _bt_verify_arrays_bt_first(IndexScanDesc scan, ScanDirection dir)
2982 : {
2983 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2984 : int arrayidx = 0;
2985 :
2986 : for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
2987 : {
2988 : ScanKey cur = so->keyData + ikey;
2989 : BTArrayKeyInfo *array = NULL;
2990 : int first_elem_dir;
2991 :
2992 : if (!(cur->sk_flags & SK_SEARCHARRAY) ||
2993 : cur->sk_strategy != BTEqualStrategyNumber)
2994 : continue;
2995 :
2996 : array = &so->arrayKeys[arrayidx++];
2997 :
2998 : if (((cur->sk_flags & SK_BT_REQFWD) && ScanDirectionIsForward(dir)) ||
2999 : ((cur->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsBackward(dir)))
3000 : continue;
3001 :
3002 : if (ScanDirectionIsForward(dir))
3003 : first_elem_dir = 0;
3004 : else
3005 : first_elem_dir = array->num_elems - 1;
3006 :
3007 : if (array->cur_elem != first_elem_dir)
3008 : return false;
3009 : }
3010 :
3011 : return _bt_verify_keys_with_arraykeys(scan);
3012 : }
3013 :
3014 : /*
3015 : * Verify that the scan's "so->keyData[]" scan keys are in agreement with
3016 : * its array key state
3017 : */
3018 : static bool
3019 : _bt_verify_keys_with_arraykeys(IndexScanDesc scan)
3020 : {
3021 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
3022 : int last_sk_attno = InvalidAttrNumber,
3023 : arrayidx = 0;
3024 :
3025 : if (!so->qual_ok)
3026 : return false;
3027 :
3028 : for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
3029 : {
3030 : ScanKey cur = so->keyData + ikey;
3031 : BTArrayKeyInfo *array;
3032 :
3033 : if (cur->sk_strategy != BTEqualStrategyNumber ||
3034 : !(cur->sk_flags & SK_SEARCHARRAY))
3035 : continue;
3036 :
3037 : array = &so->arrayKeys[arrayidx++];
3038 : if (array->scan_key != ikey)
3039 : return false;
3040 :
3041 : if (array->num_elems <= 0)
3042 : return false;
3043 :
3044 : if (cur->sk_argument != array->elem_values[array->cur_elem])
3045 : return false;
3046 : if (last_sk_attno > cur->sk_attno)
3047 : return false;
3048 : last_sk_attno = cur->sk_attno;
3049 : }
3050 :
3051 : if (arrayidx != so->numArrayKeys)
3052 : return false;
3053 :
3054 : return true;
3055 : }
3056 : #endif
3057 :
3058 : /*
3059 : * Compare two scankey values using a specified operator.
3060 : *
3061 : * The test we want to perform is logically "leftarg op rightarg", where
3062 : * leftarg and rightarg are the sk_argument values in those ScanKeys, and
3063 : * the comparison operator is the one in the op ScanKey. However, in
3064 : * cross-data-type situations we may need to look up the correct operator in
3065 : * the index's opfamily: it is the one having amopstrategy = op->sk_strategy
3066 : * and amoplefttype/amoprighttype equal to the two argument datatypes.
3067 : *
3068 : * If the opfamily doesn't supply a complete set of cross-type operators we
3069 : * may not be able to make the comparison. If we can make the comparison
3070 : * we store the operator result in *result and return true. We return false
3071 : * if the comparison could not be made.
3072 : *
3073 : * If either leftarg or rightarg are an array, we'll apply array-specific
3074 : * rules to determine which array elements are redundant on behalf of caller.
3075 : * It is up to our caller to save whichever of the two scan keys is the array,
3076 : * and discard the non-array scan key (the non-array scan key is guaranteed to
3077 : * be redundant with any complete opfamily). Caller isn't expected to call
3078 : * here with a pair of array scan keys provided we're dealing with a complete
3079 : * opfamily (_bt_preprocess_array_keys will merge array keys together to make
3080 : * sure of that).
3081 : *
3082 : * Note: we'll also shrink caller's array as needed to eliminate redundant
3083 : * array elements. One reason why caller should prefer to discard non-array
3084 : * scan keys is so that we'll have the opportunity to shrink the array
3085 : * multiple times, in multiple calls (for each of several other scan keys on
3086 : * the same index attribute).
3087 : *
3088 : * Note: op always points at the same ScanKey as either leftarg or rightarg.
3089 : * Since we don't scribble on the scankeys themselves, this aliasing should
3090 : * cause no trouble.
3091 : *
3092 : * Note: this routine needs to be insensitive to any DESC option applied
3093 : * to the index column. For example, "x < 4" is a tighter constraint than
3094 : * "x < 5" regardless of which way the index is sorted.
3095 : */
3096 : static bool
3097 266 : _bt_compare_scankey_args(IndexScanDesc scan, ScanKey op,
3098 : ScanKey leftarg, ScanKey rightarg,
3099 : BTArrayKeyInfo *array, FmgrInfo *orderproc,
3100 : bool *result)
3101 : {
3102 266 : Relation rel = scan->indexRelation;
3103 : Oid lefttype,
3104 : righttype,
3105 : optype,
3106 : opcintype,
3107 : cmp_op;
3108 : StrategyNumber strat;
3109 :
3110 : /*
3111 : * First, deal with cases where one or both args are NULL. This should
3112 : * only happen when the scankeys represent IS NULL/NOT NULL conditions.
3113 : */
3114 266 : if ((leftarg->sk_flags | rightarg->sk_flags) & SK_ISNULL)
3115 : {
3116 : bool leftnull,
3117 : rightnull;
3118 :
3119 132 : if (leftarg->sk_flags & SK_ISNULL)
3120 : {
3121 : Assert(leftarg->sk_flags & (SK_SEARCHNULL | SK_SEARCHNOTNULL));
3122 0 : leftnull = true;
3123 : }
3124 : else
3125 132 : leftnull = false;
3126 132 : if (rightarg->sk_flags & SK_ISNULL)
3127 : {
3128 : Assert(rightarg->sk_flags & (SK_SEARCHNULL | SK_SEARCHNOTNULL));
3129 132 : rightnull = true;
3130 : }
3131 : else
3132 0 : rightnull = false;
3133 :
3134 : /*
3135 : * We treat NULL as either greater than or less than all other values.
3136 : * Since true > false, the tests below work correctly for NULLS LAST
3137 : * logic. If the index is NULLS FIRST, we need to flip the strategy.
3138 : */
3139 132 : strat = op->sk_strategy;
3140 132 : if (op->sk_flags & SK_BT_NULLS_FIRST)
3141 0 : strat = BTCommuteStrategyNumber(strat);
3142 :
3143 132 : switch (strat)
3144 : {
3145 132 : case BTLessStrategyNumber:
3146 132 : *result = (leftnull < rightnull);
3147 132 : break;
3148 0 : case BTLessEqualStrategyNumber:
3149 0 : *result = (leftnull <= rightnull);
3150 0 : break;
3151 0 : case BTEqualStrategyNumber:
3152 0 : *result = (leftnull == rightnull);
3153 0 : break;
3154 0 : case BTGreaterEqualStrategyNumber:
3155 0 : *result = (leftnull >= rightnull);
3156 0 : break;
3157 0 : case BTGreaterStrategyNumber:
3158 0 : *result = (leftnull > rightnull);
3159 0 : break;
3160 0 : default:
3161 0 : elog(ERROR, "unrecognized StrategyNumber: %d", (int) strat);
3162 : *result = false; /* keep compiler quiet */
3163 : break;
3164 : }
3165 132 : return true;
3166 : }
3167 :
3168 : /*
3169 : * If either leftarg or rightarg are equality-type array scankeys, we need
3170 : * specialized handling (since by now we know that IS NULL wasn't used)
3171 : */
3172 134 : if (array)
3173 : {
3174 : bool leftarray,
3175 : rightarray;
3176 :
3177 48 : leftarray = ((leftarg->sk_flags & SK_SEARCHARRAY) &&
3178 18 : leftarg->sk_strategy == BTEqualStrategyNumber);
3179 42 : rightarray = ((rightarg->sk_flags & SK_SEARCHARRAY) &&
3180 12 : rightarg->sk_strategy == BTEqualStrategyNumber);
3181 :
3182 : /*
3183 : * _bt_preprocess_array_keys is responsible for merging together array
3184 : * scan keys, and will do so whenever the opfamily has the required
3185 : * cross-type support. If it failed to do that, we handle it just
3186 : * like the case where we can't make the comparison ourselves.
3187 : */
3188 30 : if (leftarray && rightarray)
3189 : {
3190 : /* Can't make the comparison */
3191 0 : *result = false; /* suppress compiler warnings */
3192 0 : return false;
3193 : }
3194 :
3195 : /*
3196 : * Otherwise we need to determine if either one of leftarg or rightarg
3197 : * uses an array, then pass this through to a dedicated helper
3198 : * function.
3199 : */
3200 30 : if (leftarray)
3201 18 : return _bt_compare_array_scankey_args(scan, leftarg, rightarg,
3202 : orderproc, array, result);
3203 12 : else if (rightarray)
3204 12 : return _bt_compare_array_scankey_args(scan, rightarg, leftarg,
3205 : orderproc, array, result);
3206 :
3207 : /* FALL THRU */
3208 : }
3209 :
3210 : /*
3211 : * The opfamily we need to worry about is identified by the index column.
3212 : */
3213 : Assert(leftarg->sk_attno == rightarg->sk_attno);
3214 :
3215 104 : opcintype = rel->rd_opcintype[leftarg->sk_attno - 1];
3216 :
3217 : /*
3218 : * Determine the actual datatypes of the ScanKey arguments. We have to
3219 : * support the convention that sk_subtype == InvalidOid means the opclass
3220 : * input type; this is a hack to simplify life for ScanKeyInit().
3221 : */
3222 104 : lefttype = leftarg->sk_subtype;
3223 104 : if (lefttype == InvalidOid)
3224 0 : lefttype = opcintype;
3225 104 : righttype = rightarg->sk_subtype;
3226 104 : if (righttype == InvalidOid)
3227 0 : righttype = opcintype;
3228 104 : optype = op->sk_subtype;
3229 104 : if (optype == InvalidOid)
3230 0 : optype = opcintype;
3231 :
3232 : /*
3233 : * If leftarg and rightarg match the types expected for the "op" scankey,
3234 : * we can use its already-looked-up comparison function.
3235 : */
3236 104 : if (lefttype == opcintype && righttype == optype)
3237 : {
3238 98 : *result = DatumGetBool(FunctionCall2Coll(&op->sk_func,
3239 : op->sk_collation,
3240 : leftarg->sk_argument,
3241 : rightarg->sk_argument));
3242 98 : return true;
3243 : }
3244 :
3245 : /*
3246 : * Otherwise, we need to go to the syscache to find the appropriate
3247 : * operator. (This cannot result in infinite recursion, since no
3248 : * indexscan initiated by syscache lookup will use cross-data-type
3249 : * operators.)
3250 : *
3251 : * If the sk_strategy was flipped by _bt_fix_scankey_strategy, we have to
3252 : * un-flip it to get the correct opfamily member.
3253 : */
3254 6 : strat = op->sk_strategy;
3255 6 : if (op->sk_flags & SK_BT_DESC)
3256 0 : strat = BTCommuteStrategyNumber(strat);
3257 :
3258 6 : cmp_op = get_opfamily_member(rel->rd_opfamily[leftarg->sk_attno - 1],
3259 : lefttype,
3260 : righttype,
3261 : strat);
3262 6 : if (OidIsValid(cmp_op))
3263 : {
3264 6 : RegProcedure cmp_proc = get_opcode(cmp_op);
3265 :
3266 6 : if (RegProcedureIsValid(cmp_proc))
3267 : {
3268 6 : *result = DatumGetBool(OidFunctionCall2Coll(cmp_proc,
3269 : op->sk_collation,
3270 : leftarg->sk_argument,
3271 : rightarg->sk_argument));
3272 6 : return true;
3273 : }
3274 : }
3275 :
3276 : /* Can't make the comparison */
3277 0 : *result = false; /* suppress compiler warnings */
3278 0 : return false;
3279 : }
3280 :
3281 : /*
3282 : * Adjust a scankey's strategy and flags setting as needed for indoptions.
3283 : *
3284 : * We copy the appropriate indoption value into the scankey sk_flags
3285 : * (shifting to avoid clobbering system-defined flag bits). Also, if
3286 : * the DESC option is set, commute (flip) the operator strategy number.
3287 : *
3288 : * A secondary purpose is to check for IS NULL/NOT NULL scankeys and set up
3289 : * the strategy field correctly for them.
3290 : *
3291 : * Lastly, for ordinary scankeys (not IS NULL/NOT NULL), we check for a
3292 : * NULL comparison value. Since all btree operators are assumed strict,
3293 : * a NULL means that the qual cannot be satisfied. We return true if the
3294 : * comparison value isn't NULL, or false if the scan should be abandoned.
3295 : *
3296 : * This function is applied to the *input* scankey structure; therefore
3297 : * on a rescan we will be looking at already-processed scankeys. Hence
3298 : * we have to be careful not to re-commute the strategy if we already did it.
3299 : * It's a bit ugly to modify the caller's copy of the scankey but in practice
3300 : * there shouldn't be any problem, since the index's indoptions are certainly
3301 : * not going to change while the scankey survives.
3302 : */
3303 : static bool
3304 20758786 : _bt_fix_scankey_strategy(ScanKey skey, int16 *indoption)
3305 : {
3306 : int addflags;
3307 :
3308 20758786 : addflags = indoption[skey->sk_attno - 1] << SK_BT_INDOPTION_SHIFT;
3309 :
3310 : /*
3311 : * We treat all btree operators as strict (even if they're not so marked
3312 : * in pg_proc). This means that it is impossible for an operator condition
3313 : * with a NULL comparison constant to succeed, and we can reject it right
3314 : * away.
3315 : *
3316 : * However, we now also support "x IS NULL" clauses as search conditions,
3317 : * so in that case keep going. The planner has not filled in any
3318 : * particular strategy in this case, so set it to BTEqualStrategyNumber
3319 : * --- we can treat IS NULL as an equality operator for purposes of search
3320 : * strategy.
3321 : *
3322 : * Likewise, "x IS NOT NULL" is supported. We treat that as either "less
3323 : * than NULL" in a NULLS LAST index, or "greater than NULL" in a NULLS
3324 : * FIRST index.
3325 : *
3326 : * Note: someday we might have to fill in sk_collation from the index
3327 : * column's collation. At the moment this is a non-issue because we'll
3328 : * never actually call the comparison operator on a NULL.
3329 : */
3330 20758786 : if (skey->sk_flags & SK_ISNULL)
3331 : {
3332 : /* SK_ISNULL shouldn't be set in a row header scankey */
3333 : Assert(!(skey->sk_flags & SK_ROW_HEADER));
3334 :
3335 : /* Set indoption flags in scankey (might be done already) */
3336 106412 : skey->sk_flags |= addflags;
3337 :
3338 : /* Set correct strategy for IS NULL or NOT NULL search */
3339 106412 : if (skey->sk_flags & SK_SEARCHNULL)
3340 : {
3341 140 : skey->sk_strategy = BTEqualStrategyNumber;
3342 140 : skey->sk_subtype = InvalidOid;
3343 140 : skey->sk_collation = InvalidOid;
3344 : }
3345 106272 : else if (skey->sk_flags & SK_SEARCHNOTNULL)
3346 : {
3347 105282 : if (skey->sk_flags & SK_BT_NULLS_FIRST)
3348 36 : skey->sk_strategy = BTGreaterStrategyNumber;
3349 : else
3350 105246 : skey->sk_strategy = BTLessStrategyNumber;
3351 105282 : skey->sk_subtype = InvalidOid;
3352 105282 : skey->sk_collation = InvalidOid;
3353 : }
3354 : else
3355 : {
3356 : /* regular qual, so it cannot be satisfied */
3357 990 : return false;
3358 : }
3359 :
3360 : /* Needn't do the rest */
3361 105422 : return true;
3362 : }
3363 :
3364 : /* Adjust strategy for DESC, if we didn't already */
3365 20652374 : if ((addflags & SK_BT_DESC) && !(skey->sk_flags & SK_BT_DESC))
3366 6 : skey->sk_strategy = BTCommuteStrategyNumber(skey->sk_strategy);
3367 20652374 : skey->sk_flags |= addflags;
3368 :
3369 : /* If it's a row header, fix row member flags and strategies similarly */
3370 20652374 : if (skey->sk_flags & SK_ROW_HEADER)
3371 : {
3372 36 : ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
3373 :
3374 : for (;;)
3375 : {
3376 36 : Assert(subkey->sk_flags & SK_ROW_MEMBER);
3377 72 : addflags = indoption[subkey->sk_attno - 1] << SK_BT_INDOPTION_SHIFT;
3378 72 : if ((addflags & SK_BT_DESC) && !(subkey->sk_flags & SK_BT_DESC))
3379 0 : subkey->sk_strategy = BTCommuteStrategyNumber(subkey->sk_strategy);
3380 72 : subkey->sk_flags |= addflags;
3381 72 : if (subkey->sk_flags & SK_ROW_END)
3382 36 : break;
3383 36 : subkey++;
3384 : }
3385 : }
3386 :
3387 20652374 : return true;
3388 : }
3389 :
3390 : /*
3391 : * Mark a scankey as "required to continue the scan".
3392 : *
3393 : * Depending on the operator type, the key may be required for both scan
3394 : * directions or just one. Also, if the key is a row comparison header,
3395 : * we have to mark its first subsidiary ScanKey as required. (Subsequent
3396 : * subsidiary ScanKeys are normally for lower-order columns, and thus
3397 : * cannot be required, since they're after the first non-equality scankey.)
3398 : *
3399 : * Note: when we set required-key flag bits in a subsidiary scankey, we are
3400 : * scribbling on a data structure belonging to the index AM's caller, not on
3401 : * our private copy. This should be OK because the marking will not change
3402 : * from scan to scan within a query, and so we'd just re-mark the same way
3403 : * anyway on a rescan. Something to keep an eye on though.
3404 : */
3405 : static void
3406 20754842 : _bt_mark_scankey_required(ScanKey skey)
3407 : {
3408 : int addflags;
3409 :
3410 20754842 : switch (skey->sk_strategy)
3411 : {
3412 108162 : case BTLessStrategyNumber:
3413 : case BTLessEqualStrategyNumber:
3414 108162 : addflags = SK_BT_REQFWD;
3415 108162 : break;
3416 19335008 : case BTEqualStrategyNumber:
3417 19335008 : addflags = SK_BT_REQFWD | SK_BT_REQBKWD;
3418 19335008 : break;
3419 1311672 : case BTGreaterEqualStrategyNumber:
3420 : case BTGreaterStrategyNumber:
3421 1311672 : addflags = SK_BT_REQBKWD;
3422 1311672 : break;
3423 0 : default:
3424 0 : elog(ERROR, "unrecognized StrategyNumber: %d",
3425 : (int) skey->sk_strategy);
3426 : addflags = 0; /* keep compiler quiet */
3427 : break;
3428 : }
3429 :
3430 20754842 : skey->sk_flags |= addflags;
3431 :
3432 20754842 : if (skey->sk_flags & SK_ROW_HEADER)
3433 : {
3434 36 : ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
3435 :
3436 : /* First subkey should be same column/operator as the header */
3437 : Assert(subkey->sk_flags & SK_ROW_MEMBER);
3438 : Assert(subkey->sk_attno == skey->sk_attno);
3439 : Assert(subkey->sk_strategy == skey->sk_strategy);
3440 36 : subkey->sk_flags |= addflags;
3441 : }
3442 20754842 : }
3443 :
3444 : /*
3445 : * Test whether an indextuple satisfies all the scankey conditions.
3446 : *
3447 : * Return true if so, false if not. If the tuple fails to pass the qual,
3448 : * we also determine whether there's any need to continue the scan beyond
3449 : * this tuple, and set pstate.continuescan accordingly. See comments for
3450 : * _bt_preprocess_keys(), above, about how this is done.
3451 : *
3452 : * Forward scan callers can pass a high key tuple in the hopes of having
3453 : * us set *continuescan to false, and avoiding an unnecessary visit to
3454 : * the page to the right.
3455 : *
3456 : * Advances the scan's array keys when necessary for arrayKeys=true callers.
3457 : * Caller can avoid all array related side-effects when calling just to do a
3458 : * page continuescan precheck -- pass arrayKeys=false for that. Scans without
3459 : * any arrays keys must always pass arrayKeys=false.
3460 : *
3461 : * Also stops and starts primitive index scans for arrayKeys=true callers.
3462 : * Scans with array keys are required to set up page state that helps us with
3463 : * this. The page's finaltup tuple (the page high key for a forward scan, or
3464 : * the page's first non-pivot tuple for a backward scan) must be set in
3465 : * pstate.finaltup ahead of the first call here for the page (or possibly the
3466 : * first call after an initial continuescan-setting page precheck call). Set
3467 : * this to NULL for rightmost page (or the leftmost page for backwards scans).
3468 : *
3469 : * scan: index scan descriptor (containing a search-type scankey)
3470 : * pstate: page level input and output parameters
3471 : * arrayKeys: should we advance the scan's array keys if necessary?
3472 : * tuple: index tuple to test
3473 : * tupnatts: number of attributes in tupnatts (high key may be truncated)
3474 : */
3475 : bool
3476 50483348 : _bt_checkkeys(IndexScanDesc scan, BTReadPageState *pstate, bool arrayKeys,
3477 : IndexTuple tuple, int tupnatts)
3478 : {
3479 50483348 : TupleDesc tupdesc = RelationGetDescr(scan->indexRelation);
3480 50483348 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
3481 50483348 : ScanDirection dir = so->currPos.dir;
3482 50483348 : int ikey = 0;
3483 : bool res;
3484 :
3485 : Assert(BTreeTupleGetNAtts(tuple, scan->indexRelation) == tupnatts);
3486 :
3487 50483348 : res = _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc,
3488 50483348 : arrayKeys, pstate->prechecked, pstate->firstmatch,
3489 : &pstate->continuescan, &ikey);
3490 :
3491 : #ifdef USE_ASSERT_CHECKING
3492 : if (!arrayKeys && so->numArrayKeys)
3493 : {
3494 : /*
3495 : * This is a continuescan precheck call for a scan with array keys.
3496 : *
3497 : * Assert that the scan isn't in danger of becoming confused.
3498 : */
3499 : Assert(!so->scanBehind && !so->oppositeDirCheck);
3500 : Assert(!pstate->prechecked && !pstate->firstmatch);
3501 : Assert(!_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc,
3502 : tupnatts, false, 0, NULL));
3503 : }
3504 : if (pstate->prechecked || pstate->firstmatch)
3505 : {
3506 : bool dcontinuescan;
3507 : int dikey = 0;
3508 :
3509 : /*
3510 : * Call relied on continuescan/firstmatch prechecks -- assert that we
3511 : * get the same answer without those optimizations
3512 : */
3513 : Assert(res == _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc,
3514 : false, false, false,
3515 : &dcontinuescan, &dikey));
3516 : Assert(pstate->continuescan == dcontinuescan);
3517 : }
3518 : #endif
3519 :
3520 : /*
3521 : * Only one _bt_check_compare call is required in the common case where
3522 : * there are no equality strategy array scan keys. Otherwise we can only
3523 : * accept _bt_check_compare's answer unreservedly when it didn't set
3524 : * pstate.continuescan=false.
3525 : */
3526 50483348 : if (!arrayKeys || pstate->continuescan)
3527 50476528 : return res;
3528 :
3529 : /*
3530 : * _bt_check_compare call set continuescan=false in the presence of
3531 : * equality type array keys. This could mean that the tuple is just past
3532 : * the end of matches for the current array keys.
3533 : *
3534 : * It's also possible that the scan is still _before_ the _start_ of
3535 : * tuples matching the current set of array keys. Check for that first.
3536 : */
3537 6820 : if (_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts, true,
3538 : ikey, NULL))
3539 : {
3540 : /*
3541 : * Tuple is still before the start of matches according to the scan's
3542 : * required array keys (according to _all_ of its required equality
3543 : * strategy keys, actually).
3544 : *
3545 : * _bt_advance_array_keys occasionally sets so->scanBehind to signal
3546 : * that the scan's current position/tuples might be significantly
3547 : * behind (multiple pages behind) its current array keys. When this
3548 : * happens, we need to be prepared to recover by starting a new
3549 : * primitive index scan here, on our own.
3550 : */
3551 : Assert(!so->scanBehind ||
3552 : so->keyData[ikey].sk_strategy == BTEqualStrategyNumber);
3553 2776 : if (unlikely(so->scanBehind) && pstate->finaltup &&
3554 60 : _bt_tuple_before_array_skeys(scan, dir, pstate->finaltup, tupdesc,
3555 60 : BTreeTupleGetNAtts(pstate->finaltup,
3556 : scan->indexRelation),
3557 : false, 0, NULL))
3558 : {
3559 : /* Cut our losses -- start a new primitive index scan now */
3560 0 : pstate->continuescan = false;
3561 0 : so->needPrimScan = true;
3562 : }
3563 : else
3564 : {
3565 : /* Override _bt_check_compare, continue primitive scan */
3566 2746 : pstate->continuescan = true;
3567 :
3568 : /*
3569 : * We will end up here repeatedly given a group of tuples > the
3570 : * previous array keys and < the now-current keys (for a backwards
3571 : * scan it's just the same, though the operators swap positions).
3572 : *
3573 : * We must avoid allowing this linear search process to scan very
3574 : * many tuples from well before the start of tuples matching the
3575 : * current array keys (or from well before the point where we'll
3576 : * once again have to advance the scan's array keys).
3577 : *
3578 : * We keep the overhead under control by speculatively "looking
3579 : * ahead" to later still-unscanned items from this same leaf page.
3580 : * We'll only attempt this once the number of tuples that the
3581 : * linear search process has examined starts to get out of hand.
3582 : */
3583 2746 : pstate->rechecks++;
3584 2746 : if (pstate->rechecks >= LOOK_AHEAD_REQUIRED_RECHECKS)
3585 : {
3586 : /* See if we should skip ahead within the current leaf page */
3587 1048 : _bt_checkkeys_look_ahead(scan, pstate, tupnatts, tupdesc);
3588 :
3589 : /*
3590 : * Might have set pstate.skip to a later page offset. When
3591 : * that happens then _bt_readpage caller will inexpensively
3592 : * skip ahead to a later tuple from the same page (the one
3593 : * just after the tuple we successfully "looked ahead" to).
3594 : */
3595 : }
3596 : }
3597 :
3598 : /* This indextuple doesn't match the current qual, in any case */
3599 2746 : return false;
3600 : }
3601 :
3602 : /*
3603 : * Caller's tuple is >= the current set of array keys and other equality
3604 : * constraint scan keys (or <= if this is a backwards scan). It's now
3605 : * clear that we _must_ advance any required array keys in lockstep with
3606 : * the scan.
3607 : */
3608 4074 : return _bt_advance_array_keys(scan, pstate, tuple, tupnatts, tupdesc,
3609 : ikey, true);
3610 : }
3611 :
3612 : /*
3613 : * Test whether an indextuple fails to satisfy an inequality required in the
3614 : * opposite direction only.
3615 : *
3616 : * Caller's finaltup tuple is the page high key (for forwards scans), or the
3617 : * first non-pivot tuple (for backwards scans). Called during scans with
3618 : * required array keys and required opposite-direction inequalities.
3619 : *
3620 : * Returns false if an inequality scan key required in the opposite direction
3621 : * only isn't satisfied (and any earlier required scan keys are satisfied).
3622 : * Otherwise returns true.
3623 : *
3624 : * An unsatisfied inequality required in the opposite direction only might
3625 : * well enable skipping over many leaf pages, provided another _bt_first call
3626 : * takes place. This type of unsatisfied inequality won't usually cause
3627 : * _bt_checkkeys to stop the scan to consider array advancement/starting a new
3628 : * primitive index scan.
3629 : */
3630 : bool
3631 0 : _bt_oppodir_checkkeys(IndexScanDesc scan, ScanDirection dir,
3632 : IndexTuple finaltup)
3633 : {
3634 0 : Relation rel = scan->indexRelation;
3635 0 : TupleDesc tupdesc = RelationGetDescr(rel);
3636 0 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
3637 0 : int nfinaltupatts = BTreeTupleGetNAtts(finaltup, rel);
3638 : bool continuescan;
3639 0 : ScanDirection flipped = -dir;
3640 0 : int ikey = 0;
3641 :
3642 : Assert(so->numArrayKeys);
3643 :
3644 0 : _bt_check_compare(scan, flipped, finaltup, nfinaltupatts, tupdesc,
3645 : false, false, false, &continuescan, &ikey);
3646 :
3647 0 : if (!continuescan && so->keyData[ikey].sk_strategy != BTEqualStrategyNumber)
3648 0 : return false;
3649 :
3650 0 : return true;
3651 : }
3652 :
3653 : /*
3654 : * Test whether an indextuple satisfies current scan condition.
3655 : *
3656 : * Return true if so, false if not. If not, also sets *continuescan to false
3657 : * when it's also not possible for any later tuples to pass the current qual
3658 : * (with the scan's current set of array keys, in the current scan direction),
3659 : * in addition to setting *ikey to the so->keyData[] subscript/offset for the
3660 : * unsatisfied scan key (needed when caller must consider advancing the scan's
3661 : * array keys).
3662 : *
3663 : * This is a subroutine for _bt_checkkeys. We provisionally assume that
3664 : * reaching the end of the current set of required keys (in particular the
3665 : * current required array keys) ends the ongoing (primitive) index scan.
3666 : * Callers without array keys should just end the scan right away when they
3667 : * find that continuescan has been set to false here by us. Things are more
3668 : * complicated for callers with array keys.
3669 : *
3670 : * Callers with array keys must first consider advancing the arrays when
3671 : * continuescan has been set to false here by us. They must then consider if
3672 : * it really does make sense to end the current (primitive) index scan, in
3673 : * light of everything that is known at that point. (In general when we set
3674 : * continuescan=false for these callers it must be treated as provisional.)
3675 : *
3676 : * We deal with advancing unsatisfied non-required arrays directly, though.
3677 : * This is safe, since by definition non-required keys can't end the scan.
3678 : * This is just how we determine if non-required arrays are just unsatisfied
3679 : * by the current array key, or if they're truly unsatisfied (that is, if
3680 : * they're unsatisfied by every possible array key).
3681 : *
3682 : * Though we advance non-required array keys on our own, that shouldn't have
3683 : * any lasting consequences for the scan. By definition, non-required arrays
3684 : * have no fixed relationship with the scan's progress. (There are delicate
3685 : * considerations for non-required arrays when the arrays need to be advanced
3686 : * following our setting continuescan to false, but that doesn't concern us.)
3687 : *
3688 : * Pass advancenonrequired=false to avoid all array related side effects.
3689 : * This allows _bt_advance_array_keys caller to avoid infinite recursion.
3690 : */
3691 : static bool
3692 50485282 : _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
3693 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
3694 : bool advancenonrequired, bool prechecked, bool firstmatch,
3695 : bool *continuescan, int *ikey)
3696 : {
3697 50485282 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
3698 :
3699 50485282 : *continuescan = true; /* default assumption */
3700 :
3701 97763084 : for (; *ikey < so->numberOfKeys; (*ikey)++)
3702 : {
3703 57495614 : ScanKey key = so->keyData + *ikey;
3704 : Datum datum;
3705 : bool isNull;
3706 57495614 : bool requiredSameDir = false,
3707 57495614 : requiredOppositeDirOnly = false;
3708 :
3709 : /*
3710 : * Check if the key is required in the current scan direction, in the
3711 : * opposite scan direction _only_, or in neither direction
3712 : */
3713 57495614 : if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsForward(dir)) ||
3714 13594340 : ((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsBackward(dir)))
3715 43918588 : requiredSameDir = true;
3716 13577026 : else if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsBackward(dir)) ||
3717 6425032 : ((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsForward(dir)))
3718 13010804 : requiredOppositeDirOnly = true;
3719 :
3720 : /*
3721 : * If the caller told us the *continuescan flag is known to be true
3722 : * for the last item on the page, then we know the keys required for
3723 : * the current direction scan should be matched. Otherwise, the
3724 : * *continuescan flag would be set for the current item and
3725 : * subsequently the last item on the page accordingly.
3726 : *
3727 : * If the key is required for the opposite direction scan, we can skip
3728 : * the check if the caller tells us there was already at least one
3729 : * matching item on the page. Also, we require the *continuescan flag
3730 : * to be true for the last item on the page to know there are no
3731 : * NULLs.
3732 : *
3733 : * Both cases above work except for the row keys, where NULLs could be
3734 : * found in the middle of matching values.
3735 : */
3736 57495614 : if (prechecked &&
3737 1580158 : (requiredSameDir || (requiredOppositeDirOnly && firstmatch)) &&
3738 1472614 : !(key->sk_flags & SK_ROW_HEADER))
3739 17361490 : continue;
3740 :
3741 56023000 : if (key->sk_attno > tupnatts)
3742 : {
3743 : /*
3744 : * This attribute is truncated (must be high key). The value for
3745 : * this attribute in the first non-pivot tuple on the page to the
3746 : * right could be any possible value. Assume that truncated
3747 : * attribute passes the qual.
3748 : */
3749 : Assert(BTreeTupleIsPivot(tuple));
3750 2154 : continue;
3751 : }
3752 :
3753 : /* row-comparison keys need special processing */
3754 56020846 : if (key->sk_flags & SK_ROW_HEADER)
3755 : {
3756 1980 : if (_bt_check_rowcompare(key, tuple, tupnatts, tupdesc, dir,
3757 : continuescan))
3758 1926 : continue;
3759 10217812 : return false;
3760 : }
3761 :
3762 56018866 : datum = index_getattr(tuple,
3763 56018866 : key->sk_attno,
3764 : tupdesc,
3765 : &isNull);
3766 :
3767 56018866 : if (key->sk_flags & SK_ISNULL)
3768 : {
3769 : /* Handle IS NULL/NOT NULL tests */
3770 15932958 : if (key->sk_flags & SK_SEARCHNULL)
3771 : {
3772 48236 : if (isNull)
3773 164 : continue; /* tuple satisfies this qual */
3774 : }
3775 : else
3776 : {
3777 : Assert(key->sk_flags & SK_SEARCHNOTNULL);
3778 15884722 : if (!isNull)
3779 15884632 : continue; /* tuple satisfies this qual */
3780 : }
3781 :
3782 : /*
3783 : * Tuple fails this qual. If it's a required qual for the current
3784 : * scan direction, then we can conclude no further tuples will
3785 : * pass, either.
3786 : */
3787 48162 : if (requiredSameDir)
3788 36 : *continuescan = false;
3789 :
3790 : /*
3791 : * In any case, this indextuple doesn't match the qual.
3792 : */
3793 48162 : return false;
3794 : }
3795 :
3796 40085908 : if (isNull)
3797 : {
3798 150 : if (key->sk_flags & SK_BT_NULLS_FIRST)
3799 : {
3800 : /*
3801 : * Since NULLs are sorted before non-NULLs, we know we have
3802 : * reached the lower limit of the range of values for this
3803 : * index attr. On a backward scan, we can stop if this qual
3804 : * is one of the "must match" subset. We can stop regardless
3805 : * of whether the qual is > or <, so long as it's required,
3806 : * because it's not possible for any future tuples to pass. On
3807 : * a forward scan, however, we must keep going, because we may
3808 : * have initially positioned to the start of the index.
3809 : * (_bt_advance_array_keys also relies on this behavior during
3810 : * forward scans.)
3811 : */
3812 0 : if ((key->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
3813 : ScanDirectionIsBackward(dir))
3814 0 : *continuescan = false;
3815 : }
3816 : else
3817 : {
3818 : /*
3819 : * Since NULLs are sorted after non-NULLs, we know we have
3820 : * reached the upper limit of the range of values for this
3821 : * index attr. On a forward scan, we can stop if this qual is
3822 : * one of the "must match" subset. We can stop regardless of
3823 : * whether the qual is > or <, so long as it's required,
3824 : * because it's not possible for any future tuples to pass. On
3825 : * a backward scan, however, we must keep going, because we
3826 : * may have initially positioned to the end of the index.
3827 : * (_bt_advance_array_keys also relies on this behavior during
3828 : * backward scans.)
3829 : */
3830 150 : if ((key->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
3831 : ScanDirectionIsForward(dir))
3832 84 : *continuescan = false;
3833 : }
3834 :
3835 : /*
3836 : * In any case, this indextuple doesn't match the qual.
3837 : */
3838 150 : return false;
3839 : }
3840 :
3841 : /*
3842 : * Apply the key-checking function, though only if we must.
3843 : *
3844 : * When a key is required in the opposite-of-scan direction _only_,
3845 : * then it must already be satisfied if firstmatch=true indicates that
3846 : * an earlier tuple from this same page satisfied it earlier on.
3847 : */
3848 40085758 : if (!(requiredOppositeDirOnly && firstmatch) &&
3849 36646902 : !DatumGetBool(FunctionCall2Coll(&key->sk_func, key->sk_collation,
3850 : datum, key->sk_argument)))
3851 : {
3852 : /*
3853 : * Tuple fails this qual. If it's a required qual for the current
3854 : * scan direction, then we can conclude no further tuples will
3855 : * pass, either.
3856 : *
3857 : * Note: because we stop the scan as soon as any required equality
3858 : * qual fails, it is critical that equality quals be used for the
3859 : * initial positioning in _bt_first() when they are available. See
3860 : * comments in _bt_first().
3861 : */
3862 10169446 : if (requiredSameDir)
3863 9740840 : *continuescan = false;
3864 :
3865 : /*
3866 : * If this is a non-required equality-type array key, the tuple
3867 : * needs to be checked against every possible array key. Handle
3868 : * this by "advancing" the scan key's array to a matching value
3869 : * (if we're successful then the tuple might match the qual).
3870 : */
3871 428606 : else if (advancenonrequired &&
3872 326 : key->sk_strategy == BTEqualStrategyNumber &&
3873 260 : (key->sk_flags & SK_SEARCHARRAY))
3874 260 : return _bt_advance_array_keys(scan, NULL, tuple, tupnatts,
3875 : tupdesc, *ikey, false);
3876 :
3877 : /*
3878 : * This indextuple doesn't match the qual.
3879 : */
3880 10169186 : return false;
3881 : }
3882 : }
3883 :
3884 : /* If we get here, the tuple passes all index quals. */
3885 40267470 : return true;
3886 : }
3887 :
3888 : /*
3889 : * Test whether an indextuple satisfies a row-comparison scan condition.
3890 : *
3891 : * Return true if so, false if not. If not, also clear *continuescan if
3892 : * it's not possible for any future tuples in the current scan direction
3893 : * to pass the qual.
3894 : *
3895 : * This is a subroutine for _bt_checkkeys/_bt_check_compare.
3896 : */
3897 : static bool
3898 1980 : _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
3899 : TupleDesc tupdesc, ScanDirection dir, bool *continuescan)
3900 : {
3901 1980 : ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
3902 1980 : int32 cmpresult = 0;
3903 : bool result;
3904 :
3905 : /* First subkey should be same as the header says */
3906 : Assert(subkey->sk_attno == skey->sk_attno);
3907 :
3908 : /* Loop over columns of the row condition */
3909 : for (;;)
3910 156 : {
3911 : Datum datum;
3912 : bool isNull;
3913 :
3914 : Assert(subkey->sk_flags & SK_ROW_MEMBER);
3915 :
3916 2136 : if (subkey->sk_attno > tupnatts)
3917 : {
3918 : /*
3919 : * This attribute is truncated (must be high key). The value for
3920 : * this attribute in the first non-pivot tuple on the page to the
3921 : * right could be any possible value. Assume that truncated
3922 : * attribute passes the qual.
3923 : */
3924 : Assert(BTreeTupleIsPivot(tuple));
3925 6 : cmpresult = 0;
3926 6 : if (subkey->sk_flags & SK_ROW_END)
3927 6 : break;
3928 0 : subkey++;
3929 0 : continue;
3930 : }
3931 :
3932 2130 : datum = index_getattr(tuple,
3933 2130 : subkey->sk_attno,
3934 : tupdesc,
3935 : &isNull);
3936 :
3937 2130 : if (isNull)
3938 : {
3939 48 : if (subkey->sk_flags & SK_BT_NULLS_FIRST)
3940 : {
3941 : /*
3942 : * Since NULLs are sorted before non-NULLs, we know we have
3943 : * reached the lower limit of the range of values for this
3944 : * index attr. On a backward scan, we can stop if this qual
3945 : * is one of the "must match" subset. We can stop regardless
3946 : * of whether the qual is > or <, so long as it's required,
3947 : * because it's not possible for any future tuples to pass. On
3948 : * a forward scan, however, we must keep going, because we may
3949 : * have initially positioned to the start of the index.
3950 : * (_bt_advance_array_keys also relies on this behavior during
3951 : * forward scans.)
3952 : */
3953 0 : if ((subkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
3954 : ScanDirectionIsBackward(dir))
3955 0 : *continuescan = false;
3956 : }
3957 : else
3958 : {
3959 : /*
3960 : * Since NULLs are sorted after non-NULLs, we know we have
3961 : * reached the upper limit of the range of values for this
3962 : * index attr. On a forward scan, we can stop if this qual is
3963 : * one of the "must match" subset. We can stop regardless of
3964 : * whether the qual is > or <, so long as it's required,
3965 : * because it's not possible for any future tuples to pass. On
3966 : * a backward scan, however, we must keep going, because we
3967 : * may have initially positioned to the end of the index.
3968 : * (_bt_advance_array_keys also relies on this behavior during
3969 : * backward scans.)
3970 : */
3971 48 : if ((subkey->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) &&
3972 : ScanDirectionIsForward(dir))
3973 0 : *continuescan = false;
3974 : }
3975 :
3976 : /*
3977 : * In any case, this indextuple doesn't match the qual.
3978 : */
3979 48 : return false;
3980 : }
3981 :
3982 2082 : if (subkey->sk_flags & SK_ISNULL)
3983 : {
3984 : /*
3985 : * Unlike the simple-scankey case, this isn't a disallowed case.
3986 : * But it can never match. If all the earlier row comparison
3987 : * columns are required for the scan direction, we can stop the
3988 : * scan, because there can't be another tuple that will succeed.
3989 : */
3990 0 : if (subkey != (ScanKey) DatumGetPointer(skey->sk_argument))
3991 0 : subkey--;
3992 0 : if ((subkey->sk_flags & SK_BT_REQFWD) &&
3993 : ScanDirectionIsForward(dir))
3994 0 : *continuescan = false;
3995 0 : else if ((subkey->sk_flags & SK_BT_REQBKWD) &&
3996 : ScanDirectionIsBackward(dir))
3997 0 : *continuescan = false;
3998 0 : return false;
3999 : }
4000 :
4001 : /* Perform the test --- three-way comparison not bool operator */
4002 2082 : cmpresult = DatumGetInt32(FunctionCall2Coll(&subkey->sk_func,
4003 : subkey->sk_collation,
4004 : datum,
4005 : subkey->sk_argument));
4006 :
4007 2082 : if (subkey->sk_flags & SK_BT_DESC)
4008 0 : INVERT_COMPARE_RESULT(cmpresult);
4009 :
4010 : /* Done comparing if unequal, else advance to next column */
4011 2082 : if (cmpresult != 0)
4012 1926 : break;
4013 :
4014 156 : if (subkey->sk_flags & SK_ROW_END)
4015 0 : break;
4016 156 : subkey++;
4017 : }
4018 :
4019 : /*
4020 : * At this point cmpresult indicates the overall result of the row
4021 : * comparison, and subkey points to the deciding column (or the last
4022 : * column if the result is "=").
4023 : */
4024 1932 : switch (subkey->sk_strategy)
4025 : {
4026 : /* EQ and NE cases aren't allowed here */
4027 0 : case BTLessStrategyNumber:
4028 0 : result = (cmpresult < 0);
4029 0 : break;
4030 1590 : case BTLessEqualStrategyNumber:
4031 1590 : result = (cmpresult <= 0);
4032 1590 : break;
4033 240 : case BTGreaterEqualStrategyNumber:
4034 240 : result = (cmpresult >= 0);
4035 240 : break;
4036 102 : case BTGreaterStrategyNumber:
4037 102 : result = (cmpresult > 0);
4038 102 : break;
4039 0 : default:
4040 0 : elog(ERROR, "unexpected strategy number %d", subkey->sk_strategy);
4041 : result = 0; /* keep compiler quiet */
4042 : break;
4043 : }
4044 :
4045 1932 : if (!result)
4046 : {
4047 : /*
4048 : * Tuple fails this qual. If it's a required qual for the current
4049 : * scan direction, then we can conclude no further tuples will pass,
4050 : * either. Note we have to look at the deciding column, not
4051 : * necessarily the first or last column of the row condition.
4052 : */
4053 6 : if ((subkey->sk_flags & SK_BT_REQFWD) &&
4054 : ScanDirectionIsForward(dir))
4055 6 : *continuescan = false;
4056 0 : else if ((subkey->sk_flags & SK_BT_REQBKWD) &&
4057 : ScanDirectionIsBackward(dir))
4058 0 : *continuescan = false;
4059 : }
4060 :
4061 1932 : return result;
4062 : }
4063 :
4064 : /*
4065 : * Determine if a scan with array keys should skip over uninteresting tuples.
4066 : *
4067 : * This is a subroutine for _bt_checkkeys. Called when _bt_readpage's linear
4068 : * search process (started after it finishes reading an initial group of
4069 : * matching tuples, used to locate the start of the next group of tuples
4070 : * matching the next set of required array keys) has already scanned an
4071 : * excessive number of tuples whose key space is "between arrays".
4072 : *
4073 : * When we perform look ahead successfully, we'll sets pstate.skip, which
4074 : * instructs _bt_readpage to skip ahead to that tuple next (could be past the
4075 : * end of the scan's leaf page). Pages where the optimization is effective
4076 : * will generally still need to skip several times. Each call here performs
4077 : * only a single "look ahead" comparison of a later tuple, whose distance from
4078 : * the current tuple's offset number is determined by applying heuristics.
4079 : */
4080 : static void
4081 1048 : _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
4082 : int tupnatts, TupleDesc tupdesc)
4083 : {
4084 1048 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
4085 1048 : ScanDirection dir = so->currPos.dir;
4086 : OffsetNumber aheadoffnum;
4087 : IndexTuple ahead;
4088 :
4089 : /* Avoid looking ahead when comparing the page high key */
4090 1048 : if (pstate->offnum < pstate->minoff)
4091 0 : return;
4092 :
4093 : /*
4094 : * Don't look ahead when there aren't enough tuples remaining on the page
4095 : * (in the current scan direction) for it to be worth our while
4096 : */
4097 1048 : if (ScanDirectionIsForward(dir) &&
4098 1042 : pstate->offnum >= pstate->maxoff - LOOK_AHEAD_DEFAULT_DISTANCE)
4099 0 : return;
4100 1048 : else if (ScanDirectionIsBackward(dir) &&
4101 6 : pstate->offnum <= pstate->minoff + LOOK_AHEAD_DEFAULT_DISTANCE)
4102 0 : return;
4103 :
4104 : /*
4105 : * The look ahead distance starts small, and ramps up as each call here
4106 : * allows _bt_readpage to skip over more tuples
4107 : */
4108 1048 : if (!pstate->targetdistance)
4109 408 : pstate->targetdistance = LOOK_AHEAD_DEFAULT_DISTANCE;
4110 640 : else if (pstate->targetdistance < MaxIndexTuplesPerPage / 2)
4111 640 : pstate->targetdistance *= 2;
4112 :
4113 : /* Don't read past the end (or before the start) of the page, though */
4114 1048 : if (ScanDirectionIsForward(dir))
4115 1042 : aheadoffnum = Min((int) pstate->maxoff,
4116 : (int) pstate->offnum + pstate->targetdistance);
4117 : else
4118 6 : aheadoffnum = Max((int) pstate->minoff,
4119 : (int) pstate->offnum - pstate->targetdistance);
4120 :
4121 1048 : ahead = (IndexTuple) PageGetItem(pstate->page,
4122 : PageGetItemId(pstate->page, aheadoffnum));
4123 1048 : if (_bt_tuple_before_array_skeys(scan, dir, ahead, tupdesc, tupnatts,
4124 : false, 0, NULL))
4125 : {
4126 : /*
4127 : * Success -- instruct _bt_readpage to skip ahead to very next tuple
4128 : * after the one we determined was still before the current array keys
4129 : */
4130 424 : if (ScanDirectionIsForward(dir))
4131 418 : pstate->skip = aheadoffnum + 1;
4132 : else
4133 6 : pstate->skip = aheadoffnum - 1;
4134 : }
4135 : else
4136 : {
4137 : /*
4138 : * Failure -- "ahead" tuple is too far ahead (we were too aggressive).
4139 : *
4140 : * Reset the number of rechecks, and aggressively reduce the target
4141 : * distance (we're much more aggressive here than we were when the
4142 : * distance was initially ramped up).
4143 : */
4144 624 : pstate->rechecks = 0;
4145 624 : pstate->targetdistance = Max(pstate->targetdistance / 8, 1);
4146 : }
4147 : }
4148 :
4149 : /*
4150 : * _bt_killitems - set LP_DEAD state for items an indexscan caller has
4151 : * told us were killed
4152 : *
4153 : * scan->opaque, referenced locally through so, contains information about the
4154 : * current page and killed tuples thereon (generally, this should only be
4155 : * called if so->numKilled > 0).
4156 : *
4157 : * The caller does not have a lock on the page and may or may not have the
4158 : * page pinned in a buffer. Note that read-lock is sufficient for setting
4159 : * LP_DEAD status (which is only a hint).
4160 : *
4161 : * We match items by heap TID before assuming they are the right ones to
4162 : * delete. We cope with cases where items have moved right due to insertions.
4163 : * If an item has moved off the current page due to a split, we'll fail to
4164 : * find it and do nothing (this is not an error case --- we assume the item
4165 : * will eventually get marked in a future indexscan).
4166 : *
4167 : * Note that if we hold a pin on the target page continuously from initially
4168 : * reading the items until applying this function, VACUUM cannot have deleted
4169 : * any items from the page, and so there is no need to search left from the
4170 : * recorded offset. (This observation also guarantees that the item is still
4171 : * the right one to delete, which might otherwise be questionable since heap
4172 : * TIDs can get recycled.) This holds true even if the page has been modified
4173 : * by inserts and page splits, so there is no need to consult the LSN.
4174 : *
4175 : * If the pin was released after reading the page, then we re-read it. If it
4176 : * has been modified since we read it (as determined by the LSN), we dare not
4177 : * flag any entries because it is possible that the old entry was vacuumed
4178 : * away and the TID was re-used by a completely different heap tuple.
4179 : */
4180 : void
4181 158254 : _bt_killitems(IndexScanDesc scan)
4182 : {
4183 158254 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
4184 : Page page;
4185 : BTPageOpaque opaque;
4186 : OffsetNumber minoff;
4187 : OffsetNumber maxoff;
4188 : int i;
4189 158254 : int numKilled = so->numKilled;
4190 158254 : bool killedsomething = false;
4191 : bool droppedpin PG_USED_FOR_ASSERTS_ONLY;
4192 :
4193 : Assert(BTScanPosIsValid(so->currPos));
4194 :
4195 : /*
4196 : * Always reset the scan state, so we don't look for same items on other
4197 : * pages.
4198 : */
4199 158254 : so->numKilled = 0;
4200 :
4201 158254 : if (BTScanPosIsPinned(so->currPos))
4202 : {
4203 : /*
4204 : * We have held the pin on this page since we read the index tuples,
4205 : * so all we need to do is lock it. The pin will have prevented
4206 : * re-use of any TID on the page, so there is no need to check the
4207 : * LSN.
4208 : */
4209 34458 : droppedpin = false;
4210 34458 : _bt_lockbuf(scan->indexRelation, so->currPos.buf, BT_READ);
4211 :
4212 34458 : page = BufferGetPage(so->currPos.buf);
4213 : }
4214 : else
4215 : {
4216 : Buffer buf;
4217 :
4218 123796 : droppedpin = true;
4219 : /* Attempt to re-read the buffer, getting pin and lock. */
4220 123796 : buf = _bt_getbuf(scan->indexRelation, so->currPos.currPage, BT_READ);
4221 :
4222 123796 : page = BufferGetPage(buf);
4223 123796 : if (BufferGetLSNAtomic(buf) == so->currPos.lsn)
4224 123670 : so->currPos.buf = buf;
4225 : else
4226 : {
4227 : /* Modified while not pinned means hinting is not safe. */
4228 126 : _bt_relbuf(scan->indexRelation, buf);
4229 126 : return;
4230 : }
4231 : }
4232 :
4233 158128 : opaque = BTPageGetOpaque(page);
4234 158128 : minoff = P_FIRSTDATAKEY(opaque);
4235 158128 : maxoff = PageGetMaxOffsetNumber(page);
4236 :
4237 652178 : for (i = 0; i < numKilled; i++)
4238 : {
4239 494050 : int itemIndex = so->killedItems[i];
4240 494050 : BTScanPosItem *kitem = &so->currPos.items[itemIndex];
4241 494050 : OffsetNumber offnum = kitem->indexOffset;
4242 :
4243 : Assert(itemIndex >= so->currPos.firstItem &&
4244 : itemIndex <= so->currPos.lastItem);
4245 494050 : if (offnum < minoff)
4246 0 : continue; /* pure paranoia */
4247 8217830 : while (offnum <= maxoff)
4248 : {
4249 8149180 : ItemId iid = PageGetItemId(page, offnum);
4250 8149180 : IndexTuple ituple = (IndexTuple) PageGetItem(page, iid);
4251 8149180 : bool killtuple = false;
4252 :
4253 8149180 : if (BTreeTupleIsPosting(ituple))
4254 : {
4255 3044750 : int pi = i + 1;
4256 3044750 : int nposting = BTreeTupleGetNPosting(ituple);
4257 : int j;
4258 :
4259 : /*
4260 : * We rely on the convention that heap TIDs in the scanpos
4261 : * items array are stored in ascending heap TID order for a
4262 : * group of TIDs that originally came from a posting list
4263 : * tuple. This convention even applies during backwards
4264 : * scans, where returning the TIDs in descending order might
4265 : * seem more natural. This is about effectiveness, not
4266 : * correctness.
4267 : *
4268 : * Note that the page may have been modified in almost any way
4269 : * since we first read it (in the !droppedpin case), so it's
4270 : * possible that this posting list tuple wasn't a posting list
4271 : * tuple when we first encountered its heap TIDs.
4272 : */
4273 3117670 : for (j = 0; j < nposting; j++)
4274 : {
4275 3114898 : ItemPointer item = BTreeTupleGetPostingN(ituple, j);
4276 :
4277 3114898 : if (!ItemPointerEquals(item, &kitem->heapTid))
4278 3041978 : break; /* out of posting list loop */
4279 :
4280 : /*
4281 : * kitem must have matching offnum when heap TIDs match,
4282 : * though only in the common case where the page can't
4283 : * have been concurrently modified
4284 : */
4285 : Assert(kitem->indexOffset == offnum || !droppedpin);
4286 :
4287 : /*
4288 : * Read-ahead to later kitems here.
4289 : *
4290 : * We rely on the assumption that not advancing kitem here
4291 : * will prevent us from considering the posting list tuple
4292 : * fully dead by not matching its next heap TID in next
4293 : * loop iteration.
4294 : *
4295 : * If, on the other hand, this is the final heap TID in
4296 : * the posting list tuple, then tuple gets killed
4297 : * regardless (i.e. we handle the case where the last
4298 : * kitem is also the last heap TID in the last index tuple
4299 : * correctly -- posting tuple still gets killed).
4300 : */
4301 72920 : if (pi < numKilled)
4302 42918 : kitem = &so->currPos.items[so->killedItems[pi++]];
4303 : }
4304 :
4305 : /*
4306 : * Don't bother advancing the outermost loop's int iterator to
4307 : * avoid processing killed items that relate to the same
4308 : * offnum/posting list tuple. This micro-optimization hardly
4309 : * seems worth it. (Further iterations of the outermost loop
4310 : * will fail to match on this same posting list's first heap
4311 : * TID instead, so we'll advance to the next offnum/index
4312 : * tuple pretty quickly.)
4313 : */
4314 3044750 : if (j == nposting)
4315 2772 : killtuple = true;
4316 : }
4317 5104430 : else if (ItemPointerEquals(&ituple->t_tid, &kitem->heapTid))
4318 423310 : killtuple = true;
4319 :
4320 : /*
4321 : * Mark index item as dead, if it isn't already. Since this
4322 : * happens while holding a buffer lock possibly in shared mode,
4323 : * it's possible that multiple processes attempt to do this
4324 : * simultaneously, leading to multiple full-page images being sent
4325 : * to WAL (if wal_log_hints or data checksums are enabled), which
4326 : * is undesirable.
4327 : */
4328 8149180 : if (killtuple && !ItemIdIsDead(iid))
4329 : {
4330 : /* found the item/all posting list items */
4331 425400 : ItemIdMarkDead(iid);
4332 425400 : killedsomething = true;
4333 425400 : break; /* out of inner search loop */
4334 : }
4335 7723780 : offnum = OffsetNumberNext(offnum);
4336 : }
4337 : }
4338 :
4339 : /*
4340 : * Since this can be redone later if needed, mark as dirty hint.
4341 : *
4342 : * Whenever we mark anything LP_DEAD, we also set the page's
4343 : * BTP_HAS_GARBAGE flag, which is likewise just a hint. (Note that we
4344 : * only rely on the page-level flag in !heapkeyspace indexes.)
4345 : */
4346 158128 : if (killedsomething)
4347 : {
4348 126000 : opaque->btpo_flags |= BTP_HAS_GARBAGE;
4349 126000 : MarkBufferDirtyHint(so->currPos.buf, true);
4350 : }
4351 :
4352 158128 : _bt_unlockbuf(scan->indexRelation, so->currPos.buf);
4353 : }
4354 :
4355 :
4356 : /*
4357 : * The following routines manage a shared-memory area in which we track
4358 : * assignment of "vacuum cycle IDs" to currently-active btree vacuuming
4359 : * operations. There is a single counter which increments each time we
4360 : * start a vacuum to assign it a cycle ID. Since multiple vacuums could
4361 : * be active concurrently, we have to track the cycle ID for each active
4362 : * vacuum; this requires at most MaxBackends entries (usually far fewer).
4363 : * We assume at most one vacuum can be active for a given index.
4364 : *
4365 : * Access to the shared memory area is controlled by BtreeVacuumLock.
4366 : * In principle we could use a separate lmgr locktag for each index,
4367 : * but a single LWLock is much cheaper, and given the short time that
4368 : * the lock is ever held, the concurrency hit should be minimal.
4369 : */
4370 :
4371 : typedef struct BTOneVacInfo
4372 : {
4373 : LockRelId relid; /* global identifier of an index */
4374 : BTCycleId cycleid; /* cycle ID for its active VACUUM */
4375 : } BTOneVacInfo;
4376 :
4377 : typedef struct BTVacInfo
4378 : {
4379 : BTCycleId cycle_ctr; /* cycle ID most recently assigned */
4380 : int num_vacuums; /* number of currently active VACUUMs */
4381 : int max_vacuums; /* allocated length of vacuums[] array */
4382 : BTOneVacInfo vacuums[FLEXIBLE_ARRAY_MEMBER];
4383 : } BTVacInfo;
4384 :
4385 : static BTVacInfo *btvacinfo;
4386 :
4387 :
4388 : /*
4389 : * _bt_vacuum_cycleid --- get the active vacuum cycle ID for an index,
4390 : * or zero if there is no active VACUUM
4391 : *
4392 : * Note: for correct interlocking, the caller must already hold pin and
4393 : * exclusive lock on each buffer it will store the cycle ID into. This
4394 : * ensures that even if a VACUUM starts immediately afterwards, it cannot
4395 : * process those pages until the page split is complete.
4396 : */
4397 : BTCycleId
4398 21824 : _bt_vacuum_cycleid(Relation rel)
4399 : {
4400 21824 : BTCycleId result = 0;
4401 : int i;
4402 :
4403 : /* Share lock is enough since this is a read-only operation */
4404 21824 : LWLockAcquire(BtreeVacuumLock, LW_SHARED);
4405 :
4406 21824 : for (i = 0; i < btvacinfo->num_vacuums; i++)
4407 : {
4408 0 : BTOneVacInfo *vac = &btvacinfo->vacuums[i];
4409 :
4410 0 : if (vac->relid.relId == rel->rd_lockInfo.lockRelId.relId &&
4411 0 : vac->relid.dbId == rel->rd_lockInfo.lockRelId.dbId)
4412 : {
4413 0 : result = vac->cycleid;
4414 0 : break;
4415 : }
4416 : }
4417 :
4418 21824 : LWLockRelease(BtreeVacuumLock);
4419 21824 : return result;
4420 : }
4421 :
4422 : /*
4423 : * _bt_start_vacuum --- assign a cycle ID to a just-starting VACUUM operation
4424 : *
4425 : * Note: the caller must guarantee that it will eventually call
4426 : * _bt_end_vacuum, else we'll permanently leak an array slot. To ensure
4427 : * that this happens even in elog(FATAL) scenarios, the appropriate coding
4428 : * is not just a PG_TRY, but
4429 : * PG_ENSURE_ERROR_CLEANUP(_bt_end_vacuum_callback, PointerGetDatum(rel))
4430 : */
4431 : BTCycleId
4432 2468 : _bt_start_vacuum(Relation rel)
4433 : {
4434 : BTCycleId result;
4435 : int i;
4436 : BTOneVacInfo *vac;
4437 :
4438 2468 : LWLockAcquire(BtreeVacuumLock, LW_EXCLUSIVE);
4439 :
4440 : /*
4441 : * Assign the next cycle ID, being careful to avoid zero as well as the
4442 : * reserved high values.
4443 : */
4444 2468 : result = ++(btvacinfo->cycle_ctr);
4445 2468 : if (result == 0 || result > MAX_BT_CYCLE_ID)
4446 0 : result = btvacinfo->cycle_ctr = 1;
4447 :
4448 : /* Let's just make sure there's no entry already for this index */
4449 2468 : for (i = 0; i < btvacinfo->num_vacuums; i++)
4450 : {
4451 0 : vac = &btvacinfo->vacuums[i];
4452 0 : if (vac->relid.relId == rel->rd_lockInfo.lockRelId.relId &&
4453 0 : vac->relid.dbId == rel->rd_lockInfo.lockRelId.dbId)
4454 : {
4455 : /*
4456 : * Unlike most places in the backend, we have to explicitly
4457 : * release our LWLock before throwing an error. This is because
4458 : * we expect _bt_end_vacuum() to be called before transaction
4459 : * abort cleanup can run to release LWLocks.
4460 : */
4461 0 : LWLockRelease(BtreeVacuumLock);
4462 0 : elog(ERROR, "multiple active vacuums for index \"%s\"",
4463 : RelationGetRelationName(rel));
4464 : }
4465 : }
4466 :
4467 : /* OK, add an entry */
4468 2468 : if (btvacinfo->num_vacuums >= btvacinfo->max_vacuums)
4469 : {
4470 0 : LWLockRelease(BtreeVacuumLock);
4471 0 : elog(ERROR, "out of btvacinfo slots");
4472 : }
4473 2468 : vac = &btvacinfo->vacuums[btvacinfo->num_vacuums];
4474 2468 : vac->relid = rel->rd_lockInfo.lockRelId;
4475 2468 : vac->cycleid = result;
4476 2468 : btvacinfo->num_vacuums++;
4477 :
4478 2468 : LWLockRelease(BtreeVacuumLock);
4479 2468 : return result;
4480 : }
4481 :
4482 : /*
4483 : * _bt_end_vacuum --- mark a btree VACUUM operation as done
4484 : *
4485 : * Note: this is deliberately coded not to complain if no entry is found;
4486 : * this allows the caller to put PG_TRY around the start_vacuum operation.
4487 : */
4488 : void
4489 2468 : _bt_end_vacuum(Relation rel)
4490 : {
4491 : int i;
4492 :
4493 2468 : LWLockAcquire(BtreeVacuumLock, LW_EXCLUSIVE);
4494 :
4495 : /* Find the array entry */
4496 2468 : for (i = 0; i < btvacinfo->num_vacuums; i++)
4497 : {
4498 2468 : BTOneVacInfo *vac = &btvacinfo->vacuums[i];
4499 :
4500 2468 : if (vac->relid.relId == rel->rd_lockInfo.lockRelId.relId &&
4501 2468 : vac->relid.dbId == rel->rd_lockInfo.lockRelId.dbId)
4502 : {
4503 : /* Remove it by shifting down the last entry */
4504 2468 : *vac = btvacinfo->vacuums[btvacinfo->num_vacuums - 1];
4505 2468 : btvacinfo->num_vacuums--;
4506 2468 : break;
4507 : }
4508 : }
4509 :
4510 2468 : LWLockRelease(BtreeVacuumLock);
4511 2468 : }
4512 :
4513 : /*
4514 : * _bt_end_vacuum wrapped as an on_shmem_exit callback function
4515 : */
4516 : void
4517 0 : _bt_end_vacuum_callback(int code, Datum arg)
4518 : {
4519 0 : _bt_end_vacuum((Relation) DatumGetPointer(arg));
4520 0 : }
4521 :
4522 : /*
4523 : * BTreeShmemSize --- report amount of shared memory space needed
4524 : */
4525 : Size
4526 5454 : BTreeShmemSize(void)
4527 : {
4528 : Size size;
4529 :
4530 5454 : size = offsetof(BTVacInfo, vacuums);
4531 5454 : size = add_size(size, mul_size(MaxBackends, sizeof(BTOneVacInfo)));
4532 5454 : return size;
4533 : }
4534 :
4535 : /*
4536 : * BTreeShmemInit --- initialize this module's shared memory
4537 : */
4538 : void
4539 1908 : BTreeShmemInit(void)
4540 : {
4541 : bool found;
4542 :
4543 1908 : btvacinfo = (BTVacInfo *) ShmemInitStruct("BTree Vacuum State",
4544 : BTreeShmemSize(),
4545 : &found);
4546 :
4547 1908 : if (!IsUnderPostmaster)
4548 : {
4549 : /* Initialize shared memory area */
4550 : Assert(!found);
4551 :
4552 : /*
4553 : * It doesn't really matter what the cycle counter starts at, but
4554 : * having it always start the same doesn't seem good. Seed with
4555 : * low-order bits of time() instead.
4556 : */
4557 1908 : btvacinfo->cycle_ctr = (BTCycleId) time(NULL);
4558 :
4559 1908 : btvacinfo->num_vacuums = 0;
4560 1908 : btvacinfo->max_vacuums = MaxBackends;
4561 : }
4562 : else
4563 : Assert(found);
4564 1908 : }
4565 :
4566 : bytea *
4567 310 : btoptions(Datum reloptions, bool validate)
4568 : {
4569 : static const relopt_parse_elt tab[] = {
4570 : {"fillfactor", RELOPT_TYPE_INT, offsetof(BTOptions, fillfactor)},
4571 : {"vacuum_cleanup_index_scale_factor", RELOPT_TYPE_REAL,
4572 : offsetof(BTOptions, vacuum_cleanup_index_scale_factor)},
4573 : {"deduplicate_items", RELOPT_TYPE_BOOL,
4574 : offsetof(BTOptions, deduplicate_items)}
4575 : };
4576 :
4577 310 : return (bytea *) build_reloptions(reloptions, validate,
4578 : RELOPT_KIND_BTREE,
4579 : sizeof(BTOptions),
4580 : tab, lengthof(tab));
4581 : }
4582 :
4583 : /*
4584 : * btproperty() -- Check boolean properties of indexes.
4585 : *
4586 : * This is optional, but handling AMPROP_RETURNABLE here saves opening the rel
4587 : * to call btcanreturn.
4588 : */
4589 : bool
4590 756 : btproperty(Oid index_oid, int attno,
4591 : IndexAMProperty prop, const char *propname,
4592 : bool *res, bool *isnull)
4593 : {
4594 756 : switch (prop)
4595 : {
4596 42 : case AMPROP_RETURNABLE:
4597 : /* answer only for columns, not AM or whole index */
4598 42 : if (attno == 0)
4599 12 : return false;
4600 : /* otherwise, btree can always return data */
4601 30 : *res = true;
4602 30 : return true;
4603 :
4604 714 : default:
4605 714 : return false; /* punt to generic code */
4606 : }
4607 : }
4608 :
4609 : /*
4610 : * btbuildphasename() -- Return name of index build phase.
4611 : */
4612 : char *
4613 0 : btbuildphasename(int64 phasenum)
4614 : {
4615 0 : switch (phasenum)
4616 : {
4617 0 : case PROGRESS_CREATEIDX_SUBPHASE_INITIALIZE:
4618 0 : return "initializing";
4619 0 : case PROGRESS_BTREE_PHASE_INDEXBUILD_TABLESCAN:
4620 0 : return "scanning table";
4621 0 : case PROGRESS_BTREE_PHASE_PERFORMSORT_1:
4622 0 : return "sorting live tuples";
4623 0 : case PROGRESS_BTREE_PHASE_PERFORMSORT_2:
4624 0 : return "sorting dead tuples";
4625 0 : case PROGRESS_BTREE_PHASE_LEAF_LOAD:
4626 0 : return "loading tuples in tree";
4627 0 : default:
4628 0 : return NULL;
4629 : }
4630 : }
4631 :
4632 : /*
4633 : * _bt_truncate() -- create tuple without unneeded suffix attributes.
4634 : *
4635 : * Returns truncated pivot index tuple allocated in caller's memory context,
4636 : * with key attributes copied from caller's firstright argument. If rel is
4637 : * an INCLUDE index, non-key attributes will definitely be truncated away,
4638 : * since they're not part of the key space. More aggressive suffix
4639 : * truncation can take place when it's clear that the returned tuple does not
4640 : * need one or more suffix key attributes. We only need to keep firstright
4641 : * attributes up to and including the first non-lastleft-equal attribute.
4642 : * Caller's insertion scankey is used to compare the tuples; the scankey's
4643 : * argument values are not considered here.
4644 : *
4645 : * Note that returned tuple's t_tid offset will hold the number of attributes
4646 : * present, so the original item pointer offset is not represented. Caller
4647 : * should only change truncated tuple's downlink. Note also that truncated
4648 : * key attributes are treated as containing "minus infinity" values by
4649 : * _bt_compare().
4650 : *
4651 : * In the worst case (when a heap TID must be appended to distinguish lastleft
4652 : * from firstright), the size of the returned tuple is the size of firstright
4653 : * plus the size of an additional MAXALIGN()'d item pointer. This guarantee
4654 : * is important, since callers need to stay under the 1/3 of a page
4655 : * restriction on tuple size. If this routine is ever taught to truncate
4656 : * within an attribute/datum, it will need to avoid returning an enlarged
4657 : * tuple to caller when truncation + TOAST compression ends up enlarging the
4658 : * final datum.
4659 : */
4660 : IndexTuple
4661 60534 : _bt_truncate(Relation rel, IndexTuple lastleft, IndexTuple firstright,
4662 : BTScanInsert itup_key)
4663 : {
4664 60534 : TupleDesc itupdesc = RelationGetDescr(rel);
4665 60534 : int16 nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
4666 : int keepnatts;
4667 : IndexTuple pivot;
4668 : IndexTuple tidpivot;
4669 : ItemPointer pivotheaptid;
4670 : Size newsize;
4671 :
4672 : /*
4673 : * We should only ever truncate non-pivot tuples from leaf pages. It's
4674 : * never okay to truncate when splitting an internal page.
4675 : */
4676 : Assert(!BTreeTupleIsPivot(lastleft) && !BTreeTupleIsPivot(firstright));
4677 :
4678 : /* Determine how many attributes must be kept in truncated tuple */
4679 60534 : keepnatts = _bt_keep_natts(rel, lastleft, firstright, itup_key);
4680 :
4681 : #ifdef DEBUG_NO_TRUNCATE
4682 : /* Force truncation to be ineffective for testing purposes */
4683 : keepnatts = nkeyatts + 1;
4684 : #endif
4685 :
4686 60534 : pivot = index_truncate_tuple(itupdesc, firstright,
4687 : Min(keepnatts, nkeyatts));
4688 :
4689 60534 : if (BTreeTupleIsPosting(pivot))
4690 : {
4691 : /*
4692 : * index_truncate_tuple() just returns a straight copy of firstright
4693 : * when it has no attributes to truncate. When that happens, we may
4694 : * need to truncate away a posting list here instead.
4695 : */
4696 : Assert(keepnatts == nkeyatts || keepnatts == nkeyatts + 1);
4697 : Assert(IndexRelationGetNumberOfAttributes(rel) == nkeyatts);
4698 1302 : pivot->t_info &= ~INDEX_SIZE_MASK;
4699 1302 : pivot->t_info |= MAXALIGN(BTreeTupleGetPostingOffset(firstright));
4700 : }
4701 :
4702 : /*
4703 : * If there is a distinguishing key attribute within pivot tuple, we're
4704 : * done
4705 : */
4706 60534 : if (keepnatts <= nkeyatts)
4707 : {
4708 59432 : BTreeTupleSetNAtts(pivot, keepnatts, false);
4709 59432 : return pivot;
4710 : }
4711 :
4712 : /*
4713 : * We have to store a heap TID in the new pivot tuple, since no non-TID
4714 : * key attribute value in firstright distinguishes the right side of the
4715 : * split from the left side. nbtree conceptualizes this case as an
4716 : * inability to truncate away any key attributes, since heap TID is
4717 : * treated as just another key attribute (despite lacking a pg_attribute
4718 : * entry).
4719 : *
4720 : * Use enlarged space that holds a copy of pivot. We need the extra space
4721 : * to store a heap TID at the end (using the special pivot tuple
4722 : * representation). Note that the original pivot already has firstright's
4723 : * possible posting list/non-key attribute values removed at this point.
4724 : */
4725 1102 : newsize = MAXALIGN(IndexTupleSize(pivot)) + MAXALIGN(sizeof(ItemPointerData));
4726 1102 : tidpivot = palloc0(newsize);
4727 1102 : memcpy(tidpivot, pivot, MAXALIGN(IndexTupleSize(pivot)));
4728 : /* Cannot leak memory here */
4729 1102 : pfree(pivot);
4730 :
4731 : /*
4732 : * Store all of firstright's key attribute values plus a tiebreaker heap
4733 : * TID value in enlarged pivot tuple
4734 : */
4735 1102 : tidpivot->t_info &= ~INDEX_SIZE_MASK;
4736 1102 : tidpivot->t_info |= newsize;
4737 1102 : BTreeTupleSetNAtts(tidpivot, nkeyatts, true);
4738 1102 : pivotheaptid = BTreeTupleGetHeapTID(tidpivot);
4739 :
4740 : /*
4741 : * Lehman & Yao use lastleft as the leaf high key in all cases, but don't
4742 : * consider suffix truncation. It seems like a good idea to follow that
4743 : * example in cases where no truncation takes place -- use lastleft's heap
4744 : * TID. (This is also the closest value to negative infinity that's
4745 : * legally usable.)
4746 : */
4747 1102 : ItemPointerCopy(BTreeTupleGetMaxHeapTID(lastleft), pivotheaptid);
4748 :
4749 : /*
4750 : * We're done. Assert() that heap TID invariants hold before returning.
4751 : *
4752 : * Lehman and Yao require that the downlink to the right page, which is to
4753 : * be inserted into the parent page in the second phase of a page split be
4754 : * a strict lower bound on items on the right page, and a non-strict upper
4755 : * bound for items on the left page. Assert that heap TIDs follow these
4756 : * invariants, since a heap TID value is apparently needed as a
4757 : * tiebreaker.
4758 : */
4759 : #ifndef DEBUG_NO_TRUNCATE
4760 : Assert(ItemPointerCompare(BTreeTupleGetMaxHeapTID(lastleft),
4761 : BTreeTupleGetHeapTID(firstright)) < 0);
4762 : Assert(ItemPointerCompare(pivotheaptid,
4763 : BTreeTupleGetHeapTID(lastleft)) >= 0);
4764 : Assert(ItemPointerCompare(pivotheaptid,
4765 : BTreeTupleGetHeapTID(firstright)) < 0);
4766 : #else
4767 :
4768 : /*
4769 : * Those invariants aren't guaranteed to hold for lastleft + firstright
4770 : * heap TID attribute values when they're considered here only because
4771 : * DEBUG_NO_TRUNCATE is defined (a heap TID is probably not actually
4772 : * needed as a tiebreaker). DEBUG_NO_TRUNCATE must therefore use a heap
4773 : * TID value that always works as a strict lower bound for items to the
4774 : * right. In particular, it must avoid using firstright's leading key
4775 : * attribute values along with lastleft's heap TID value when lastleft's
4776 : * TID happens to be greater than firstright's TID.
4777 : */
4778 : ItemPointerCopy(BTreeTupleGetHeapTID(firstright), pivotheaptid);
4779 :
4780 : /*
4781 : * Pivot heap TID should never be fully equal to firstright. Note that
4782 : * the pivot heap TID will still end up equal to lastleft's heap TID when
4783 : * that's the only usable value.
4784 : */
4785 : ItemPointerSetOffsetNumber(pivotheaptid,
4786 : OffsetNumberPrev(ItemPointerGetOffsetNumber(pivotheaptid)));
4787 : Assert(ItemPointerCompare(pivotheaptid,
4788 : BTreeTupleGetHeapTID(firstright)) < 0);
4789 : #endif
4790 :
4791 1102 : return tidpivot;
4792 : }
4793 :
4794 : /*
4795 : * _bt_keep_natts - how many key attributes to keep when truncating.
4796 : *
4797 : * Caller provides two tuples that enclose a split point. Caller's insertion
4798 : * scankey is used to compare the tuples; the scankey's argument values are
4799 : * not considered here.
4800 : *
4801 : * This can return a number of attributes that is one greater than the
4802 : * number of key attributes for the index relation. This indicates that the
4803 : * caller must use a heap TID as a unique-ifier in new pivot tuple.
4804 : */
4805 : static int
4806 60534 : _bt_keep_natts(Relation rel, IndexTuple lastleft, IndexTuple firstright,
4807 : BTScanInsert itup_key)
4808 : {
4809 60534 : int nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
4810 60534 : TupleDesc itupdesc = RelationGetDescr(rel);
4811 : int keepnatts;
4812 : ScanKey scankey;
4813 :
4814 : /*
4815 : * _bt_compare() treats truncated key attributes as having the value minus
4816 : * infinity, which would break searches within !heapkeyspace indexes. We
4817 : * must still truncate away non-key attribute values, though.
4818 : */
4819 60534 : if (!itup_key->heapkeyspace)
4820 0 : return nkeyatts;
4821 :
4822 60534 : scankey = itup_key->scankeys;
4823 60534 : keepnatts = 1;
4824 73750 : for (int attnum = 1; attnum <= nkeyatts; attnum++, scankey++)
4825 : {
4826 : Datum datum1,
4827 : datum2;
4828 : bool isNull1,
4829 : isNull2;
4830 :
4831 72648 : datum1 = index_getattr(lastleft, attnum, itupdesc, &isNull1);
4832 72648 : datum2 = index_getattr(firstright, attnum, itupdesc, &isNull2);
4833 :
4834 72648 : if (isNull1 != isNull2)
4835 59432 : break;
4836 :
4837 145266 : if (!isNull1 &&
4838 72618 : DatumGetInt32(FunctionCall2Coll(&scankey->sk_func,
4839 : scankey->sk_collation,
4840 : datum1,
4841 : datum2)) != 0)
4842 59432 : break;
4843 :
4844 13216 : keepnatts++;
4845 : }
4846 :
4847 : /*
4848 : * Assert that _bt_keep_natts_fast() agrees with us in passing. This is
4849 : * expected in an allequalimage index.
4850 : */
4851 : Assert(!itup_key->allequalimage ||
4852 : keepnatts == _bt_keep_natts_fast(rel, lastleft, firstright));
4853 :
4854 60534 : return keepnatts;
4855 : }
4856 :
4857 : /*
4858 : * _bt_keep_natts_fast - fast bitwise variant of _bt_keep_natts.
4859 : *
4860 : * This is exported so that a candidate split point can have its effect on
4861 : * suffix truncation inexpensively evaluated ahead of time when finding a
4862 : * split location. A naive bitwise approach to datum comparisons is used to
4863 : * save cycles.
4864 : *
4865 : * The approach taken here usually provides the same answer as _bt_keep_natts
4866 : * will (for the same pair of tuples from a heapkeyspace index), since the
4867 : * majority of btree opclasses can never indicate that two datums are equal
4868 : * unless they're bitwise equal after detoasting. When an index only has
4869 : * "equal image" columns, routine is guaranteed to give the same result as
4870 : * _bt_keep_natts would.
4871 : *
4872 : * Callers can rely on the fact that attributes considered equal here are
4873 : * definitely also equal according to _bt_keep_natts, even when the index uses
4874 : * an opclass or collation that is not "allequalimage"/deduplication-safe.
4875 : * This weaker guarantee is good enough for nbtsplitloc.c caller, since false
4876 : * negatives generally only have the effect of making leaf page splits use a
4877 : * more balanced split point.
4878 : */
4879 : int
4880 12749216 : _bt_keep_natts_fast(Relation rel, IndexTuple lastleft, IndexTuple firstright)
4881 : {
4882 12749216 : TupleDesc itupdesc = RelationGetDescr(rel);
4883 12749216 : int keysz = IndexRelationGetNumberOfKeyAttributes(rel);
4884 : int keepnatts;
4885 :
4886 12749216 : keepnatts = 1;
4887 21218590 : for (int attnum = 1; attnum <= keysz; attnum++)
4888 : {
4889 : Datum datum1,
4890 : datum2;
4891 : bool isNull1,
4892 : isNull2;
4893 : CompactAttribute *att;
4894 :
4895 18936086 : datum1 = index_getattr(lastleft, attnum, itupdesc, &isNull1);
4896 18936086 : datum2 = index_getattr(firstright, attnum, itupdesc, &isNull2);
4897 18936086 : att = TupleDescCompactAttr(itupdesc, attnum - 1);
4898 :
4899 18936086 : if (isNull1 != isNull2)
4900 10466712 : break;
4901 :
4902 18935936 : if (!isNull1 &&
4903 18888880 : !datum_image_eq(datum1, datum2, att->attbyval, att->attlen))
4904 10466562 : break;
4905 :
4906 8469374 : keepnatts++;
4907 : }
4908 :
4909 12749216 : return keepnatts;
4910 : }
4911 :
4912 : /*
4913 : * _bt_check_natts() -- Verify tuple has expected number of attributes.
4914 : *
4915 : * Returns value indicating if the expected number of attributes were found
4916 : * for a particular offset on page. This can be used as a general purpose
4917 : * sanity check.
4918 : *
4919 : * Testing a tuple directly with BTreeTupleGetNAtts() should generally be
4920 : * preferred to calling here. That's usually more convenient, and is always
4921 : * more explicit. Call here instead when offnum's tuple may be a negative
4922 : * infinity tuple that uses the pre-v11 on-disk representation, or when a low
4923 : * context check is appropriate. This routine is as strict as possible about
4924 : * what is expected on each version of btree.
4925 : */
4926 : bool
4927 4039696 : _bt_check_natts(Relation rel, bool heapkeyspace, Page page, OffsetNumber offnum)
4928 : {
4929 4039696 : int16 natts = IndexRelationGetNumberOfAttributes(rel);
4930 4039696 : int16 nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
4931 4039696 : BTPageOpaque opaque = BTPageGetOpaque(page);
4932 : IndexTuple itup;
4933 : int tupnatts;
4934 :
4935 : /*
4936 : * We cannot reliably test a deleted or half-dead page, since they have
4937 : * dummy high keys
4938 : */
4939 4039696 : if (P_IGNORE(opaque))
4940 0 : return true;
4941 :
4942 : Assert(offnum >= FirstOffsetNumber &&
4943 : offnum <= PageGetMaxOffsetNumber(page));
4944 :
4945 4039696 : itup = (IndexTuple) PageGetItem(page, PageGetItemId(page, offnum));
4946 4039696 : tupnatts = BTreeTupleGetNAtts(itup, rel);
4947 :
4948 : /* !heapkeyspace indexes do not support deduplication */
4949 4039696 : if (!heapkeyspace && BTreeTupleIsPosting(itup))
4950 0 : return false;
4951 :
4952 : /* Posting list tuples should never have "pivot heap TID" bit set */
4953 4039696 : if (BTreeTupleIsPosting(itup) &&
4954 22126 : (ItemPointerGetOffsetNumberNoCheck(&itup->t_tid) &
4955 : BT_PIVOT_HEAP_TID_ATTR) != 0)
4956 0 : return false;
4957 :
4958 : /* INCLUDE indexes do not support deduplication */
4959 4039696 : if (natts != nkeyatts && BTreeTupleIsPosting(itup))
4960 0 : return false;
4961 :
4962 4039696 : if (P_ISLEAF(opaque))
4963 : {
4964 4025374 : if (offnum >= P_FIRSTDATAKEY(opaque))
4965 : {
4966 : /*
4967 : * Non-pivot tuple should never be explicitly marked as a pivot
4968 : * tuple
4969 : */
4970 4012172 : if (BTreeTupleIsPivot(itup))
4971 0 : return false;
4972 :
4973 : /*
4974 : * Leaf tuples that are not the page high key (non-pivot tuples)
4975 : * should never be truncated. (Note that tupnatts must have been
4976 : * inferred, even with a posting list tuple, because only pivot
4977 : * tuples store tupnatts directly.)
4978 : */
4979 4012172 : return tupnatts == natts;
4980 : }
4981 : else
4982 : {
4983 : /*
4984 : * Rightmost page doesn't contain a page high key, so tuple was
4985 : * checked above as ordinary leaf tuple
4986 : */
4987 : Assert(!P_RIGHTMOST(opaque));
4988 :
4989 : /*
4990 : * !heapkeyspace high key tuple contains only key attributes. Note
4991 : * that tupnatts will only have been explicitly represented in
4992 : * !heapkeyspace indexes that happen to have non-key attributes.
4993 : */
4994 13202 : if (!heapkeyspace)
4995 0 : return tupnatts == nkeyatts;
4996 :
4997 : /* Use generic heapkeyspace pivot tuple handling */
4998 : }
4999 : }
5000 : else /* !P_ISLEAF(opaque) */
5001 : {
5002 14322 : if (offnum == P_FIRSTDATAKEY(opaque))
5003 : {
5004 : /*
5005 : * The first tuple on any internal page (possibly the first after
5006 : * its high key) is its negative infinity tuple. Negative
5007 : * infinity tuples are always truncated to zero attributes. They
5008 : * are a particular kind of pivot tuple.
5009 : */
5010 1114 : if (heapkeyspace)
5011 1114 : return tupnatts == 0;
5012 :
5013 : /*
5014 : * The number of attributes won't be explicitly represented if the
5015 : * negative infinity tuple was generated during a page split that
5016 : * occurred with a version of Postgres before v11. There must be
5017 : * a problem when there is an explicit representation that is
5018 : * non-zero, or when there is no explicit representation and the
5019 : * tuple is evidently not a pre-pg_upgrade tuple.
5020 : *
5021 : * Prior to v11, downlinks always had P_HIKEY as their offset.
5022 : * Accept that as an alternative indication of a valid
5023 : * !heapkeyspace negative infinity tuple.
5024 : */
5025 0 : return tupnatts == 0 ||
5026 0 : ItemPointerGetOffsetNumber(&(itup->t_tid)) == P_HIKEY;
5027 : }
5028 : else
5029 : {
5030 : /*
5031 : * !heapkeyspace downlink tuple with separator key contains only
5032 : * key attributes. Note that tupnatts will only have been
5033 : * explicitly represented in !heapkeyspace indexes that happen to
5034 : * have non-key attributes.
5035 : */
5036 13208 : if (!heapkeyspace)
5037 0 : return tupnatts == nkeyatts;
5038 :
5039 : /* Use generic heapkeyspace pivot tuple handling */
5040 : }
5041 : }
5042 :
5043 : /* Handle heapkeyspace pivot tuples (excluding minus infinity items) */
5044 : Assert(heapkeyspace);
5045 :
5046 : /*
5047 : * Explicit representation of the number of attributes is mandatory with
5048 : * heapkeyspace index pivot tuples, regardless of whether or not there are
5049 : * non-key attributes.
5050 : */
5051 26410 : if (!BTreeTupleIsPivot(itup))
5052 0 : return false;
5053 :
5054 : /* Pivot tuple should not use posting list representation (redundant) */
5055 26410 : if (BTreeTupleIsPosting(itup))
5056 0 : return false;
5057 :
5058 : /*
5059 : * Heap TID is a tiebreaker key attribute, so it cannot be untruncated
5060 : * when any other key attribute is truncated
5061 : */
5062 26410 : if (BTreeTupleGetHeapTID(itup) != NULL && tupnatts != nkeyatts)
5063 0 : return false;
5064 :
5065 : /*
5066 : * Pivot tuple must have at least one untruncated key attribute (minus
5067 : * infinity pivot tuples are the only exception). Pivot tuples can never
5068 : * represent that there is a value present for a key attribute that
5069 : * exceeds pg_index.indnkeyatts for the index.
5070 : */
5071 26410 : return tupnatts > 0 && tupnatts <= nkeyatts;
5072 : }
5073 :
5074 : /*
5075 : *
5076 : * _bt_check_third_page() -- check whether tuple fits on a btree page at all.
5077 : *
5078 : * We actually need to be able to fit three items on every page, so restrict
5079 : * any one item to 1/3 the per-page available space. Note that itemsz should
5080 : * not include the ItemId overhead.
5081 : *
5082 : * It might be useful to apply TOAST methods rather than throw an error here.
5083 : * Using out of line storage would break assumptions made by suffix truncation
5084 : * and by contrib/amcheck, though.
5085 : */
5086 : void
5087 264 : _bt_check_third_page(Relation rel, Relation heap, bool needheaptidspace,
5088 : Page page, IndexTuple newtup)
5089 : {
5090 : Size itemsz;
5091 : BTPageOpaque opaque;
5092 :
5093 264 : itemsz = MAXALIGN(IndexTupleSize(newtup));
5094 :
5095 : /* Double check item size against limit */
5096 264 : if (itemsz <= BTMaxItemSize(page))
5097 0 : return;
5098 :
5099 : /*
5100 : * Tuple is probably too large to fit on page, but it's possible that the
5101 : * index uses version 2 or version 3, or that page is an internal page, in
5102 : * which case a slightly higher limit applies.
5103 : */
5104 264 : if (!needheaptidspace && itemsz <= BTMaxItemSizeNoHeapTid(page))
5105 264 : return;
5106 :
5107 : /*
5108 : * Internal page insertions cannot fail here, because that would mean that
5109 : * an earlier leaf level insertion that should have failed didn't
5110 : */
5111 0 : opaque = BTPageGetOpaque(page);
5112 0 : if (!P_ISLEAF(opaque))
5113 0 : elog(ERROR, "cannot insert oversized tuple of size %zu on internal page of index \"%s\"",
5114 : itemsz, RelationGetRelationName(rel));
5115 :
5116 0 : ereport(ERROR,
5117 : (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
5118 : errmsg("index row size %zu exceeds btree version %u maximum %zu for index \"%s\"",
5119 : itemsz,
5120 : needheaptidspace ? BTREE_VERSION : BTREE_NOVAC_VERSION,
5121 : needheaptidspace ? BTMaxItemSize(page) :
5122 : BTMaxItemSizeNoHeapTid(page),
5123 : RelationGetRelationName(rel)),
5124 : errdetail("Index row references tuple (%u,%u) in relation \"%s\".",
5125 : ItemPointerGetBlockNumber(BTreeTupleGetHeapTID(newtup)),
5126 : ItemPointerGetOffsetNumber(BTreeTupleGetHeapTID(newtup)),
5127 : RelationGetRelationName(heap)),
5128 : errhint("Values larger than 1/3 of a buffer page cannot be indexed.\n"
5129 : "Consider a function index of an MD5 hash of the value, "
5130 : "or use full text indexing."),
5131 : errtableconstraint(heap, RelationGetRelationName(rel))));
5132 : }
5133 :
5134 : /*
5135 : * Are all attributes in rel "equality is image equality" attributes?
5136 : *
5137 : * We use each attribute's BTEQUALIMAGE_PROC opclass procedure. If any
5138 : * opclass either lacks a BTEQUALIMAGE_PROC procedure or returns false, we
5139 : * return false; otherwise we return true.
5140 : *
5141 : * Returned boolean value is stored in index metapage during index builds.
5142 : * Deduplication can only be used when we return true.
5143 : */
5144 : bool
5145 55674 : _bt_allequalimage(Relation rel, bool debugmessage)
5146 : {
5147 55674 : bool allequalimage = true;
5148 :
5149 : /* INCLUDE indexes can never support deduplication */
5150 55674 : if (IndexRelationGetNumberOfAttributes(rel) !=
5151 55674 : IndexRelationGetNumberOfKeyAttributes(rel))
5152 272 : return false;
5153 :
5154 146332 : for (int i = 0; i < IndexRelationGetNumberOfKeyAttributes(rel); i++)
5155 : {
5156 91432 : Oid opfamily = rel->rd_opfamily[i];
5157 91432 : Oid opcintype = rel->rd_opcintype[i];
5158 91432 : Oid collation = rel->rd_indcollation[i];
5159 : Oid equalimageproc;
5160 :
5161 91432 : equalimageproc = get_opfamily_proc(opfamily, opcintype, opcintype,
5162 : BTEQUALIMAGE_PROC);
5163 :
5164 : /*
5165 : * If there is no BTEQUALIMAGE_PROC then deduplication is assumed to
5166 : * be unsafe. Otherwise, actually call proc and see what it says.
5167 : */
5168 91432 : if (!OidIsValid(equalimageproc) ||
5169 90974 : !DatumGetBool(OidFunctionCall1Coll(equalimageproc, collation,
5170 : ObjectIdGetDatum(opcintype))))
5171 : {
5172 502 : allequalimage = false;
5173 502 : break;
5174 : }
5175 : }
5176 :
5177 55402 : if (debugmessage)
5178 : {
5179 47328 : if (allequalimage)
5180 46826 : elog(DEBUG1, "index \"%s\" can safely use deduplication",
5181 : RelationGetRelationName(rel));
5182 : else
5183 502 : elog(DEBUG1, "index \"%s\" cannot use deduplication",
5184 : RelationGetRelationName(rel));
5185 : }
5186 :
5187 55402 : return allequalimage;
5188 : }
|
