Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * nbtutils.c
4 : * Utility code for Postgres btree implementation.
5 : *
6 : * Portions Copyright (c) 1996-2025, 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 "miscadmin.h"
25 : #include "utils/datum.h"
26 : #include "utils/lsyscache.h"
27 : #include "utils/rel.h"
28 :
29 :
30 : #define LOOK_AHEAD_REQUIRED_RECHECKS 3
31 : #define LOOK_AHEAD_DEFAULT_DISTANCE 5
32 : #define NSKIPADVANCES_THRESHOLD 3
33 :
34 : static inline int32 _bt_compare_array_skey(FmgrInfo *orderproc,
35 : Datum tupdatum, bool tupnull,
36 : Datum arrdatum, ScanKey cur);
37 : static void _bt_binsrch_skiparray_skey(bool cur_elem_trig, ScanDirection dir,
38 : Datum tupdatum, bool tupnull,
39 : BTArrayKeyInfo *array, ScanKey cur,
40 : int32 *set_elem_result);
41 : static void _bt_skiparray_set_element(Relation rel, ScanKey skey, BTArrayKeyInfo *array,
42 : int32 set_elem_result, Datum tupdatum, bool tupnull);
43 : static void _bt_skiparray_set_isnull(Relation rel, ScanKey skey, BTArrayKeyInfo *array);
44 : static void _bt_array_set_low_or_high(Relation rel, ScanKey skey,
45 : BTArrayKeyInfo *array, bool low_not_high);
46 : static bool _bt_array_decrement(Relation rel, ScanKey skey, BTArrayKeyInfo *array);
47 : static bool _bt_array_increment(Relation rel, ScanKey skey, BTArrayKeyInfo *array);
48 : static bool _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir,
49 : bool *skip_array_set);
50 : static bool _bt_tuple_before_array_skeys(IndexScanDesc scan, ScanDirection dir,
51 : IndexTuple tuple, TupleDesc tupdesc, int tupnatts,
52 : bool readpagetup, int sktrig, bool *scanBehind);
53 : static bool _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
54 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
55 : int sktrig, bool sktrig_required);
56 : #ifdef USE_ASSERT_CHECKING
57 : static bool _bt_verify_keys_with_arraykeys(IndexScanDesc scan);
58 : #endif
59 : static bool _bt_oppodir_checkkeys(IndexScanDesc scan, ScanDirection dir,
60 : IndexTuple finaltup);
61 : static bool _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
62 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
63 : bool advancenonrequired, bool forcenonrequired,
64 : bool *continuescan, int *ikey);
65 : static bool _bt_rowcompare_cmpresult(ScanKey subkey, int cmpresult);
66 : static bool _bt_check_rowcompare(ScanKey skey,
67 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
68 : ScanDirection dir, bool forcenonrequired, bool *continuescan);
69 : static void _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
70 : int tupnatts, TupleDesc tupdesc);
71 : static int _bt_keep_natts(Relation rel, IndexTuple lastleft,
72 : IndexTuple firstright, BTScanInsert itup_key);
73 :
74 :
75 : /*
76 : * _bt_mkscankey
77 : * Build an insertion scan key that contains comparison data from itup
78 : * as well as comparator routines appropriate to the key datatypes.
79 : *
80 : * The result is intended for use with _bt_compare() and _bt_truncate().
81 : * Callers that don't need to fill out the insertion scankey arguments
82 : * (e.g. they use an ad-hoc comparison routine, or only need a scankey
83 : * for _bt_truncate()) can pass a NULL index tuple. The scankey will
84 : * be initialized as if an "all truncated" pivot tuple was passed
85 : * instead.
86 : *
87 : * Note that we may occasionally have to share lock the metapage to
88 : * determine whether or not the keys in the index are expected to be
89 : * unique (i.e. if this is a "heapkeyspace" index). We assume a
90 : * heapkeyspace index when caller passes a NULL tuple, allowing index
91 : * build callers to avoid accessing the non-existent metapage. We
92 : * also assume that the index is _not_ allequalimage when a NULL tuple
93 : * is passed; CREATE INDEX callers call _bt_allequalimage() to set the
94 : * field themselves.
95 : */
96 : BTScanInsert
97 11832224 : _bt_mkscankey(Relation rel, IndexTuple itup)
98 : {
99 : BTScanInsert key;
100 : ScanKey skey;
101 : TupleDesc itupdesc;
102 : int indnkeyatts;
103 : int16 *indoption;
104 : int tupnatts;
105 : int i;
106 :
107 11832224 : itupdesc = RelationGetDescr(rel);
108 11832224 : indnkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
109 11832224 : indoption = rel->rd_indoption;
110 11832224 : tupnatts = itup ? BTreeTupleGetNAtts(itup, rel) : 0;
111 :
112 : Assert(tupnatts <= IndexRelationGetNumberOfAttributes(rel));
113 :
114 : /*
115 : * We'll execute search using scan key constructed on key columns.
116 : * Truncated attributes and non-key attributes are omitted from the final
117 : * scan key.
118 : */
119 11832224 : key = palloc(offsetof(BTScanInsertData, scankeys) +
120 11832224 : sizeof(ScanKeyData) * indnkeyatts);
121 11832224 : if (itup)
122 11689168 : _bt_metaversion(rel, &key->heapkeyspace, &key->allequalimage);
123 : else
124 : {
125 : /* Utility statement callers can set these fields themselves */
126 143056 : key->heapkeyspace = true;
127 143056 : key->allequalimage = false;
128 : }
129 11832224 : key->anynullkeys = false; /* initial assumption */
130 11832224 : key->nextkey = false; /* usual case, required by btinsert */
131 11832224 : key->backward = false; /* usual case, required by btinsert */
132 11832224 : key->keysz = Min(indnkeyatts, tupnatts);
133 11832224 : key->scantid = key->heapkeyspace && itup ?
134 23664448 : BTreeTupleGetHeapTID(itup) : NULL;
135 11832224 : skey = key->scankeys;
136 32020532 : for (i = 0; i < indnkeyatts; i++)
137 : {
138 : FmgrInfo *procinfo;
139 : Datum arg;
140 : bool null;
141 : int flags;
142 :
143 : /*
144 : * We can use the cached (default) support procs since no cross-type
145 : * comparison can be needed.
146 : */
147 20188308 : procinfo = index_getprocinfo(rel, i + 1, BTORDER_PROC);
148 :
149 : /*
150 : * Key arguments built from truncated attributes (or when caller
151 : * provides no tuple) are defensively represented as NULL values. They
152 : * should never be used.
153 : */
154 20188308 : if (i < tupnatts)
155 19931760 : arg = index_getattr(itup, i + 1, itupdesc, &null);
156 : else
157 : {
158 256548 : arg = (Datum) 0;
159 256548 : null = true;
160 : }
161 20188308 : flags = (null ? SK_ISNULL : 0) | (indoption[i] << SK_BT_INDOPTION_SHIFT);
162 20188308 : ScanKeyEntryInitializeWithInfo(&skey[i],
163 : flags,
164 20188308 : (AttrNumber) (i + 1),
165 : InvalidStrategy,
166 : InvalidOid,
167 20188308 : rel->rd_indcollation[i],
168 : procinfo,
169 : arg);
170 : /* Record if any key attribute is NULL (or truncated) */
171 20188308 : if (null)
172 277196 : key->anynullkeys = true;
173 : }
174 :
175 : /*
176 : * In NULLS NOT DISTINCT mode, we pretend that there are no null keys, so
177 : * that full uniqueness check is done.
178 : */
179 11832224 : if (rel->rd_index->indnullsnotdistinct)
180 186 : key->anynullkeys = false;
181 :
182 11832224 : return key;
183 : }
184 :
185 : /*
186 : * free a retracement stack made by _bt_search.
187 : */
188 : void
189 23348576 : _bt_freestack(BTStack stack)
190 : {
191 : BTStack ostack;
192 :
193 42772736 : while (stack != NULL)
194 : {
195 19424160 : ostack = stack;
196 19424160 : stack = stack->bts_parent;
197 19424160 : pfree(ostack);
198 : }
199 23348576 : }
200 :
201 : /*
202 : * _bt_compare_array_skey() -- apply array comparison function
203 : *
204 : * Compares caller's tuple attribute value to a scan key/array element.
205 : * Helper function used during binary searches of SK_SEARCHARRAY arrays.
206 : *
207 : * This routine returns:
208 : * <0 if tupdatum < arrdatum;
209 : * 0 if tupdatum == arrdatum;
210 : * >0 if tupdatum > arrdatum.
211 : *
212 : * This is essentially the same interface as _bt_compare: both functions
213 : * compare the value that they're searching for to a binary search pivot.
214 : * However, unlike _bt_compare, this function's "tuple argument" comes first,
215 : * while its "array/scankey argument" comes second.
216 : */
217 : static inline int32
218 468430 : _bt_compare_array_skey(FmgrInfo *orderproc,
219 : Datum tupdatum, bool tupnull,
220 : Datum arrdatum, ScanKey cur)
221 : {
222 468430 : int32 result = 0;
223 :
224 : Assert(cur->sk_strategy == BTEqualStrategyNumber);
225 : Assert(!(cur->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL)));
226 :
227 468430 : if (tupnull) /* NULL tupdatum */
228 : {
229 228 : if (cur->sk_flags & SK_ISNULL)
230 132 : result = 0; /* NULL "=" NULL */
231 96 : else if (cur->sk_flags & SK_BT_NULLS_FIRST)
232 0 : result = -1; /* NULL "<" NOT_NULL */
233 : else
234 96 : result = 1; /* NULL ">" NOT_NULL */
235 : }
236 468202 : else if (cur->sk_flags & SK_ISNULL) /* NOT_NULL tupdatum, NULL arrdatum */
237 : {
238 30540 : if (cur->sk_flags & SK_BT_NULLS_FIRST)
239 54 : result = 1; /* NOT_NULL ">" NULL */
240 : else
241 30486 : result = -1; /* NOT_NULL "<" NULL */
242 : }
243 : else
244 : {
245 : /*
246 : * Like _bt_compare, we need to be careful of cross-type comparisons,
247 : * so the left value has to be the value that came from an index tuple
248 : */
249 437662 : result = DatumGetInt32(FunctionCall2Coll(orderproc, cur->sk_collation,
250 : tupdatum, arrdatum));
251 :
252 : /*
253 : * We flip the sign by following the obvious rule: flip whenever the
254 : * column is a DESC column.
255 : *
256 : * _bt_compare does it the wrong way around (flip when *ASC*) in order
257 : * to compensate for passing its orderproc arguments backwards. We
258 : * don't need to play these games because we find it natural to pass
259 : * tupdatum as the left value (and arrdatum as the right value).
260 : */
261 437662 : if (cur->sk_flags & SK_BT_DESC)
262 45498 : INVERT_COMPARE_RESULT(result);
263 : }
264 :
265 468430 : return result;
266 : }
267 :
268 : /*
269 : * _bt_binsrch_array_skey() -- Binary search for next matching array key
270 : *
271 : * Returns an index to the first array element >= caller's tupdatum argument.
272 : * This convention is more natural for forwards scan callers, but that can't
273 : * really matter to backwards scan callers. Both callers require handling for
274 : * the case where the match we return is < tupdatum, and symmetric handling
275 : * for the case where our best match is > tupdatum.
276 : *
277 : * Also sets *set_elem_result to the result _bt_compare_array_skey returned
278 : * when we used it to compare the matching array element to tupdatum/tupnull.
279 : *
280 : * cur_elem_trig indicates if array advancement was triggered by this array's
281 : * scan key, and that the array is for a required scan key. We can apply this
282 : * information to find the next matching array element in the current scan
283 : * direction using far fewer comparisons (fewer on average, compared to naive
284 : * binary search). This scheme takes advantage of an important property of
285 : * required arrays: required arrays always advance in lockstep with the index
286 : * scan's progress through the index's key space.
287 : */
288 : int
289 32132 : _bt_binsrch_array_skey(FmgrInfo *orderproc,
290 : bool cur_elem_trig, ScanDirection dir,
291 : Datum tupdatum, bool tupnull,
292 : BTArrayKeyInfo *array, ScanKey cur,
293 : int32 *set_elem_result)
294 : {
295 32132 : int low_elem = 0,
296 32132 : mid_elem = -1,
297 32132 : high_elem = array->num_elems - 1,
298 32132 : result = 0;
299 : Datum arrdatum;
300 :
301 : Assert(cur->sk_flags & SK_SEARCHARRAY);
302 : Assert(!(cur->sk_flags & SK_BT_SKIP));
303 : Assert(!(cur->sk_flags & SK_ISNULL)); /* SAOP arrays never have NULLs */
304 : Assert(cur->sk_strategy == BTEqualStrategyNumber);
305 :
306 32132 : if (cur_elem_trig)
307 : {
308 : Assert(!ScanDirectionIsNoMovement(dir));
309 : Assert(cur->sk_flags & SK_BT_REQFWD);
310 :
311 : /*
312 : * When the scan key that triggered array advancement is a required
313 : * array scan key, it is now certain that the current array element
314 : * (plus all prior elements relative to the current scan direction)
315 : * cannot possibly be at or ahead of the corresponding tuple value.
316 : * (_bt_checkkeys must have called _bt_tuple_before_array_skeys, which
317 : * makes sure this is true as a condition of advancing the arrays.)
318 : *
319 : * This makes it safe to exclude array elements up to and including
320 : * the former-current array element from our search.
321 : *
322 : * Separately, when array advancement was triggered by a required scan
323 : * key, the array element immediately after the former-current element
324 : * is often either an exact tupdatum match, or a "close by" near-match
325 : * (a near-match tupdatum is one whose key space falls _between_ the
326 : * former-current and new-current array elements). We'll detect both
327 : * cases via an optimistic comparison of the new search lower bound
328 : * (or new search upper bound in the case of backwards scans).
329 : */
330 31814 : if (ScanDirectionIsForward(dir))
331 : {
332 31754 : low_elem = array->cur_elem + 1; /* old cur_elem exhausted */
333 :
334 : /* Compare prospective new cur_elem (also the new lower bound) */
335 31754 : if (high_elem >= low_elem)
336 : {
337 23692 : arrdatum = array->elem_values[low_elem];
338 23692 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
339 : arrdatum, cur);
340 :
341 23692 : if (result <= 0)
342 : {
343 : /* Optimistic comparison optimization worked out */
344 23606 : *set_elem_result = result;
345 23606 : return low_elem;
346 : }
347 86 : mid_elem = low_elem;
348 86 : low_elem++; /* this cur_elem exhausted, too */
349 : }
350 :
351 8148 : if (high_elem < low_elem)
352 : {
353 : /* Caller needs to perform "beyond end" array advancement */
354 8068 : *set_elem_result = 1;
355 8068 : return high_elem;
356 : }
357 : }
358 : else
359 : {
360 60 : high_elem = array->cur_elem - 1; /* old cur_elem exhausted */
361 :
362 : /* Compare prospective new cur_elem (also the new upper bound) */
363 60 : if (high_elem >= low_elem)
364 : {
365 42 : arrdatum = array->elem_values[high_elem];
366 42 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
367 : arrdatum, cur);
368 :
369 42 : if (result >= 0)
370 : {
371 : /* Optimistic comparison optimization worked out */
372 30 : *set_elem_result = result;
373 30 : return high_elem;
374 : }
375 12 : mid_elem = high_elem;
376 12 : high_elem--; /* this cur_elem exhausted, too */
377 : }
378 :
379 30 : if (high_elem < low_elem)
380 : {
381 : /* Caller needs to perform "beyond end" array advancement */
382 30 : *set_elem_result = -1;
383 30 : return low_elem;
384 : }
385 : }
386 : }
387 :
388 698 : while (high_elem > low_elem)
389 : {
390 438 : mid_elem = low_elem + ((high_elem - low_elem) / 2);
391 438 : arrdatum = array->elem_values[mid_elem];
392 :
393 438 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
394 : arrdatum, cur);
395 :
396 438 : if (result == 0)
397 : {
398 : /*
399 : * It's safe to quit as soon as we see an equal array element.
400 : * This often saves an extra comparison or two...
401 : */
402 138 : low_elem = mid_elem;
403 138 : break;
404 : }
405 :
406 300 : if (result > 0)
407 270 : low_elem = mid_elem + 1;
408 : else
409 30 : high_elem = mid_elem;
410 : }
411 :
412 : /*
413 : * ...but our caller also cares about how its searched-for tuple datum
414 : * compares to the low_elem datum. Must always set *set_elem_result with
415 : * the result of that comparison specifically.
416 : */
417 398 : if (low_elem != mid_elem)
418 242 : result = _bt_compare_array_skey(orderproc, tupdatum, tupnull,
419 242 : array->elem_values[low_elem], cur);
420 :
421 398 : *set_elem_result = result;
422 :
423 398 : return low_elem;
424 : }
425 :
426 : /*
427 : * _bt_binsrch_skiparray_skey() -- "Binary search" within a skip array
428 : *
429 : * Does not return an index into the array, since skip arrays don't really
430 : * contain elements (they generate their array elements procedurally instead).
431 : * Our interface matches that of _bt_binsrch_array_skey in every other way.
432 : *
433 : * Sets *set_elem_result just like _bt_binsrch_array_skey would with a true
434 : * array. The value 0 indicates that tupdatum/tupnull is within the range of
435 : * the skip array. We return -1 when tupdatum/tupnull is lower that any value
436 : * within the range of the array, and 1 when it is higher than every value.
437 : * Caller should pass *set_elem_result to _bt_skiparray_set_element to advance
438 : * the array.
439 : *
440 : * cur_elem_trig indicates if array advancement was triggered by this array's
441 : * scan key. We use this to optimize-away comparisons that are known by our
442 : * caller to be unnecessary from context, just like _bt_binsrch_array_skey.
443 : */
444 : static void
445 167124 : _bt_binsrch_skiparray_skey(bool cur_elem_trig, ScanDirection dir,
446 : Datum tupdatum, bool tupnull,
447 : BTArrayKeyInfo *array, ScanKey cur,
448 : int32 *set_elem_result)
449 : {
450 : Assert(cur->sk_flags & SK_BT_SKIP);
451 : Assert(cur->sk_flags & SK_SEARCHARRAY);
452 : Assert(cur->sk_flags & SK_BT_REQFWD);
453 : Assert(array->num_elems == -1);
454 : Assert(!ScanDirectionIsNoMovement(dir));
455 :
456 167124 : if (array->null_elem)
457 : {
458 : Assert(!array->low_compare && !array->high_compare);
459 :
460 140888 : *set_elem_result = 0;
461 140888 : return;
462 : }
463 :
464 26236 : if (tupnull) /* NULL tupdatum */
465 : {
466 24 : if (cur->sk_flags & SK_BT_NULLS_FIRST)
467 0 : *set_elem_result = -1; /* NULL "<" NOT_NULL */
468 : else
469 24 : *set_elem_result = 1; /* NULL ">" NOT_NULL */
470 24 : return;
471 : }
472 :
473 : /*
474 : * Array inequalities determine whether tupdatum is within the range of
475 : * caller's skip array
476 : */
477 26212 : *set_elem_result = 0;
478 26212 : if (ScanDirectionIsForward(dir))
479 : {
480 : /*
481 : * Evaluate low_compare first (unless cur_elem_trig tells us that it
482 : * cannot possibly fail to be satisfied), then evaluate high_compare
483 : */
484 26164 : if (!cur_elem_trig && array->low_compare &&
485 724 : !DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
486 724 : array->low_compare->sk_collation,
487 : tupdatum,
488 724 : array->low_compare->sk_argument)))
489 0 : *set_elem_result = -1;
490 26164 : else if (array->high_compare &&
491 10072 : !DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
492 10072 : array->high_compare->sk_collation,
493 : tupdatum,
494 10072 : array->high_compare->sk_argument)))
495 6406 : *set_elem_result = 1;
496 : }
497 : else
498 : {
499 : /*
500 : * Evaluate high_compare first (unless cur_elem_trig tells us that it
501 : * cannot possibly fail to be satisfied), then evaluate low_compare
502 : */
503 48 : if (!cur_elem_trig && array->high_compare &&
504 6 : !DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
505 6 : array->high_compare->sk_collation,
506 : tupdatum,
507 6 : array->high_compare->sk_argument)))
508 0 : *set_elem_result = 1;
509 48 : else if (array->low_compare &&
510 24 : !DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
511 24 : array->low_compare->sk_collation,
512 : tupdatum,
513 24 : array->low_compare->sk_argument)))
514 0 : *set_elem_result = -1;
515 : }
516 :
517 : /*
518 : * Assert that any keys that were assumed to be satisfied already (due to
519 : * caller passing cur_elem_trig=true) really are satisfied as expected
520 : */
521 : #ifdef USE_ASSERT_CHECKING
522 : if (cur_elem_trig)
523 : {
524 : if (ScanDirectionIsForward(dir) && array->low_compare)
525 : Assert(DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
526 : array->low_compare->sk_collation,
527 : tupdatum,
528 : array->low_compare->sk_argument)));
529 :
530 : if (ScanDirectionIsBackward(dir) && array->high_compare)
531 : Assert(DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
532 : array->high_compare->sk_collation,
533 : tupdatum,
534 : array->high_compare->sk_argument)));
535 : }
536 : #endif
537 : }
538 :
539 : /*
540 : * _bt_skiparray_set_element() -- Set skip array scan key's sk_argument
541 : *
542 : * Caller passes set_elem_result returned by _bt_binsrch_skiparray_skey for
543 : * caller's tupdatum/tupnull.
544 : *
545 : * We copy tupdatum/tupnull into skey's sk_argument iff set_elem_result == 0.
546 : * Otherwise, we set skey to either the lowest or highest value that's within
547 : * the range of caller's skip array (whichever is the best available match to
548 : * tupdatum/tupnull that is still within the range of the skip array according
549 : * to _bt_binsrch_skiparray_skey/set_elem_result).
550 : */
551 : static void
552 155424 : _bt_skiparray_set_element(Relation rel, ScanKey skey, BTArrayKeyInfo *array,
553 : int32 set_elem_result, Datum tupdatum, bool tupnull)
554 : {
555 : Assert(skey->sk_flags & SK_BT_SKIP);
556 : Assert(skey->sk_flags & SK_SEARCHARRAY);
557 :
558 155424 : if (set_elem_result)
559 : {
560 : /* tupdatum/tupnull is out of the range of the skip array */
561 : Assert(!array->null_elem);
562 :
563 642 : _bt_array_set_low_or_high(rel, skey, array, set_elem_result < 0);
564 642 : return;
565 : }
566 :
567 : /* Advance skip array to tupdatum (or tupnull) value */
568 154782 : if (unlikely(tupnull))
569 : {
570 36 : _bt_skiparray_set_isnull(rel, skey, array);
571 36 : return;
572 : }
573 :
574 : /* Free memory previously allocated for sk_argument if needed */
575 154746 : if (!array->attbyval && skey->sk_argument)
576 78780 : pfree(DatumGetPointer(skey->sk_argument));
577 :
578 : /* tupdatum becomes new sk_argument/new current element */
579 154746 : skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL |
580 : SK_BT_MINVAL | SK_BT_MAXVAL |
581 : SK_BT_NEXT | SK_BT_PRIOR);
582 154746 : skey->sk_argument = datumCopy(tupdatum, array->attbyval, array->attlen);
583 : }
584 :
585 : /*
586 : * _bt_skiparray_set_isnull() -- set skip array scan key to NULL
587 : */
588 : static void
589 48 : _bt_skiparray_set_isnull(Relation rel, ScanKey skey, BTArrayKeyInfo *array)
590 : {
591 : Assert(skey->sk_flags & SK_BT_SKIP);
592 : Assert(skey->sk_flags & SK_SEARCHARRAY);
593 : Assert(array->null_elem && !array->low_compare && !array->high_compare);
594 :
595 : /* Free memory previously allocated for sk_argument if needed */
596 48 : if (!array->attbyval && skey->sk_argument)
597 6 : pfree(DatumGetPointer(skey->sk_argument));
598 :
599 : /* NULL becomes new sk_argument/new current element */
600 48 : skey->sk_argument = (Datum) 0;
601 48 : skey->sk_flags &= ~(SK_BT_MINVAL | SK_BT_MAXVAL |
602 : SK_BT_NEXT | SK_BT_PRIOR);
603 48 : skey->sk_flags |= (SK_SEARCHNULL | SK_ISNULL);
604 48 : }
605 :
606 : /*
607 : * _bt_start_array_keys() -- Initialize array keys at start of a scan
608 : *
609 : * Set up the cur_elem counters and fill in the first sk_argument value for
610 : * each array scankey.
611 : */
612 : void
613 81660 : _bt_start_array_keys(IndexScanDesc scan, ScanDirection dir)
614 : {
615 81660 : Relation rel = scan->indexRelation;
616 81660 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
617 :
618 : Assert(so->numArrayKeys);
619 : Assert(so->qual_ok);
620 :
621 163944 : for (int i = 0; i < so->numArrayKeys; i++)
622 : {
623 82284 : BTArrayKeyInfo *array = &so->arrayKeys[i];
624 82284 : ScanKey skey = &so->keyData[array->scan_key];
625 :
626 : Assert(skey->sk_flags & SK_SEARCHARRAY);
627 :
628 82284 : _bt_array_set_low_or_high(rel, skey, array,
629 : ScanDirectionIsForward(dir));
630 : }
631 81660 : so->scanBehind = so->oppositeDirCheck = false; /* reset */
632 81660 : }
633 :
634 : /*
635 : * _bt_array_set_low_or_high() -- Set array scan key to lowest/highest element
636 : *
637 : * Caller also passes associated scan key, which will have its argument set to
638 : * the lowest/highest array value in passing.
639 : */
640 : static void
641 93734 : _bt_array_set_low_or_high(Relation rel, ScanKey skey, BTArrayKeyInfo *array,
642 : bool low_not_high)
643 : {
644 : Assert(skey->sk_flags & SK_SEARCHARRAY);
645 :
646 93734 : if (array->num_elems != -1)
647 : {
648 : /* set low or high element for SAOP array */
649 84672 : int set_elem = 0;
650 :
651 : Assert(!(skey->sk_flags & SK_BT_SKIP));
652 :
653 84672 : if (!low_not_high)
654 8300 : set_elem = array->num_elems - 1;
655 :
656 : /*
657 : * Just copy over array datum (only skip arrays require freeing and
658 : * allocating memory for sk_argument)
659 : */
660 84672 : array->cur_elem = set_elem;
661 84672 : skey->sk_argument = array->elem_values[set_elem];
662 :
663 84672 : return;
664 : }
665 :
666 : /* set low or high element for skip array */
667 : Assert(skey->sk_flags & SK_BT_SKIP);
668 : Assert(array->num_elems == -1);
669 :
670 : /* Free memory previously allocated for sk_argument if needed */
671 9062 : if (!array->attbyval && skey->sk_argument)
672 1874 : pfree(DatumGetPointer(skey->sk_argument));
673 :
674 : /* Reset flags */
675 9062 : skey->sk_argument = (Datum) 0;
676 9062 : skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL |
677 : SK_BT_MINVAL | SK_BT_MAXVAL |
678 : SK_BT_NEXT | SK_BT_PRIOR);
679 :
680 9062 : if (array->null_elem &&
681 7242 : (low_not_high == ((skey->sk_flags & SK_BT_NULLS_FIRST) != 0)))
682 : {
683 : /* Requested element (either lowest or highest) has the value NULL */
684 966 : skey->sk_flags |= (SK_SEARCHNULL | SK_ISNULL);
685 : }
686 8096 : else if (low_not_high)
687 : {
688 : /* Setting array to lowest element (according to low_compare) */
689 7376 : skey->sk_flags |= SK_BT_MINVAL;
690 : }
691 : else
692 : {
693 : /* Setting array to highest element (according to high_compare) */
694 720 : skey->sk_flags |= SK_BT_MAXVAL;
695 : }
696 : }
697 :
698 : /*
699 : * _bt_array_decrement() -- decrement array scan key's sk_argument
700 : *
701 : * Return value indicates whether caller's array was successfully decremented.
702 : * Cannot decrement an array whose current element is already the first one.
703 : */
704 : static bool
705 912 : _bt_array_decrement(Relation rel, ScanKey skey, BTArrayKeyInfo *array)
706 : {
707 912 : bool uflow = false;
708 : Datum dec_sk_argument;
709 :
710 : Assert(skey->sk_flags & SK_SEARCHARRAY);
711 : Assert(!(skey->sk_flags & (SK_BT_MAXVAL | SK_BT_NEXT | SK_BT_PRIOR)));
712 :
713 : /* SAOP array? */
714 912 : if (array->num_elems != -1)
715 : {
716 : Assert(!(skey->sk_flags & (SK_BT_SKIP | SK_BT_MINVAL | SK_BT_MAXVAL)));
717 36 : if (array->cur_elem > 0)
718 : {
719 : /*
720 : * Just decrement current element, and assign its datum to skey
721 : * (only skip arrays need us to free existing sk_argument memory)
722 : */
723 6 : array->cur_elem--;
724 6 : skey->sk_argument = array->elem_values[array->cur_elem];
725 :
726 : /* Successfully decremented array */
727 6 : return true;
728 : }
729 :
730 : /* Cannot decrement to before first array element */
731 30 : return false;
732 : }
733 :
734 : /* Nope, this is a skip array */
735 : Assert(skey->sk_flags & SK_BT_SKIP);
736 :
737 : /*
738 : * The sentinel value that represents the minimum value within the range
739 : * of a skip array (often just -inf) is never decrementable
740 : */
741 876 : if (skey->sk_flags & SK_BT_MINVAL)
742 0 : return false;
743 :
744 : /*
745 : * When the current array element is NULL, and the lowest sorting value in
746 : * the index is also NULL, we cannot decrement before first array element
747 : */
748 876 : if ((skey->sk_flags & SK_ISNULL) && (skey->sk_flags & SK_BT_NULLS_FIRST))
749 0 : return false;
750 :
751 : /*
752 : * Opclasses without skip support "decrement" the scan key's current
753 : * element by setting the PRIOR flag. The true prior value is determined
754 : * by repositioning to the last index tuple < existing sk_argument/current
755 : * array element. Note that this works in the usual way when the scan key
756 : * is already marked ISNULL (i.e. when the current element is NULL).
757 : */
758 876 : if (!array->sksup)
759 : {
760 : /* Successfully "decremented" array */
761 12 : skey->sk_flags |= SK_BT_PRIOR;
762 12 : return true;
763 : }
764 :
765 : /*
766 : * Opclasses with skip support directly decrement sk_argument
767 : */
768 864 : if (skey->sk_flags & SK_ISNULL)
769 : {
770 : Assert(!(skey->sk_flags & SK_BT_NULLS_FIRST));
771 :
772 : /*
773 : * Existing sk_argument/array element is NULL (for an IS NULL qual).
774 : *
775 : * "Decrement" from NULL to the high_elem value provided by opclass
776 : * skip support routine.
777 : */
778 6 : skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL);
779 12 : skey->sk_argument = datumCopy(array->sksup->high_elem,
780 6 : array->attbyval, array->attlen);
781 6 : return true;
782 : }
783 :
784 : /*
785 : * Ask opclass support routine to provide decremented copy of existing
786 : * non-NULL sk_argument
787 : */
788 858 : dec_sk_argument = array->sksup->decrement(rel, skey->sk_argument, &uflow);
789 858 : if (unlikely(uflow))
790 : {
791 : /* dec_sk_argument has undefined value (so no pfree) */
792 0 : if (array->null_elem && (skey->sk_flags & SK_BT_NULLS_FIRST))
793 : {
794 0 : _bt_skiparray_set_isnull(rel, skey, array);
795 :
796 : /* Successfully "decremented" array to NULL */
797 0 : return true;
798 : }
799 :
800 : /* Cannot decrement to before first array element */
801 0 : return false;
802 : }
803 :
804 : /*
805 : * Successfully decremented sk_argument to a non-NULL value. Make sure
806 : * that the decremented value is still within the range of the array.
807 : */
808 858 : if (array->low_compare &&
809 12 : !DatumGetBool(FunctionCall2Coll(&array->low_compare->sk_func,
810 12 : array->low_compare->sk_collation,
811 : dec_sk_argument,
812 12 : array->low_compare->sk_argument)))
813 : {
814 : /* Keep existing sk_argument after all */
815 6 : if (!array->attbyval)
816 0 : pfree(DatumGetPointer(dec_sk_argument));
817 :
818 : /* Cannot decrement to before first array element */
819 6 : return false;
820 : }
821 :
822 : /* Accept value returned by opclass decrement callback */
823 852 : if (!array->attbyval && skey->sk_argument)
824 0 : pfree(DatumGetPointer(skey->sk_argument));
825 852 : skey->sk_argument = dec_sk_argument;
826 :
827 : /* Successfully decremented array */
828 852 : return true;
829 : }
830 :
831 : /*
832 : * _bt_array_increment() -- increment array scan key's sk_argument
833 : *
834 : * Return value indicates whether caller's array was successfully incremented.
835 : * Cannot increment an array whose current element is already the final one.
836 : */
837 : static bool
838 31422 : _bt_array_increment(Relation rel, ScanKey skey, BTArrayKeyInfo *array)
839 : {
840 31422 : bool oflow = false;
841 : Datum inc_sk_argument;
842 :
843 : Assert(skey->sk_flags & SK_SEARCHARRAY);
844 : Assert(!(skey->sk_flags & (SK_BT_MINVAL | SK_BT_NEXT | SK_BT_PRIOR)));
845 :
846 : /* SAOP array? */
847 31422 : if (array->num_elems != -1)
848 : {
849 : Assert(!(skey->sk_flags & (SK_BT_SKIP | SK_BT_MINVAL | SK_BT_MAXVAL)));
850 8324 : if (array->cur_elem < array->num_elems - 1)
851 : {
852 : /*
853 : * Just increment current element, and assign its datum to skey
854 : * (only skip arrays need us to free existing sk_argument memory)
855 : */
856 38 : array->cur_elem++;
857 38 : skey->sk_argument = array->elem_values[array->cur_elem];
858 :
859 : /* Successfully incremented array */
860 38 : return true;
861 : }
862 :
863 : /* Cannot increment past final array element */
864 8286 : return false;
865 : }
866 :
867 : /* Nope, this is a skip array */
868 : Assert(skey->sk_flags & SK_BT_SKIP);
869 :
870 : /*
871 : * The sentinel value that represents the maximum value within the range
872 : * of a skip array (often just +inf) is never incrementable
873 : */
874 23098 : if (skey->sk_flags & SK_BT_MAXVAL)
875 642 : return false;
876 :
877 : /*
878 : * When the current array element is NULL, and the highest sorting value
879 : * in the index is also NULL, we cannot increment past the final element
880 : */
881 22456 : if ((skey->sk_flags & SK_ISNULL) && !(skey->sk_flags & SK_BT_NULLS_FIRST))
882 438 : return false;
883 :
884 : /*
885 : * Opclasses without skip support "increment" the scan key's current
886 : * element by setting the NEXT flag. The true next value is determined by
887 : * repositioning to the first index tuple > existing sk_argument/current
888 : * array element. Note that this works in the usual way when the scan key
889 : * is already marked ISNULL (i.e. when the current element is NULL).
890 : */
891 22018 : if (!array->sksup)
892 : {
893 : /* Successfully "incremented" array */
894 14726 : skey->sk_flags |= SK_BT_NEXT;
895 14726 : return true;
896 : }
897 :
898 : /*
899 : * Opclasses with skip support directly increment sk_argument
900 : */
901 7292 : if (skey->sk_flags & SK_ISNULL)
902 : {
903 : Assert(skey->sk_flags & SK_BT_NULLS_FIRST);
904 :
905 : /*
906 : * Existing sk_argument/array element is NULL (for an IS NULL qual).
907 : *
908 : * "Increment" from NULL to the low_elem value provided by opclass
909 : * skip support routine.
910 : */
911 36 : skey->sk_flags &= ~(SK_SEARCHNULL | SK_ISNULL);
912 72 : skey->sk_argument = datumCopy(array->sksup->low_elem,
913 36 : array->attbyval, array->attlen);
914 36 : return true;
915 : }
916 :
917 : /*
918 : * Ask opclass support routine to provide incremented copy of existing
919 : * non-NULL sk_argument
920 : */
921 7256 : inc_sk_argument = array->sksup->increment(rel, skey->sk_argument, &oflow);
922 7256 : if (unlikely(oflow))
923 : {
924 : /* inc_sk_argument has undefined value (so no pfree) */
925 30 : if (array->null_elem && !(skey->sk_flags & SK_BT_NULLS_FIRST))
926 : {
927 12 : _bt_skiparray_set_isnull(rel, skey, array);
928 :
929 : /* Successfully "incremented" array to NULL */
930 12 : return true;
931 : }
932 :
933 : /* Cannot increment past final array element */
934 18 : return false;
935 : }
936 :
937 : /*
938 : * Successfully incremented sk_argument to a non-NULL value. Make sure
939 : * that the incremented value is still within the range of the array.
940 : */
941 7226 : if (array->high_compare &&
942 42 : !DatumGetBool(FunctionCall2Coll(&array->high_compare->sk_func,
943 42 : array->high_compare->sk_collation,
944 : inc_sk_argument,
945 42 : array->high_compare->sk_argument)))
946 : {
947 : /* Keep existing sk_argument after all */
948 12 : if (!array->attbyval)
949 0 : pfree(DatumGetPointer(inc_sk_argument));
950 :
951 : /* Cannot increment past final array element */
952 12 : return false;
953 : }
954 :
955 : /* Accept value returned by opclass increment callback */
956 7214 : if (!array->attbyval && skey->sk_argument)
957 0 : pfree(DatumGetPointer(skey->sk_argument));
958 7214 : skey->sk_argument = inc_sk_argument;
959 :
960 : /* Successfully incremented array */
961 7214 : return true;
962 : }
963 :
964 : /*
965 : * _bt_advance_array_keys_increment() -- Advance to next set of array elements
966 : *
967 : * Advances the array keys by a single increment in the current scan
968 : * direction. When there are multiple array keys this can roll over from the
969 : * lowest order array to higher order arrays.
970 : *
971 : * Returns true if there is another set of values to consider, false if not.
972 : * On true result, the scankeys are initialized with the next set of values.
973 : * On false result, the scankeys stay the same, and the array keys are not
974 : * advanced (every array remains at its final element for scan direction).
975 : */
976 : static bool
977 31194 : _bt_advance_array_keys_increment(IndexScanDesc scan, ScanDirection dir,
978 : bool *skip_array_set)
979 : {
980 31194 : Relation rel = scan->indexRelation;
981 31194 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
982 :
983 : /*
984 : * We must advance the last array key most quickly, since it will
985 : * correspond to the lowest-order index column among the available
986 : * qualifications
987 : */
988 40626 : for (int i = so->numArrayKeys - 1; i >= 0; i--)
989 : {
990 32334 : BTArrayKeyInfo *array = &so->arrayKeys[i];
991 32334 : ScanKey skey = &so->keyData[array->scan_key];
992 :
993 32334 : if (array->num_elems == -1)
994 23974 : *skip_array_set = true;
995 :
996 32334 : if (ScanDirectionIsForward(dir))
997 : {
998 31422 : if (_bt_array_increment(rel, skey, array))
999 22026 : return true;
1000 : }
1001 : else
1002 : {
1003 912 : if (_bt_array_decrement(rel, skey, array))
1004 876 : return true;
1005 : }
1006 :
1007 : /*
1008 : * Couldn't increment (or decrement) array. Handle array roll over.
1009 : *
1010 : * Start over at the array's lowest sorting value (or its highest
1011 : * value, for backward scans)...
1012 : */
1013 9432 : _bt_array_set_low_or_high(rel, skey, array,
1014 : ScanDirectionIsForward(dir));
1015 :
1016 : /* ...then increment (or decrement) next most significant array */
1017 : }
1018 :
1019 : /*
1020 : * The array keys are now exhausted.
1021 : *
1022 : * Restore the array keys to the state they were in immediately before we
1023 : * were called. This ensures that the arrays only ever ratchet in the
1024 : * current scan direction.
1025 : *
1026 : * Without this, scans could overlook matching tuples when the scan
1027 : * direction gets reversed just before btgettuple runs out of items to
1028 : * return, but just after _bt_readpage prepares all the items from the
1029 : * scan's final page in so->currPos. When we're on the final page it is
1030 : * typical for so->currPos to get invalidated once btgettuple finally
1031 : * returns false, which'll effectively invalidate the scan's array keys.
1032 : * That hasn't happened yet, though -- and in general it may never happen.
1033 : */
1034 8292 : _bt_start_array_keys(scan, -dir);
1035 :
1036 8292 : return false;
1037 : }
1038 :
1039 : /*
1040 : * _bt_tuple_before_array_skeys() -- too early to advance required arrays?
1041 : *
1042 : * We always compare the tuple using the current array keys (which we assume
1043 : * are already set in so->keyData[]). readpagetup indicates if tuple is the
1044 : * scan's current _bt_readpage-wise tuple.
1045 : *
1046 : * readpagetup callers must only call here when _bt_check_compare already set
1047 : * continuescan=false. We help these callers deal with _bt_check_compare's
1048 : * inability to distinguish between the < and > cases (it uses equality
1049 : * operator scan keys, whereas we use 3-way ORDER procs). These callers pass
1050 : * a _bt_check_compare-set sktrig value that indicates which scan key
1051 : * triggered the call (!readpagetup callers just pass us sktrig=0 instead).
1052 : * This information allows us to avoid wastefully checking earlier scan keys
1053 : * that were already deemed to have been satisfied inside _bt_check_compare.
1054 : *
1055 : * Returns false when caller's tuple is >= the current required equality scan
1056 : * keys (or <=, in the case of backwards scans). This happens to readpagetup
1057 : * callers when the scan has reached the point of needing its array keys
1058 : * advanced; caller will need to advance required and non-required arrays at
1059 : * scan key offsets >= sktrig, plus scan keys < sktrig iff sktrig rolls over.
1060 : * (When we return false to readpagetup callers, tuple can only be == current
1061 : * required equality scan keys when caller's sktrig indicates that the arrays
1062 : * need to be advanced due to an unsatisfied required inequality key trigger.)
1063 : *
1064 : * Returns true when caller passes a tuple that is < the current set of
1065 : * equality keys for the most significant non-equal required scan key/column
1066 : * (or > the keys, during backwards scans). This happens to readpagetup
1067 : * callers when tuple is still before the start of matches for the scan's
1068 : * required equality strategy scan keys. (sktrig can't have indicated that an
1069 : * inequality strategy scan key wasn't satisfied in _bt_check_compare when we
1070 : * return true. In fact, we automatically return false when passed such an
1071 : * inequality sktrig by readpagetup callers -- _bt_check_compare's initial
1072 : * continuescan=false doesn't really need to be confirmed here by us.)
1073 : *
1074 : * !readpagetup callers optionally pass us *scanBehind, which tracks whether
1075 : * any missing truncated attributes might have affected array advancement
1076 : * (compared to what would happen if it was shown the first non-pivot tuple on
1077 : * the page to the right of caller's finaltup/high key tuple instead). It's
1078 : * only possible that we'll set *scanBehind to true when caller passes us a
1079 : * pivot tuple (with truncated -inf attributes) that we return false for.
1080 : */
1081 : static bool
1082 326420 : _bt_tuple_before_array_skeys(IndexScanDesc scan, ScanDirection dir,
1083 : IndexTuple tuple, TupleDesc tupdesc, int tupnatts,
1084 : bool readpagetup, int sktrig, bool *scanBehind)
1085 : {
1086 326420 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1087 :
1088 : Assert(so->numArrayKeys);
1089 : Assert(so->numberOfKeys);
1090 : Assert(sktrig == 0 || readpagetup);
1091 : Assert(!readpagetup || scanBehind == NULL);
1092 :
1093 326420 : if (scanBehind)
1094 84626 : *scanBehind = false;
1095 :
1096 329522 : for (int ikey = sktrig; ikey < so->numberOfKeys; ikey++)
1097 : {
1098 328870 : ScanKey cur = so->keyData + ikey;
1099 : Datum tupdatum;
1100 : bool tupnull;
1101 : int32 result;
1102 :
1103 : /* readpagetup calls require one ORDER proc comparison (at most) */
1104 : Assert(!readpagetup || ikey == sktrig);
1105 :
1106 : /*
1107 : * Once we reach a non-required scan key, we're completely done.
1108 : *
1109 : * Note: we deliberately don't consider the scan direction here.
1110 : * _bt_advance_array_keys caller requires that we track *scanBehind
1111 : * without concern for scan direction.
1112 : */
1113 328870 : if ((cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD)) == 0)
1114 : {
1115 : Assert(!readpagetup);
1116 : Assert(ikey > sktrig || ikey == 0);
1117 325768 : return false;
1118 : }
1119 :
1120 328870 : if (cur->sk_attno > tupnatts)
1121 : {
1122 : Assert(!readpagetup);
1123 :
1124 : /*
1125 : * When we reach a high key's truncated attribute, assume that the
1126 : * tuple attribute's value is >= the scan's equality constraint
1127 : * scan keys (but set *scanBehind to let interested callers know
1128 : * that a truncated attribute might have affected our answer).
1129 : */
1130 34 : if (scanBehind)
1131 34 : *scanBehind = true;
1132 :
1133 34 : return false;
1134 : }
1135 :
1136 : /*
1137 : * Deal with inequality strategy scan keys that _bt_check_compare set
1138 : * continuescan=false for
1139 : */
1140 328836 : if (cur->sk_strategy != BTEqualStrategyNumber)
1141 : {
1142 : /*
1143 : * When _bt_check_compare indicated that a required inequality
1144 : * scan key wasn't satisfied, there's no need to verify anything;
1145 : * caller always calls _bt_advance_array_keys with this sktrig.
1146 : */
1147 618 : if (readpagetup)
1148 348 : return false;
1149 :
1150 : /*
1151 : * Otherwise we can't give up, since we must check all required
1152 : * scan keys (required in either direction) in order to correctly
1153 : * track *scanBehind for caller
1154 : */
1155 270 : continue;
1156 : }
1157 :
1158 328218 : tupdatum = index_getattr(tuple, cur->sk_attno, tupdesc, &tupnull);
1159 :
1160 328218 : if (likely(!(cur->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL))))
1161 : {
1162 : /* Scankey has a valid/comparable sk_argument value */
1163 322808 : result = _bt_compare_array_skey(&so->orderProcs[ikey],
1164 : tupdatum, tupnull,
1165 : cur->sk_argument, cur);
1166 :
1167 322808 : if (result == 0)
1168 : {
1169 : /*
1170 : * Interpret result in a way that takes NEXT/PRIOR into
1171 : * account
1172 : */
1173 16804 : if (cur->sk_flags & SK_BT_NEXT)
1174 13942 : result = -1;
1175 2862 : else if (cur->sk_flags & SK_BT_PRIOR)
1176 30 : result = 1;
1177 :
1178 : Assert(result == 0 || (cur->sk_flags & SK_BT_SKIP));
1179 : }
1180 : }
1181 : else
1182 : {
1183 5410 : BTArrayKeyInfo *array = NULL;
1184 :
1185 : /*
1186 : * Current array element/array = scan key value is a sentinel
1187 : * value that represents the lowest (or highest) possible value
1188 : * that's still within the range of the array.
1189 : *
1190 : * Like _bt_first, we only see MINVAL keys during forwards scans
1191 : * (and similarly only see MAXVAL keys during backwards scans).
1192 : * Even if the scan's direction changes, we'll stop at some higher
1193 : * order key before we can ever reach any MAXVAL (or MINVAL) keys.
1194 : * (However, unlike _bt_first we _can_ get to keys marked either
1195 : * NEXT or PRIOR, regardless of the scan's current direction.)
1196 : */
1197 : Assert(ScanDirectionIsForward(dir) ?
1198 : !(cur->sk_flags & SK_BT_MAXVAL) :
1199 : !(cur->sk_flags & SK_BT_MINVAL));
1200 :
1201 : /*
1202 : * There are no valid sk_argument values in MINVAL/MAXVAL keys.
1203 : * Check if tupdatum is within the range of skip array instead.
1204 : */
1205 5926 : for (int arrayidx = 0; arrayidx < so->numArrayKeys; arrayidx++)
1206 : {
1207 5926 : array = &so->arrayKeys[arrayidx];
1208 5926 : if (array->scan_key == ikey)
1209 5410 : break;
1210 : }
1211 :
1212 5410 : _bt_binsrch_skiparray_skey(false, dir, tupdatum, tupnull,
1213 : array, cur, &result);
1214 :
1215 5410 : if (result == 0)
1216 : {
1217 : /*
1218 : * tupdatum satisfies both low_compare and high_compare, so
1219 : * it's time to advance the array keys.
1220 : *
1221 : * Note: It's possible that the skip array will "advance" from
1222 : * its MINVAL (or MAXVAL) representation to an alternative,
1223 : * logically equivalent representation of the same value: a
1224 : * representation where the = key gets a valid datum in its
1225 : * sk_argument. This is only possible when low_compare uses
1226 : * the >= strategy (or high_compare uses the <= strategy).
1227 : */
1228 5402 : return false;
1229 : }
1230 : }
1231 :
1232 : /*
1233 : * Does this comparison indicate that caller must _not_ advance the
1234 : * scan's arrays just yet?
1235 : */
1236 322816 : if ((ScanDirectionIsForward(dir) && result < 0) ||
1237 3252 : (ScanDirectionIsBackward(dir) && result > 0))
1238 60370 : return true;
1239 :
1240 : /*
1241 : * Does this comparison indicate that caller should now advance the
1242 : * scan's arrays? (Must be if we get here during a readpagetup call.)
1243 : */
1244 262446 : if (readpagetup || result != 0)
1245 : {
1246 : Assert(result != 0);
1247 259614 : return false;
1248 : }
1249 :
1250 : /*
1251 : * Inconclusive -- need to check later scan keys, too.
1252 : *
1253 : * This must be a finaltup precheck, or a call made from an assertion.
1254 : */
1255 : Assert(result == 0);
1256 : }
1257 :
1258 : Assert(!readpagetup);
1259 :
1260 652 : return false;
1261 : }
1262 :
1263 : /*
1264 : * _bt_start_prim_scan() -- start scheduled primitive index scan?
1265 : *
1266 : * Returns true if _bt_checkkeys scheduled another primitive index scan, just
1267 : * as the last one ended. Otherwise returns false, indicating that the array
1268 : * keys are now fully exhausted.
1269 : *
1270 : * Only call here during scans with one or more equality type array scan keys,
1271 : * after _bt_first or _bt_next return false.
1272 : */
1273 : bool
1274 88746 : _bt_start_prim_scan(IndexScanDesc scan, ScanDirection dir)
1275 : {
1276 88746 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1277 :
1278 : Assert(so->numArrayKeys);
1279 :
1280 88746 : so->scanBehind = so->oppositeDirCheck = false; /* reset */
1281 :
1282 : /*
1283 : * Array keys are advanced within _bt_checkkeys when the scan reaches the
1284 : * leaf level (more precisely, they're advanced when the scan reaches the
1285 : * end of each distinct set of array elements). This process avoids
1286 : * repeat access to leaf pages (across multiple primitive index scans) by
1287 : * advancing the scan's array keys when it allows the primitive index scan
1288 : * to find nearby matching tuples (or when it eliminates ranges of array
1289 : * key space that can't possibly be satisfied by any index tuple).
1290 : *
1291 : * _bt_checkkeys sets a simple flag variable to schedule another primitive
1292 : * index scan. The flag tells us what to do.
1293 : *
1294 : * We cannot rely on _bt_first always reaching _bt_checkkeys. There are
1295 : * various cases where that won't happen. For example, if the index is
1296 : * completely empty, then _bt_first won't call _bt_readpage/_bt_checkkeys.
1297 : * We also don't expect a call to _bt_checkkeys during searches for a
1298 : * non-existent value that happens to be lower/higher than any existing
1299 : * value in the index.
1300 : *
1301 : * We don't require special handling for these cases -- we don't need to
1302 : * be explicitly instructed to _not_ perform another primitive index scan.
1303 : * It's up to code under the control of _bt_first to always set the flag
1304 : * when another primitive index scan will be required.
1305 : *
1306 : * This works correctly, even with the tricky cases listed above, which
1307 : * all involve access to leaf pages "near the boundaries of the key space"
1308 : * (whether it's from a leftmost/rightmost page, or an imaginary empty
1309 : * leaf root page). If _bt_checkkeys cannot be reached by a primitive
1310 : * index scan for one set of array keys, then it also won't be reached for
1311 : * any later set ("later" in terms of the direction that we scan the index
1312 : * and advance the arrays). The array keys won't have advanced in these
1313 : * cases, but that's the correct behavior (even _bt_advance_array_keys
1314 : * won't always advance the arrays at the point they become "exhausted").
1315 : */
1316 88746 : if (so->needPrimScan)
1317 : {
1318 : /*
1319 : * Flag was set -- must call _bt_first again, which will reset the
1320 : * scan's needPrimScan flag
1321 : */
1322 17544 : return true;
1323 : }
1324 :
1325 : /* The top-level index scan ran out of tuples in this scan direction */
1326 71202 : if (scan->parallel_scan != NULL)
1327 30 : _bt_parallel_done(scan);
1328 :
1329 71202 : return false;
1330 : }
1331 :
1332 : /*
1333 : * _bt_advance_array_keys() -- Advance array elements using a tuple
1334 : *
1335 : * The scan always gets a new qual as a consequence of calling here (except
1336 : * when we determine that the top-level scan has run out of matching tuples).
1337 : * All later _bt_check_compare calls also use the same new qual that was first
1338 : * used here (at least until the next call here advances the keys once again).
1339 : * It's convenient to structure _bt_check_compare rechecks of caller's tuple
1340 : * (using the new qual) as one the steps of advancing the scan's array keys,
1341 : * so this function works as a wrapper around _bt_check_compare.
1342 : *
1343 : * Like _bt_check_compare, we'll set pstate.continuescan on behalf of the
1344 : * caller, and return a boolean indicating if caller's tuple satisfies the
1345 : * scan's new qual. But unlike _bt_check_compare, we set so->needPrimScan
1346 : * when we set continuescan=false, indicating if a new primitive index scan
1347 : * has been scheduled (otherwise, the top-level scan has run out of tuples in
1348 : * the current scan direction).
1349 : *
1350 : * Caller must use _bt_tuple_before_array_skeys to determine if the current
1351 : * place in the scan is >= the current array keys _before_ calling here.
1352 : * We're responsible for ensuring that caller's tuple is <= the newly advanced
1353 : * required array keys once we return. We try to find an exact match, but
1354 : * failing that we'll advance the array keys to whatever set of array elements
1355 : * comes next in the key space for the current scan direction. Required array
1356 : * keys "ratchet forwards" (or backwards). They can only advance as the scan
1357 : * itself advances through the index/key space.
1358 : *
1359 : * (The rules are the same for backwards scans, except that the operators are
1360 : * flipped: just replace the precondition's >= operator with a <=, and the
1361 : * postcondition's <= operator with a >=. In other words, just swap the
1362 : * precondition with the postcondition.)
1363 : *
1364 : * We also deal with "advancing" non-required arrays here (or arrays that are
1365 : * treated as non-required for the duration of a _bt_readpage call). Callers
1366 : * whose sktrig scan key is non-required specify sktrig_required=false. These
1367 : * calls are the only exception to the general rule about always advancing the
1368 : * required array keys (the scan may not even have a required array). These
1369 : * callers should just pass a NULL pstate (since there is never any question
1370 : * of stopping the scan). No call to _bt_tuple_before_array_skeys is required
1371 : * ahead of these calls (it's already clear that any required scan keys must
1372 : * be satisfied by caller's tuple).
1373 : *
1374 : * Note that we deal with non-array required equality strategy scan keys as
1375 : * degenerate single element arrays here. Obviously, they can never really
1376 : * advance in the way that real arrays can, but they must still affect how we
1377 : * advance real array scan keys (exactly like true array equality scan keys).
1378 : * We have to keep around a 3-way ORDER proc for these (using the "=" operator
1379 : * won't do), since in general whether the tuple is < or > _any_ unsatisfied
1380 : * required equality key influences how the scan's real arrays must advance.
1381 : *
1382 : * Note also that we may sometimes need to advance the array keys when the
1383 : * existing required array keys (and other required equality keys) are already
1384 : * an exact match for every corresponding value from caller's tuple. We must
1385 : * do this for inequalities that _bt_check_compare set continuescan=false for.
1386 : * They'll advance the array keys here, just like any other scan key that
1387 : * _bt_check_compare stops on. (This can even happen _after_ we advance the
1388 : * array keys, in which case we'll advance the array keys a second time. That
1389 : * way _bt_checkkeys caller always has its required arrays advance to the
1390 : * maximum possible extent that its tuple will allow.)
1391 : */
1392 : static bool
1393 201278 : _bt_advance_array_keys(IndexScanDesc scan, BTReadPageState *pstate,
1394 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
1395 : int sktrig, bool sktrig_required)
1396 : {
1397 201278 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
1398 201278 : Relation rel = scan->indexRelation;
1399 201278 : ScanDirection dir = so->currPos.dir;
1400 201278 : int arrayidx = 0;
1401 201278 : bool beyond_end_advance = false,
1402 201278 : skip_array_advanced = false,
1403 201278 : has_required_opposite_direction_only = false,
1404 201278 : all_required_satisfied = true,
1405 201278 : all_satisfied = true;
1406 :
1407 : Assert(!so->needPrimScan && !so->scanBehind && !so->oppositeDirCheck);
1408 : Assert(_bt_verify_keys_with_arraykeys(scan));
1409 :
1410 201278 : if (sktrig_required)
1411 : {
1412 : /*
1413 : * Precondition array state assertion
1414 : */
1415 : Assert(!_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc,
1416 : tupnatts, false, 0, NULL));
1417 :
1418 : /*
1419 : * Once we return we'll have a new set of required array keys, so
1420 : * reset state used by "look ahead" optimization
1421 : */
1422 192636 : pstate->rechecks = 0;
1423 192636 : pstate->targetdistance = 0;
1424 : }
1425 8642 : else if (sktrig < so->numberOfKeys - 1 &&
1426 8642 : !(so->keyData[so->numberOfKeys - 1].sk_flags & SK_SEARCHARRAY))
1427 : {
1428 8642 : int least_sign_ikey = so->numberOfKeys - 1;
1429 : bool continuescan;
1430 :
1431 : /*
1432 : * Optimization: perform a precheck of the least significant key
1433 : * during !sktrig_required calls when it isn't already our sktrig
1434 : * (provided the precheck key is not itself an array).
1435 : *
1436 : * When the precheck works out we'll avoid an expensive binary search
1437 : * of sktrig's array (plus any other arrays before least_sign_ikey).
1438 : */
1439 : Assert(so->keyData[sktrig].sk_flags & SK_SEARCHARRAY);
1440 8642 : if (!_bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, false,
1441 : false, &continuescan,
1442 : &least_sign_ikey))
1443 2354 : return false;
1444 : }
1445 :
1446 583740 : for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
1447 : {
1448 390582 : ScanKey cur = so->keyData + ikey;
1449 390582 : BTArrayKeyInfo *array = NULL;
1450 : Datum tupdatum;
1451 390582 : bool required = false,
1452 390582 : required_opposite_direction_only = false,
1453 : tupnull;
1454 : int32 result;
1455 390582 : int set_elem = 0;
1456 :
1457 390582 : if (cur->sk_strategy == BTEqualStrategyNumber)
1458 : {
1459 : /* Manage array state */
1460 342456 : if (cur->sk_flags & SK_SEARCHARRAY)
1461 : {
1462 209226 : array = &so->arrayKeys[arrayidx++];
1463 : Assert(array->scan_key == ikey);
1464 : }
1465 : }
1466 : else
1467 : {
1468 : /*
1469 : * Are any inequalities required in the opposite direction only
1470 : * present here?
1471 : */
1472 48126 : if (((ScanDirectionIsForward(dir) &&
1473 48126 : (cur->sk_flags & (SK_BT_REQBKWD))) ||
1474 0 : (ScanDirectionIsBackward(dir) &&
1475 0 : (cur->sk_flags & (SK_BT_REQFWD)))))
1476 15582 : has_required_opposite_direction_only =
1477 15582 : required_opposite_direction_only = true;
1478 : }
1479 :
1480 : /* Optimization: skip over known-satisfied scan keys */
1481 390582 : if (ikey < sktrig)
1482 76082 : continue;
1483 :
1484 374246 : if (cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))
1485 : {
1486 374246 : required = true;
1487 :
1488 374246 : if (cur->sk_attno > tupnatts)
1489 : {
1490 : /* Set this just like _bt_tuple_before_array_skeys */
1491 : Assert(sktrig < ikey);
1492 2282 : so->scanBehind = true;
1493 : }
1494 : }
1495 :
1496 : /*
1497 : * Handle a required non-array scan key that the initial call to
1498 : * _bt_check_compare indicated triggered array advancement, if any.
1499 : *
1500 : * The non-array scan key's strategy will be <, <=, or = during a
1501 : * forwards scan (or any one of =, >=, or > during a backwards scan).
1502 : * It follows that the corresponding tuple attribute's value must now
1503 : * be either > or >= the scan key value (for backwards scans it must
1504 : * be either < or <= that value).
1505 : *
1506 : * If this is a required equality strategy scan key, this is just an
1507 : * optimization; _bt_tuple_before_array_skeys already confirmed that
1508 : * this scan key places us ahead of caller's tuple. There's no need
1509 : * to repeat that work now. (The same underlying principle also gets
1510 : * applied by the cur_elem_trig optimization used to speed up searches
1511 : * for the next array element.)
1512 : *
1513 : * If this is a required inequality strategy scan key, we _must_ rely
1514 : * on _bt_check_compare like this; we aren't capable of directly
1515 : * evaluating required inequality strategy scan keys here, on our own.
1516 : */
1517 374246 : if (ikey == sktrig && !array)
1518 : {
1519 : Assert(sktrig_required && required && all_required_satisfied);
1520 :
1521 : /* Use "beyond end" advancement. See below for an explanation. */
1522 7420 : beyond_end_advance = true;
1523 7420 : all_satisfied = all_required_satisfied = false;
1524 :
1525 7420 : continue;
1526 : }
1527 :
1528 : /*
1529 : * Nothing more for us to do with an inequality strategy scan key that
1530 : * wasn't the one that _bt_check_compare stopped on, though.
1531 : *
1532 : * Note: if our later call to _bt_check_compare (to recheck caller's
1533 : * tuple) sets continuescan=false due to finding this same inequality
1534 : * unsatisfied (possible when it's required in the scan direction),
1535 : * we'll deal with it via a recursive "second pass" call.
1536 : */
1537 366826 : else if (cur->sk_strategy != BTEqualStrategyNumber)
1538 47556 : continue;
1539 :
1540 : /*
1541 : * Nothing for us to do with an equality strategy scan key that isn't
1542 : * marked required, either -- unless it's a non-required array
1543 : */
1544 319270 : else if (!required && !array)
1545 0 : continue;
1546 :
1547 : /*
1548 : * Here we perform steps for all array scan keys after a required
1549 : * array scan key whose binary search triggered "beyond end of array
1550 : * element" array advancement due to encountering a tuple attribute
1551 : * value > the closest matching array key (or < for backwards scans).
1552 : */
1553 319270 : if (beyond_end_advance)
1554 : {
1555 1430 : if (array)
1556 596 : _bt_array_set_low_or_high(rel, cur, array,
1557 : ScanDirectionIsBackward(dir));
1558 :
1559 1430 : continue;
1560 : }
1561 :
1562 : /*
1563 : * Here we perform steps for all array scan keys after a required
1564 : * array scan key whose tuple attribute was < the closest matching
1565 : * array key when we dealt with it (or > for backwards scans).
1566 : *
1567 : * This earlier required array key already puts us ahead of caller's
1568 : * tuple in the key space (for the current scan direction). We must
1569 : * make sure that subsequent lower-order array keys do not put us too
1570 : * far ahead (ahead of tuples that have yet to be seen by our caller).
1571 : * For example, when a tuple "(a, b) = (42, 5)" advances the array
1572 : * keys on "a" from 40 to 45, we must also set "b" to whatever the
1573 : * first array element for "b" is. It would be wrong to allow "b" to
1574 : * be set based on the tuple value.
1575 : *
1576 : * Perform the same steps with truncated high key attributes. You can
1577 : * think of this as a "binary search" for the element closest to the
1578 : * value -inf. Again, the arrays must never get ahead of the scan.
1579 : */
1580 317840 : if (!all_required_satisfied || cur->sk_attno > tupnatts)
1581 : {
1582 3340 : if (array)
1583 780 : _bt_array_set_low_or_high(rel, cur, array,
1584 : ScanDirectionIsForward(dir));
1585 :
1586 3340 : continue;
1587 : }
1588 :
1589 : /*
1590 : * Search in scankey's array for the corresponding tuple attribute
1591 : * value from caller's tuple
1592 : */
1593 314500 : tupdatum = index_getattr(tuple, cur->sk_attno, tupdesc, &tupnull);
1594 :
1595 314500 : if (array)
1596 : {
1597 193292 : bool cur_elem_trig = (sktrig_required && ikey == sktrig);
1598 :
1599 : /*
1600 : * "Binary search" by checking if tupdatum/tupnull are within the
1601 : * range of the skip array
1602 : */
1603 193292 : if (array->num_elems == -1)
1604 161190 : _bt_binsrch_skiparray_skey(cur_elem_trig, dir,
1605 : tupdatum, tupnull, array, cur,
1606 : &result);
1607 :
1608 : /*
1609 : * Binary search for the closest match from the SAOP array
1610 : */
1611 : else
1612 32102 : set_elem = _bt_binsrch_array_skey(&so->orderProcs[ikey],
1613 : cur_elem_trig, dir,
1614 : tupdatum, tupnull, array, cur,
1615 : &result);
1616 : }
1617 : else
1618 : {
1619 : Assert(required);
1620 :
1621 : /*
1622 : * This is a required non-array equality strategy scan key, which
1623 : * we'll treat as a degenerate single element array.
1624 : *
1625 : * This scan key's imaginary "array" can't really advance, but it
1626 : * can still roll over like any other array. (Actually, this is
1627 : * no different to real single value arrays, which never advance
1628 : * without rolling over -- they can never truly advance, either.)
1629 : */
1630 121208 : result = _bt_compare_array_skey(&so->orderProcs[ikey],
1631 : tupdatum, tupnull,
1632 : cur->sk_argument, cur);
1633 : }
1634 :
1635 : /*
1636 : * Consider "beyond end of array element" array advancement.
1637 : *
1638 : * When the tuple attribute value is > the closest matching array key
1639 : * (or < in the backwards scan case), we need to ratchet this array
1640 : * forward (backward) by one increment, so that caller's tuple ends up
1641 : * being < final array value instead (or > final array value instead).
1642 : * This process has to work for all of the arrays, not just this one:
1643 : * it must "carry" to higher-order arrays when the set_elem that we
1644 : * just found happens to be the final one for the scan's direction.
1645 : * Incrementing (decrementing) set_elem itself isn't good enough.
1646 : *
1647 : * Our approach is to provisionally use set_elem as if it was an exact
1648 : * match now, then set each later/less significant array to whatever
1649 : * its final element is. Once outside the loop we'll then "increment
1650 : * this array's set_elem" by calling _bt_advance_array_keys_increment.
1651 : * That way the process rolls over to higher order arrays as needed.
1652 : *
1653 : * Under this scheme any required arrays only ever ratchet forwards
1654 : * (or backwards), and always do so to the maximum possible extent
1655 : * that we can know will be safe without seeing the scan's next tuple.
1656 : * We don't need any special handling for required scan keys that lack
1657 : * a real array to advance, nor for redundant scan keys that couldn't
1658 : * be eliminated by _bt_preprocess_keys. It won't matter if some of
1659 : * our "true" array scan keys (or even all of them) are non-required.
1660 : */
1661 314500 : if (sktrig_required && required &&
1662 308212 : ((ScanDirectionIsForward(dir) && result > 0) ||
1663 1716 : (ScanDirectionIsBackward(dir) && result < 0)))
1664 23774 : beyond_end_advance = true;
1665 :
1666 : Assert(all_required_satisfied && all_satisfied);
1667 314500 : if (result != 0)
1668 : {
1669 : /*
1670 : * Track whether caller's tuple satisfies our new post-advancement
1671 : * qual, for required scan keys, as well as for the entire set of
1672 : * interesting scan keys (all required scan keys plus non-required
1673 : * array scan keys are considered interesting.)
1674 : */
1675 144158 : all_satisfied = false;
1676 144158 : if (sktrig_required && required)
1677 138392 : all_required_satisfied = false;
1678 : else
1679 : {
1680 : /*
1681 : * There's no need to advance the arrays using the best
1682 : * available match for a non-required array. Give up now.
1683 : * (Though note that sktrig_required calls still have to do
1684 : * all the usual post-advancement steps, including the recheck
1685 : * call to _bt_check_compare.)
1686 : */
1687 : break;
1688 : }
1689 : }
1690 :
1691 : /* Advance array keys, even when we don't have an exact match */
1692 308734 : if (array)
1693 : {
1694 187526 : if (array->num_elems == -1)
1695 : {
1696 : /* Skip array's new element is tupdatum (or MINVAL/MAXVAL) */
1697 155424 : _bt_skiparray_set_element(rel, cur, array, result,
1698 : tupdatum, tupnull);
1699 155424 : skip_array_advanced = true;
1700 : }
1701 32102 : else if (array->cur_elem != set_elem)
1702 : {
1703 : /* SAOP array's new element is set_elem datum */
1704 23962 : array->cur_elem = set_elem;
1705 23962 : cur->sk_argument = array->elem_values[set_elem];
1706 : }
1707 : }
1708 : }
1709 :
1710 : /*
1711 : * Advance the array keys incrementally whenever "beyond end of array
1712 : * element" array advancement happens, so that advancement will carry to
1713 : * higher-order arrays (might exhaust all the scan's arrays instead, which
1714 : * ends the top-level scan).
1715 : */
1716 198924 : if (beyond_end_advance &&
1717 31194 : !_bt_advance_array_keys_increment(scan, dir, &skip_array_advanced))
1718 8292 : goto end_toplevel_scan;
1719 :
1720 : Assert(_bt_verify_keys_with_arraykeys(scan));
1721 :
1722 : /*
1723 : * Maintain a page-level count of the number of times the scan's array
1724 : * keys advanced in a way that affected at least one skip array
1725 : */
1726 190632 : if (sktrig_required && skip_array_advanced)
1727 161430 : pstate->nskipadvances++;
1728 :
1729 : /*
1730 : * Does tuple now satisfy our new qual? Recheck with _bt_check_compare.
1731 : *
1732 : * Calls triggered by an unsatisfied required scan key, whose tuple now
1733 : * satisfies all required scan keys, but not all nonrequired array keys,
1734 : * will still require a recheck call to _bt_check_compare. They'll still
1735 : * need its "second pass" handling of required inequality scan keys.
1736 : * (Might have missed a still-unsatisfied required inequality scan key
1737 : * that caller didn't detect as the sktrig scan key during its initial
1738 : * _bt_check_compare call that used the old/original qual.)
1739 : *
1740 : * Calls triggered by an unsatisfied nonrequired array scan key never need
1741 : * "second pass" handling of required inequalities (nor any other handling
1742 : * of any required scan key). All that matters is whether caller's tuple
1743 : * satisfies the new qual, so it's safe to just skip the _bt_check_compare
1744 : * recheck when we've already determined that it can only return 'false'.
1745 : *
1746 : * Note: In practice most scan keys are marked required by preprocessing,
1747 : * if necessary by generating a preceding skip array. We nevertheless
1748 : * often handle array keys marked required as if they were nonrequired.
1749 : * This behavior is requested by our _bt_check_compare caller, though only
1750 : * when it is passed "forcenonrequired=true" by _bt_checkkeys.
1751 : */
1752 190632 : if ((sktrig_required && all_required_satisfied) ||
1753 143808 : (!sktrig_required && all_satisfied))
1754 : {
1755 47346 : int nsktrig = sktrig + 1;
1756 : bool continuescan;
1757 :
1758 : Assert(all_required_satisfied);
1759 :
1760 : /* Recheck _bt_check_compare on behalf of caller */
1761 47346 : if (_bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, false,
1762 47346 : !sktrig_required, &continuescan,
1763 47346 : &nsktrig) &&
1764 39682 : !so->scanBehind)
1765 : {
1766 : /* This tuple satisfies the new qual */
1767 : Assert(all_satisfied && continuescan);
1768 :
1769 37498 : if (pstate)
1770 36976 : pstate->continuescan = true;
1771 :
1772 37720 : return true;
1773 : }
1774 :
1775 : /*
1776 : * Consider "second pass" handling of required inequalities.
1777 : *
1778 : * It's possible that our _bt_check_compare call indicated that the
1779 : * scan should end due to some unsatisfied inequality that wasn't
1780 : * initially recognized as such by us. Handle this by calling
1781 : * ourselves recursively, this time indicating that the trigger is the
1782 : * inequality that we missed first time around (and using a set of
1783 : * required array/equality keys that are now exact matches for tuple).
1784 : *
1785 : * We make a strong, general guarantee that every _bt_checkkeys call
1786 : * here will advance the array keys to the maximum possible extent
1787 : * that we can know to be safe based on caller's tuple alone. If we
1788 : * didn't perform this step, then that guarantee wouldn't quite hold.
1789 : */
1790 9848 : if (unlikely(!continuescan))
1791 : {
1792 : bool satisfied PG_USED_FOR_ASSERTS_ONLY;
1793 :
1794 : Assert(sktrig_required);
1795 : Assert(so->keyData[nsktrig].sk_strategy != BTEqualStrategyNumber);
1796 :
1797 : /*
1798 : * The tuple must use "beyond end" advancement during the
1799 : * recursive call, so we cannot possibly end up back here when
1800 : * recursing. We'll consume a small, fixed amount of stack space.
1801 : */
1802 : Assert(!beyond_end_advance);
1803 :
1804 : /* Advance the array keys a second time using same tuple */
1805 222 : satisfied = _bt_advance_array_keys(scan, pstate, tuple, tupnatts,
1806 : tupdesc, nsktrig, true);
1807 :
1808 : /* This tuple doesn't satisfy the inequality */
1809 : Assert(!satisfied);
1810 222 : return false;
1811 : }
1812 :
1813 : /*
1814 : * Some non-required scan key (from new qual) still not satisfied.
1815 : *
1816 : * All scan keys required in the current scan direction must still be
1817 : * satisfied, though, so we can trust all_required_satisfied below.
1818 : */
1819 : }
1820 :
1821 : /*
1822 : * When we were called just to deal with "advancing" non-required arrays,
1823 : * this is as far as we can go (cannot stop the scan for these callers)
1824 : */
1825 152912 : if (!sktrig_required)
1826 : {
1827 : /* Caller's tuple doesn't match any qual */
1828 5766 : return false;
1829 : }
1830 :
1831 : /*
1832 : * Postcondition array state assertion (for still-unsatisfied tuples).
1833 : *
1834 : * By here we have established that the scan's required arrays (scan must
1835 : * have at least one required array) advanced, without becoming exhausted.
1836 : *
1837 : * Caller's tuple is now < the newly advanced array keys (or > when this
1838 : * is a backwards scan), except in the case where we only got this far due
1839 : * to an unsatisfied non-required scan key. Verify that with an assert.
1840 : *
1841 : * Note: we don't just quit at this point when all required scan keys were
1842 : * found to be satisfied because we need to consider edge-cases involving
1843 : * scan keys required in the opposite direction only; those aren't tracked
1844 : * by all_required_satisfied.
1845 : */
1846 : Assert(_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts,
1847 : false, 0, NULL) ==
1848 : !all_required_satisfied);
1849 :
1850 : /*
1851 : * We generally permit primitive index scans to continue onto the next
1852 : * sibling page when the page's finaltup satisfies all required scan keys
1853 : * at the point where we're between pages.
1854 : *
1855 : * If caller's tuple is also the page's finaltup, and we see that required
1856 : * scan keys still aren't satisfied, start a new primitive index scan.
1857 : */
1858 147146 : if (!all_required_satisfied && pstate->finaltup == tuple)
1859 524 : goto new_prim_scan;
1860 :
1861 : /*
1862 : * Proactively check finaltup (don't wait until finaltup is reached by the
1863 : * scan) when it might well turn out to not be satisfied later on.
1864 : *
1865 : * Note: if so->scanBehind hasn't already been set for finaltup by us,
1866 : * it'll be set during this call to _bt_tuple_before_array_skeys. Either
1867 : * way, it'll be set correctly (for the whole page) after this point.
1868 : */
1869 228676 : if (!all_required_satisfied && pstate->finaltup &&
1870 164108 : _bt_tuple_before_array_skeys(scan, dir, pstate->finaltup, tupdesc,
1871 164108 : BTreeTupleGetNAtts(pstate->finaltup, rel),
1872 : false, 0, &so->scanBehind))
1873 17472 : goto new_prim_scan;
1874 :
1875 : /*
1876 : * When we encounter a truncated finaltup high key attribute, we're
1877 : * optimistic about the chances of its corresponding required scan key
1878 : * being satisfied when we go on to recheck it against tuples from this
1879 : * page's right sibling leaf page. We consider truncated attributes to be
1880 : * satisfied by required scan keys, which allows the primitive index scan
1881 : * to continue to the next leaf page. We must set so->scanBehind to true
1882 : * to remember that the last page's finaltup had "satisfied" required scan
1883 : * keys for one or more truncated attribute values (scan keys required in
1884 : * _either_ scan direction).
1885 : *
1886 : * There is a chance that _bt_readpage (which checks so->scanBehind) will
1887 : * find that even the sibling leaf page's finaltup is < the new array
1888 : * keys. When that happens, our optimistic policy will have incurred a
1889 : * single extra leaf page access that could have been avoided.
1890 : *
1891 : * A pessimistic policy would give backward scans a gratuitous advantage
1892 : * over forward scans. We'd punish forward scans for applying more
1893 : * accurate information from the high key, rather than just using the
1894 : * final non-pivot tuple as finaltup, in the style of backward scans.
1895 : * Being pessimistic would also give some scans with non-required arrays a
1896 : * perverse advantage over similar scans that use required arrays instead.
1897 : *
1898 : * This is similar to our scan-level heuristics, below. They also set
1899 : * scanBehind to speculatively continue the primscan onto the next page.
1900 : */
1901 129150 : if (so->scanBehind)
1902 : {
1903 : /* Truncated high key -- _bt_scanbehind_checkkeys recheck scheduled */
1904 : }
1905 :
1906 : /*
1907 : * Handle inequalities marked required in the opposite scan direction.
1908 : * They can also signal that we should start a new primitive index scan.
1909 : *
1910 : * It's possible that the scan is now positioned where "matching" tuples
1911 : * begin, and that caller's tuple satisfies all scan keys required in the
1912 : * current scan direction. But if caller's tuple still doesn't satisfy
1913 : * other scan keys that are required in the opposite scan direction only
1914 : * (e.g., a required >= strategy scan key when scan direction is forward),
1915 : * it's still possible that there are many leaf pages before the page that
1916 : * _bt_first could skip straight to. Groveling through all those pages
1917 : * will always give correct answers, but it can be very inefficient. We
1918 : * must avoid needlessly scanning extra pages.
1919 : *
1920 : * Separately, it's possible that _bt_check_compare set continuescan=false
1921 : * for a scan key that's required in the opposite direction only. This is
1922 : * a special case, that happens only when _bt_check_compare sees that the
1923 : * inequality encountered a NULL value. This signals the end of non-NULL
1924 : * values in the current scan direction, which is reason enough to end the
1925 : * (primitive) scan. If this happens at the start of a large group of
1926 : * NULL values, then we shouldn't expect to be called again until after
1927 : * the scan has already read indefinitely-many leaf pages full of tuples
1928 : * with NULL suffix values. (_bt_first is expected to skip over the group
1929 : * of NULLs by applying a similar "deduce NOT NULL" rule of its own, which
1930 : * involves consing up an explicit SK_SEARCHNOTNULL key.)
1931 : *
1932 : * Apply a test against finaltup to detect and recover from the problem:
1933 : * if even finaltup doesn't satisfy such an inequality, we just skip by
1934 : * starting a new primitive index scan. When we skip, we know for sure
1935 : * that all of the tuples on the current page following caller's tuple are
1936 : * also before the _bt_first-wise start of tuples for our new qual. That
1937 : * at least suggests many more skippable pages beyond the current page.
1938 : * (when so->scanBehind and so->oppositeDirCheck are set, this'll happen
1939 : * when we test the next page's finaltup/high key instead.)
1940 : */
1941 126932 : else if (has_required_opposite_direction_only && pstate->finaltup &&
1942 4292 : unlikely(!_bt_oppodir_checkkeys(scan, dir, pstate->finaltup)))
1943 2 : goto new_prim_scan;
1944 :
1945 126930 : continue_scan:
1946 :
1947 : /*
1948 : * Stick with the ongoing primitive index scan for now.
1949 : *
1950 : * It's possible that later tuples will also turn out to have values that
1951 : * are still < the now-current array keys (or > the current array keys).
1952 : * Our caller will handle this by performing what amounts to a linear
1953 : * search of the page, implemented by calling _bt_check_compare and then
1954 : * _bt_tuple_before_array_skeys for each tuple.
1955 : *
1956 : * This approach has various advantages over a binary search of the page.
1957 : * Repeated binary searches of the page (one binary search for every array
1958 : * advancement) won't outperform a continuous linear search. While there
1959 : * are workloads that a naive linear search won't handle well, our caller
1960 : * has a "look ahead" fallback mechanism to deal with that problem.
1961 : */
1962 130014 : pstate->continuescan = true; /* Override _bt_check_compare */
1963 130014 : so->needPrimScan = false; /* _bt_readpage has more tuples to check */
1964 :
1965 130014 : if (so->scanBehind)
1966 : {
1967 : /*
1968 : * Remember if recheck needs to call _bt_oppodir_checkkeys for next
1969 : * page's finaltup (see above comments about "Handle inequalities
1970 : * marked required in the opposite scan direction" for why).
1971 : */
1972 3084 : so->oppositeDirCheck = has_required_opposite_direction_only;
1973 :
1974 : /*
1975 : * skip by setting "look ahead" mechanism's offnum for forwards scans
1976 : * (backwards scans check scanBehind flag directly instead)
1977 : */
1978 3084 : if (ScanDirectionIsForward(dir))
1979 3066 : pstate->skip = pstate->maxoff + 1;
1980 : }
1981 :
1982 : /* Caller's tuple doesn't match the new qual */
1983 130014 : return false;
1984 :
1985 17998 : new_prim_scan:
1986 :
1987 : Assert(pstate->finaltup); /* not on rightmost/leftmost page */
1988 :
1989 : /*
1990 : * Looks like another primitive index scan is required. But consider
1991 : * continuing the current primscan based on scan-level heuristics.
1992 : *
1993 : * Continue the ongoing primitive scan (and schedule a recheck for when
1994 : * the scan arrives on the next sibling leaf page) when it has already
1995 : * read at least one leaf page before the one we're reading now. This
1996 : * makes primscan scheduling more efficient when scanning subsets of an
1997 : * index with many distinct attribute values matching many array elements.
1998 : * It encourages fewer, larger primitive scans where that makes sense.
1999 : * This will in turn encourage _bt_readpage to apply the pstate.startikey
2000 : * optimization more often.
2001 : *
2002 : * Also continue the ongoing primitive index scan when it is still on the
2003 : * first page if there have been more than NSKIPADVANCES_THRESHOLD calls
2004 : * here that each advanced at least one of the scan's skip arrays
2005 : * (deliberately ignore advancements that only affected SAOP arrays here).
2006 : * A page that cycles through this many skip array elements is quite
2007 : * likely to neighbor similar pages, that we'll also need to read.
2008 : *
2009 : * Note: These heuristics aren't as aggressive as you might think. We're
2010 : * conservative about allowing a primitive scan to step from the first
2011 : * leaf page it reads to the page's sibling page (we only allow it on
2012 : * first pages whose finaltup strongly suggests that it'll work out, as
2013 : * well as first pages that have a large number of skip array advances).
2014 : * Clearing this first page finaltup hurdle is a strong signal in itself.
2015 : *
2016 : * Note: The NSKIPADVANCES_THRESHOLD heuristic exists only to avoid
2017 : * pathological cases. Specifically, cases where a skip scan should just
2018 : * behave like a traditional full index scan, but ends up "skipping" again
2019 : * and again, descending to the prior leaf page's direct sibling leaf page
2020 : * each time. This misbehavior would otherwise be possible during scans
2021 : * that never quite manage to "clear the first page finaltup hurdle".
2022 : */
2023 17998 : if (!pstate->firstpage || pstate->nskipadvances > NSKIPADVANCES_THRESHOLD)
2024 : {
2025 : /* Schedule a recheck once on the next (or previous) page */
2026 866 : so->scanBehind = true;
2027 :
2028 : /* Continue the current primitive scan after all */
2029 866 : goto continue_scan;
2030 : }
2031 :
2032 : /*
2033 : * End this primitive index scan, but schedule another.
2034 : *
2035 : * Note: We make a soft assumption that the current scan direction will
2036 : * also be used within _bt_next, when it is asked to step off this page.
2037 : * It is up to _bt_next to cancel this scheduled primitive index scan
2038 : * whenever it steps to a page in the direction opposite currPos.dir.
2039 : */
2040 17132 : pstate->continuescan = false; /* Tell _bt_readpage we're done... */
2041 17132 : so->needPrimScan = true; /* ...but call _bt_first again */
2042 :
2043 17132 : if (scan->parallel_scan)
2044 36 : _bt_parallel_primscan_schedule(scan, so->currPos.currPage);
2045 :
2046 : /* Caller's tuple doesn't match the new qual */
2047 17132 : return false;
2048 :
2049 8292 : end_toplevel_scan:
2050 :
2051 : /*
2052 : * End the current primitive index scan, but don't schedule another.
2053 : *
2054 : * This ends the entire top-level scan in the current scan direction.
2055 : *
2056 : * Note: The scan's arrays (including any non-required arrays) are now in
2057 : * their final positions for the current scan direction. If the scan
2058 : * direction happens to change, then the arrays will already be in their
2059 : * first positions for what will then be the current scan direction.
2060 : */
2061 8292 : pstate->continuescan = false; /* Tell _bt_readpage we're done... */
2062 8292 : so->needPrimScan = false; /* ...and don't call _bt_first again */
2063 :
2064 : /* Caller's tuple doesn't match any qual */
2065 8292 : return false;
2066 : }
2067 :
2068 : #ifdef USE_ASSERT_CHECKING
2069 : /*
2070 : * Verify that the scan's "so->keyData[]" scan keys are in agreement with
2071 : * its array key state
2072 : */
2073 : static bool
2074 : _bt_verify_keys_with_arraykeys(IndexScanDesc scan)
2075 : {
2076 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2077 : int last_sk_attno = InvalidAttrNumber,
2078 : arrayidx = 0;
2079 : bool nonrequiredseen = false;
2080 :
2081 : if (!so->qual_ok)
2082 : return false;
2083 :
2084 : for (int ikey = 0; ikey < so->numberOfKeys; ikey++)
2085 : {
2086 : ScanKey cur = so->keyData + ikey;
2087 : BTArrayKeyInfo *array;
2088 :
2089 : if (cur->sk_strategy != BTEqualStrategyNumber ||
2090 : !(cur->sk_flags & SK_SEARCHARRAY))
2091 : continue;
2092 :
2093 : array = &so->arrayKeys[arrayidx++];
2094 : if (array->scan_key != ikey)
2095 : return false;
2096 :
2097 : if (array->num_elems == 0 || array->num_elems < -1)
2098 : return false;
2099 :
2100 : if (array->num_elems != -1 &&
2101 : cur->sk_argument != array->elem_values[array->cur_elem])
2102 : return false;
2103 : if (cur->sk_flags & (SK_BT_REQFWD | SK_BT_REQBKWD))
2104 : {
2105 : if (last_sk_attno > cur->sk_attno)
2106 : return false;
2107 : if (nonrequiredseen)
2108 : return false;
2109 : }
2110 : else
2111 : nonrequiredseen = true;
2112 :
2113 : last_sk_attno = cur->sk_attno;
2114 : }
2115 :
2116 : if (arrayidx != so->numArrayKeys)
2117 : return false;
2118 :
2119 : return true;
2120 : }
2121 : #endif
2122 :
2123 : /*
2124 : * Test whether an indextuple satisfies all the scankey conditions.
2125 : *
2126 : * Return true if so, false if not. If the tuple fails to pass the qual,
2127 : * we also determine whether there's any need to continue the scan beyond
2128 : * this tuple, and set pstate.continuescan accordingly. See comments for
2129 : * _bt_preprocess_keys() about how this is done.
2130 : *
2131 : * Forward scan callers can pass a high key tuple in the hopes of having
2132 : * us set *continuescan to false, and avoiding an unnecessary visit to
2133 : * the page to the right.
2134 : *
2135 : * Advances the scan's array keys when necessary for arrayKeys=true callers.
2136 : * Scans without any array keys must always pass arrayKeys=false.
2137 : *
2138 : * Also stops and starts primitive index scans for arrayKeys=true callers.
2139 : * Scans with array keys are required to set up page state that helps us with
2140 : * this. The page's finaltup tuple (the page high key for a forward scan, or
2141 : * the page's first non-pivot tuple for a backward scan) must be set in
2142 : * pstate.finaltup ahead of the first call here for the page. Set this to
2143 : * NULL for rightmost page (or the leftmost page for backwards scans).
2144 : *
2145 : * scan: index scan descriptor (containing a search-type scankey)
2146 : * pstate: page level input and output parameters
2147 : * arrayKeys: should we advance the scan's array keys if necessary?
2148 : * tuple: index tuple to test
2149 : * tupnatts: number of attributes in tupnatts (high key may be truncated)
2150 : */
2151 : bool
2152 62431860 : _bt_checkkeys(IndexScanDesc scan, BTReadPageState *pstate, bool arrayKeys,
2153 : IndexTuple tuple, int tupnatts)
2154 : {
2155 62431860 : TupleDesc tupdesc = RelationGetDescr(scan->indexRelation);
2156 62431860 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2157 62431860 : ScanDirection dir = so->currPos.dir;
2158 62431860 : int ikey = pstate->startikey;
2159 : bool res;
2160 :
2161 : Assert(BTreeTupleGetNAtts(tuple, scan->indexRelation) == tupnatts);
2162 : Assert(!so->needPrimScan && !so->scanBehind && !so->oppositeDirCheck);
2163 : Assert(arrayKeys || so->numArrayKeys == 0);
2164 :
2165 62431860 : res = _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, arrayKeys,
2166 62431860 : pstate->forcenonrequired, &pstate->continuescan,
2167 : &ikey);
2168 :
2169 : /*
2170 : * If _bt_check_compare relied on the pstate.startikey optimization, call
2171 : * again (in assert-enabled builds) to verify it didn't affect our answer.
2172 : *
2173 : * Note: we can't do this when !pstate.forcenonrequired, since any arrays
2174 : * before pstate.startikey won't have advanced on this page at all.
2175 : */
2176 : Assert(!pstate->forcenonrequired || arrayKeys);
2177 : #ifdef USE_ASSERT_CHECKING
2178 : if (pstate->startikey > 0 && !pstate->forcenonrequired)
2179 : {
2180 : bool dres,
2181 : dcontinuescan;
2182 : int dikey = 0;
2183 :
2184 : /* Pass arrayKeys=false to avoid array side-effects */
2185 : dres = _bt_check_compare(scan, dir, tuple, tupnatts, tupdesc, false,
2186 : pstate->forcenonrequired, &dcontinuescan,
2187 : &dikey);
2188 : Assert(res == dres);
2189 : Assert(pstate->continuescan == dcontinuescan);
2190 :
2191 : /*
2192 : * Should also get the same ikey result. We need a slightly weaker
2193 : * assertion during arrayKeys calls, since they might be using an
2194 : * array that couldn't be marked required during preprocessing.
2195 : */
2196 : Assert(arrayKeys || ikey == dikey);
2197 : Assert(ikey <= dikey);
2198 : }
2199 : #endif
2200 :
2201 : /*
2202 : * Only one _bt_check_compare call is required in the common case where
2203 : * there are no equality strategy array scan keys. Otherwise we can only
2204 : * accept _bt_check_compare's answer unreservedly when it didn't set
2205 : * pstate.continuescan=false.
2206 : */
2207 62431860 : if (!arrayKeys || pstate->continuescan)
2208 62200400 : return res;
2209 :
2210 : /*
2211 : * _bt_check_compare call set continuescan=false in the presence of
2212 : * equality type array keys. This could mean that the tuple is just past
2213 : * the end of matches for the current array keys.
2214 : *
2215 : * It's also possible that the scan is still _before_ the _start_ of
2216 : * tuples matching the current set of array keys. Check for that first.
2217 : */
2218 : Assert(!pstate->forcenonrequired);
2219 231460 : if (_bt_tuple_before_array_skeys(scan, dir, tuple, tupdesc, tupnatts, true,
2220 : ikey, NULL))
2221 : {
2222 : /* Override _bt_check_compare, continue primitive scan */
2223 39046 : pstate->continuescan = true;
2224 :
2225 : /*
2226 : * We will end up here repeatedly given a group of tuples > the
2227 : * previous array keys and < the now-current keys (for a backwards
2228 : * scan it's just the same, though the operators swap positions).
2229 : *
2230 : * We must avoid allowing this linear search process to scan very many
2231 : * tuples from well before the start of tuples matching the current
2232 : * array keys (or from well before the point where we'll once again
2233 : * have to advance the scan's array keys).
2234 : *
2235 : * We keep the overhead under control by speculatively "looking ahead"
2236 : * to later still-unscanned items from this same leaf page. We'll
2237 : * only attempt this once the number of tuples that the linear search
2238 : * process has examined starts to get out of hand.
2239 : */
2240 39046 : pstate->rechecks++;
2241 39046 : if (pstate->rechecks >= LOOK_AHEAD_REQUIRED_RECHECKS)
2242 : {
2243 : /* See if we should skip ahead within the current leaf page */
2244 10742 : _bt_checkkeys_look_ahead(scan, pstate, tupnatts, tupdesc);
2245 :
2246 : /*
2247 : * Might have set pstate.skip to a later page offset. When that
2248 : * happens then _bt_readpage caller will inexpensively skip ahead
2249 : * to a later tuple from the same page (the one just after the
2250 : * tuple we successfully "looked ahead" to).
2251 : */
2252 : }
2253 :
2254 : /* This indextuple doesn't match the current qual, in any case */
2255 39046 : return false;
2256 : }
2257 :
2258 : /*
2259 : * Caller's tuple is >= the current set of array keys and other equality
2260 : * constraint scan keys (or <= if this is a backwards scan). It's now
2261 : * clear that we _must_ advance any required array keys in lockstep with
2262 : * the scan.
2263 : */
2264 192414 : return _bt_advance_array_keys(scan, pstate, tuple, tupnatts, tupdesc,
2265 : ikey, true);
2266 : }
2267 :
2268 : /*
2269 : * Test whether caller's finaltup tuple is still before the start of matches
2270 : * for the current array keys.
2271 : *
2272 : * Called at the start of reading a page during a scan with array keys, though
2273 : * only when the so->scanBehind flag was set on the scan's prior page.
2274 : *
2275 : * Returns false if the tuple is still before the start of matches. When that
2276 : * happens, caller should cut its losses and start a new primitive index scan.
2277 : * Otherwise returns true.
2278 : */
2279 : bool
2280 2572 : _bt_scanbehind_checkkeys(IndexScanDesc scan, ScanDirection dir,
2281 : IndexTuple finaltup)
2282 : {
2283 2572 : Relation rel = scan->indexRelation;
2284 2572 : TupleDesc tupdesc = RelationGetDescr(rel);
2285 2572 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2286 2572 : int nfinaltupatts = BTreeTupleGetNAtts(finaltup, rel);
2287 : bool scanBehind;
2288 :
2289 : Assert(so->numArrayKeys);
2290 :
2291 2572 : if (_bt_tuple_before_array_skeys(scan, dir, finaltup, tupdesc,
2292 : nfinaltupatts, false, 0, &scanBehind))
2293 412 : return false;
2294 :
2295 : /*
2296 : * If scanBehind was set, all of the untruncated attribute values from
2297 : * finaltup that correspond to an array match the array's current element,
2298 : * but there are other keys associated with truncated suffix attributes.
2299 : * Array advancement must have incremented the scan's arrays on the
2300 : * previous page, resulting in a set of array keys that happen to be an
2301 : * exact match for the current page high key's untruncated prefix values.
2302 : *
2303 : * This page definitely doesn't contain tuples that the scan will need to
2304 : * return. The next page may or may not contain relevant tuples. Handle
2305 : * this by cutting our losses and starting a new primscan.
2306 : */
2307 2160 : if (scanBehind)
2308 0 : return false;
2309 :
2310 2160 : if (!so->oppositeDirCheck)
2311 2032 : return true;
2312 :
2313 128 : return _bt_oppodir_checkkeys(scan, dir, finaltup);
2314 : }
2315 :
2316 : /*
2317 : * Test whether an indextuple fails to satisfy an inequality required in the
2318 : * opposite direction only.
2319 : *
2320 : * Caller's finaltup tuple is the page high key (for forwards scans), or the
2321 : * first non-pivot tuple (for backwards scans). Called during scans with
2322 : * required array keys and required opposite-direction inequalities.
2323 : *
2324 : * Returns false if an inequality scan key required in the opposite direction
2325 : * only isn't satisfied (and any earlier required scan keys are satisfied).
2326 : * Otherwise returns true.
2327 : *
2328 : * An unsatisfied inequality required in the opposite direction only might
2329 : * well enable skipping over many leaf pages, provided another _bt_first call
2330 : * takes place. This type of unsatisfied inequality won't usually cause
2331 : * _bt_checkkeys to stop the scan to consider array advancement/starting a new
2332 : * primitive index scan.
2333 : */
2334 : static bool
2335 4420 : _bt_oppodir_checkkeys(IndexScanDesc scan, ScanDirection dir,
2336 : IndexTuple finaltup)
2337 : {
2338 4420 : Relation rel = scan->indexRelation;
2339 4420 : TupleDesc tupdesc = RelationGetDescr(rel);
2340 4420 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2341 4420 : int nfinaltupatts = BTreeTupleGetNAtts(finaltup, rel);
2342 : bool continuescan;
2343 4420 : ScanDirection flipped = -dir;
2344 4420 : int ikey = 0;
2345 :
2346 : Assert(so->numArrayKeys);
2347 :
2348 4420 : _bt_check_compare(scan, flipped, finaltup, nfinaltupatts, tupdesc, false,
2349 : false, &continuescan,
2350 : &ikey);
2351 :
2352 4420 : if (!continuescan && so->keyData[ikey].sk_strategy != BTEqualStrategyNumber)
2353 2 : return false;
2354 :
2355 4418 : return true;
2356 : }
2357 :
2358 : /*
2359 : * Determines an offset to the first scan key (an so->keyData[]-wise offset)
2360 : * that is _not_ guaranteed to be satisfied by every tuple from pstate.page,
2361 : * which is set in pstate.startikey for _bt_checkkeys calls for the page.
2362 : * This allows caller to save cycles on comparisons of a prefix of keys while
2363 : * reading pstate.page.
2364 : *
2365 : * Also determines if later calls to _bt_checkkeys (for pstate.page) should be
2366 : * forced to treat all required scan keys >= pstate.startikey as nonrequired
2367 : * (that is, if they're to be treated as if any SK_BT_REQFWD/SK_BT_REQBKWD
2368 : * markings that were set by preprocessing were not set at all, for the
2369 : * duration of _bt_checkkeys calls prior to the call for pstate.finaltup).
2370 : * This is indicated to caller by setting pstate.forcenonrequired.
2371 : *
2372 : * Call here at the start of reading a leaf page beyond the first one for the
2373 : * primitive index scan. We consider all non-pivot tuples, so it doesn't make
2374 : * sense to call here when only a subset of those tuples can ever be read.
2375 : * This is also a good idea on performance grounds; not calling here when on
2376 : * the first page (first for the current primitive scan) avoids wasting cycles
2377 : * during selective point queries. They typically don't stand to gain as much
2378 : * when we can set pstate.startikey, and are likely to notice the overhead of
2379 : * calling here. (Also, allowing pstate.forcenonrequired to be set on a
2380 : * primscan's first page would mislead _bt_advance_array_keys, which expects
2381 : * pstate.nskipadvances to be representative of every first page's key space.)
2382 : *
2383 : * Caller must call _bt_start_array_keys and reset startikey/forcenonrequired
2384 : * ahead of the finaltup _bt_checkkeys call when we set forcenonrequired=true.
2385 : * This will give _bt_checkkeys the opportunity to call _bt_advance_array_keys
2386 : * with sktrig_required=true, restoring the invariant that the scan's required
2387 : * arrays always track the scan's progress through the index's key space.
2388 : * Caller won't need to do this on the rightmost/leftmost page in the index
2389 : * (where pstate.finaltup isn't ever set), since forcenonrequired will never
2390 : * be set here in the first place.
2391 : */
2392 : void
2393 29434 : _bt_set_startikey(IndexScanDesc scan, BTReadPageState *pstate)
2394 : {
2395 29434 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2396 29434 : Relation rel = scan->indexRelation;
2397 29434 : TupleDesc tupdesc = RelationGetDescr(rel);
2398 : ItemId iid;
2399 : IndexTuple firsttup,
2400 : lasttup;
2401 29434 : int startikey = 0,
2402 29434 : arrayidx = 0,
2403 : firstchangingattnum;
2404 29434 : bool start_past_saop_eq = false;
2405 :
2406 : Assert(!so->scanBehind);
2407 : Assert(pstate->minoff < pstate->maxoff);
2408 : Assert(!pstate->firstpage);
2409 : Assert(pstate->startikey == 0);
2410 : Assert(!so->numArrayKeys || pstate->finaltup ||
2411 : P_RIGHTMOST(BTPageGetOpaque(pstate->page)) ||
2412 : P_LEFTMOST(BTPageGetOpaque(pstate->page)));
2413 :
2414 29434 : if (so->numberOfKeys == 0)
2415 11262 : return;
2416 :
2417 : /* minoff is an offset to the lowest non-pivot tuple on the page */
2418 18172 : iid = PageGetItemId(pstate->page, pstate->minoff);
2419 18172 : firsttup = (IndexTuple) PageGetItem(pstate->page, iid);
2420 :
2421 : /* maxoff is an offset to the highest non-pivot tuple on the page */
2422 18172 : iid = PageGetItemId(pstate->page, pstate->maxoff);
2423 18172 : lasttup = (IndexTuple) PageGetItem(pstate->page, iid);
2424 :
2425 : /* Determine the first attribute whose values change on caller's page */
2426 18172 : firstchangingattnum = _bt_keep_natts_fast(rel, firsttup, lasttup);
2427 :
2428 27398 : for (; startikey < so->numberOfKeys; startikey++)
2429 : {
2430 21012 : ScanKey key = so->keyData + startikey;
2431 : BTArrayKeyInfo *array;
2432 : Datum firstdatum,
2433 : lastdatum;
2434 : bool firstnull,
2435 : lastnull;
2436 : int32 result;
2437 :
2438 : /*
2439 : * Determine if it's safe to set pstate.startikey to an offset to a
2440 : * key that comes after this key, by examining this key
2441 : */
2442 21012 : if (key->sk_flags & SK_ROW_HEADER)
2443 : {
2444 : /* RowCompare inequality (header key) */
2445 0 : ScanKey subkey = (ScanKey) DatumGetPointer(key->sk_argument);
2446 0 : bool satisfied = false;
2447 :
2448 : for (;;)
2449 0 : {
2450 : int cmpresult;
2451 0 : bool firstsatisfies = false;
2452 :
2453 0 : if (subkey->sk_attno > firstchangingattnum) /* >, not >= */
2454 0 : break; /* unsafe, preceding attr has multiple
2455 : * distinct values */
2456 :
2457 0 : if (subkey->sk_flags & SK_ISNULL)
2458 0 : break; /* unsafe, unsatisfiable NULL subkey arg */
2459 :
2460 0 : firstdatum = index_getattr(firsttup, subkey->sk_attno,
2461 : tupdesc, &firstnull);
2462 0 : lastdatum = index_getattr(lasttup, subkey->sk_attno,
2463 : tupdesc, &lastnull);
2464 :
2465 0 : if (firstnull || lastnull)
2466 : break; /* unsafe, NULL value won't satisfy subkey */
2467 :
2468 : /*
2469 : * Compare the first tuple's datum for this row compare member
2470 : */
2471 0 : cmpresult = DatumGetInt32(FunctionCall2Coll(&subkey->sk_func,
2472 : subkey->sk_collation,
2473 : firstdatum,
2474 : subkey->sk_argument));
2475 0 : if (subkey->sk_flags & SK_BT_DESC)
2476 0 : INVERT_COMPARE_RESULT(cmpresult);
2477 :
2478 0 : if (cmpresult != 0 || (subkey->sk_flags & SK_ROW_END))
2479 : {
2480 0 : firstsatisfies = _bt_rowcompare_cmpresult(subkey,
2481 : cmpresult);
2482 0 : if (!firstsatisfies)
2483 : {
2484 : /* Unsafe, firstdatum does not satisfy subkey */
2485 0 : break;
2486 : }
2487 : }
2488 :
2489 : /*
2490 : * Compare the last tuple's datum for this row compare member
2491 : */
2492 0 : cmpresult = DatumGetInt32(FunctionCall2Coll(&subkey->sk_func,
2493 : subkey->sk_collation,
2494 : lastdatum,
2495 : subkey->sk_argument));
2496 0 : if (subkey->sk_flags & SK_BT_DESC)
2497 0 : INVERT_COMPARE_RESULT(cmpresult);
2498 :
2499 0 : if (cmpresult != 0 || (subkey->sk_flags & SK_ROW_END))
2500 : {
2501 0 : if (!firstsatisfies)
2502 : {
2503 : /*
2504 : * It's only safe to set startikey beyond the row
2505 : * compare header key when both firsttup and lasttup
2506 : * satisfy the key as a whole based on the same
2507 : * deciding subkey/attribute. That can't happen now.
2508 : */
2509 0 : break; /* unsafe */
2510 : }
2511 :
2512 0 : satisfied = _bt_rowcompare_cmpresult(subkey, cmpresult);
2513 0 : break; /* safe iff 'satisfied' is true */
2514 : }
2515 :
2516 : /* Move on to next row member/subkey */
2517 0 : if (subkey->sk_flags & SK_ROW_END)
2518 0 : break; /* defensive */
2519 0 : subkey++;
2520 :
2521 : /*
2522 : * We deliberately don't check if the next subkey has the same
2523 : * strategy as this iteration's subkey (which happens when
2524 : * subkeys for both ASC and DESC columns are used together),
2525 : * nor if any subkey is marked required. This is safe because
2526 : * in general all prior index attributes must have only one
2527 : * distinct value (across all of the tuples on the page) in
2528 : * order for us to even consider any subkey's attribute.
2529 : */
2530 : }
2531 :
2532 0 : if (satisfied)
2533 : {
2534 : /* Safe, row compare satisfied by every tuple on page */
2535 8978 : continue;
2536 : }
2537 :
2538 11786 : break; /* unsafe */
2539 : }
2540 21012 : if (key->sk_strategy != BTEqualStrategyNumber)
2541 : {
2542 : /*
2543 : * Scalar inequality key.
2544 : *
2545 : * It's definitely safe for _bt_checkkeys to avoid assessing this
2546 : * inequality when the page's first and last non-pivot tuples both
2547 : * satisfy the inequality (since the same must also be true of all
2548 : * the tuples in between these two).
2549 : *
2550 : * Unlike the "=" case, it doesn't matter if this attribute has
2551 : * more than one distinct value (though it _is_ necessary for any
2552 : * and all _prior_ attributes to contain no more than one distinct
2553 : * value amongst all of the tuples from pstate.page).
2554 : */
2555 4732 : if (key->sk_attno > firstchangingattnum) /* >, not >= */
2556 362 : break; /* unsafe, preceding attr has multiple
2557 : * distinct values */
2558 :
2559 4370 : firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc, &firstnull);
2560 4370 : lastdatum = index_getattr(lasttup, key->sk_attno, tupdesc, &lastnull);
2561 :
2562 4370 : if (key->sk_flags & SK_ISNULL)
2563 : {
2564 : /* IS NOT NULL key */
2565 : Assert(key->sk_flags & SK_SEARCHNOTNULL);
2566 :
2567 144 : if (firstnull || lastnull)
2568 : break; /* unsafe */
2569 :
2570 : /* Safe, IS NOT NULL key satisfied by every tuple */
2571 144 : continue;
2572 : }
2573 :
2574 : /* Test firsttup */
2575 4226 : if (firstnull ||
2576 4226 : !DatumGetBool(FunctionCall2Coll(&key->sk_func,
2577 : key->sk_collation, firstdatum,
2578 : key->sk_argument)))
2579 : break; /* unsafe */
2580 :
2581 : /* Test lasttup */
2582 4226 : if (lastnull ||
2583 4226 : !DatumGetBool(FunctionCall2Coll(&key->sk_func,
2584 : key->sk_collation, lastdatum,
2585 : key->sk_argument)))
2586 : break; /* unsafe */
2587 :
2588 : /* Safe, scalar inequality satisfied by every tuple */
2589 4114 : continue;
2590 : }
2591 :
2592 : /* Some = key (could be a scalar = key, could be an array = key) */
2593 : Assert(key->sk_strategy == BTEqualStrategyNumber);
2594 :
2595 16280 : if (!(key->sk_flags & SK_SEARCHARRAY))
2596 : {
2597 : /*
2598 : * Scalar = key (possibly an IS NULL key).
2599 : *
2600 : * It is unsafe to set pstate.startikey to an ikey beyond this
2601 : * key, unless the = key is satisfied by every possible tuple on
2602 : * the page (possible only when attribute has just one distinct
2603 : * value among all tuples on the page).
2604 : */
2605 12804 : if (key->sk_attno >= firstchangingattnum)
2606 10434 : break; /* unsafe, multiple distinct attr values */
2607 :
2608 2370 : firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc,
2609 : &firstnull);
2610 2370 : if (key->sk_flags & SK_ISNULL)
2611 : {
2612 : /* IS NULL key */
2613 : Assert(key->sk_flags & SK_SEARCHNULL);
2614 :
2615 0 : if (!firstnull)
2616 0 : break; /* unsafe */
2617 :
2618 : /* Safe, IS NULL key satisfied by every tuple */
2619 0 : continue;
2620 : }
2621 2370 : if (firstnull ||
2622 2370 : !DatumGetBool(FunctionCall2Coll(&key->sk_func,
2623 : key->sk_collation, firstdatum,
2624 : key->sk_argument)))
2625 : break; /* unsafe */
2626 :
2627 : /* Safe, scalar = key satisfied by every tuple */
2628 2370 : continue;
2629 : }
2630 :
2631 : /* = array key (could be a SAOP array, could be a skip array) */
2632 3476 : array = &so->arrayKeys[arrayidx++];
2633 : Assert(array->scan_key == startikey);
2634 3476 : if (array->num_elems != -1)
2635 : {
2636 : /*
2637 : * SAOP array = key.
2638 : *
2639 : * Handle this like we handle scalar = keys (though binary search
2640 : * for a matching element, to avoid relying on key's sk_argument).
2641 : */
2642 816 : if (key->sk_attno >= firstchangingattnum)
2643 816 : break; /* unsafe, multiple distinct attr values */
2644 :
2645 0 : firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc,
2646 : &firstnull);
2647 0 : _bt_binsrch_array_skey(&so->orderProcs[startikey],
2648 : false, NoMovementScanDirection,
2649 : firstdatum, firstnull, array, key,
2650 : &result);
2651 0 : if (result != 0)
2652 0 : break; /* unsafe */
2653 :
2654 : /* Safe, SAOP = key satisfied by every tuple */
2655 0 : start_past_saop_eq = true;
2656 0 : continue;
2657 : }
2658 :
2659 : /*
2660 : * Skip array = key
2661 : */
2662 : Assert(key->sk_flags & SK_BT_SKIP);
2663 2660 : if (array->null_elem)
2664 : {
2665 : /*
2666 : * Non-range skip array = key.
2667 : *
2668 : * Safe, non-range skip array "satisfied" by every tuple on page
2669 : * (safe even when "key->sk_attno > firstchangingattnum").
2670 : */
2671 2350 : continue;
2672 : }
2673 :
2674 : /*
2675 : * Range skip array = key.
2676 : *
2677 : * Handle this like we handle scalar inequality keys (but avoid using
2678 : * key's sk_argument directly, as in the SAOP array case).
2679 : */
2680 310 : if (key->sk_attno > firstchangingattnum) /* >, not >= */
2681 48 : break; /* unsafe, preceding attr has multiple
2682 : * distinct values */
2683 :
2684 262 : firstdatum = index_getattr(firsttup, key->sk_attno, tupdesc, &firstnull);
2685 262 : lastdatum = index_getattr(lasttup, key->sk_attno, tupdesc, &lastnull);
2686 :
2687 : /* Test firsttup */
2688 262 : _bt_binsrch_skiparray_skey(false, ForwardScanDirection,
2689 : firstdatum, firstnull, array, key,
2690 : &result);
2691 262 : if (result != 0)
2692 0 : break; /* unsafe */
2693 :
2694 : /* Test lasttup */
2695 262 : _bt_binsrch_skiparray_skey(false, ForwardScanDirection,
2696 : lastdatum, lastnull, array, key,
2697 : &result);
2698 262 : if (result != 0)
2699 14 : break; /* unsafe */
2700 :
2701 : /* Safe, range skip array satisfied by every tuple on page */
2702 : }
2703 :
2704 : /*
2705 : * Use of forcenonrequired is typically undesirable, since it'll force
2706 : * _bt_readpage caller to read every tuple on the page -- even though, in
2707 : * general, it might well be possible to end the scan on an earlier tuple.
2708 : * However, caller must use forcenonrequired when start_past_saop_eq=true,
2709 : * since the usual required array behavior might fail to roll over to the
2710 : * SAOP array.
2711 : *
2712 : * We always prefer forcenonrequired=true during scans with skip arrays
2713 : * (except on the first page of each primitive index scan), though -- even
2714 : * when "startikey == 0". That way, _bt_advance_array_keys's low-order
2715 : * key precheck optimization can always be used (unless on the first page
2716 : * of the scan). It seems slightly preferable to check more tuples when
2717 : * that allows us to do significantly less skip array maintenance.
2718 : */
2719 18172 : pstate->forcenonrequired = (start_past_saop_eq || so->skipScan);
2720 18172 : pstate->startikey = startikey;
2721 :
2722 : /*
2723 : * _bt_readpage caller is required to call _bt_checkkeys against page's
2724 : * finaltup with forcenonrequired=false whenever we initially set
2725 : * forcenonrequired=true. That way the scan's arrays will reliably track
2726 : * its progress through the index's key space.
2727 : *
2728 : * We don't expect this when _bt_readpage caller has no finaltup due to
2729 : * its page being the rightmost (or the leftmost, during backwards scans).
2730 : * When we see that _bt_readpage has no finaltup, back out of everything.
2731 : */
2732 : Assert(!pstate->forcenonrequired || so->numArrayKeys);
2733 18172 : if (pstate->forcenonrequired && !pstate->finaltup)
2734 : {
2735 468 : pstate->forcenonrequired = false;
2736 468 : pstate->startikey = 0;
2737 : }
2738 : }
2739 :
2740 : /*
2741 : * Test whether an indextuple satisfies current scan condition.
2742 : *
2743 : * Return true if so, false if not. If not, also sets *continuescan to false
2744 : * when it's also not possible for any later tuples to pass the current qual
2745 : * (with the scan's current set of array keys, in the current scan direction),
2746 : * in addition to setting *ikey to the so->keyData[] subscript/offset for the
2747 : * unsatisfied scan key (needed when caller must consider advancing the scan's
2748 : * array keys).
2749 : *
2750 : * This is a subroutine for _bt_checkkeys. We provisionally assume that
2751 : * reaching the end of the current set of required keys (in particular the
2752 : * current required array keys) ends the ongoing (primitive) index scan.
2753 : * Callers without array keys should just end the scan right away when they
2754 : * find that continuescan has been set to false here by us. Things are more
2755 : * complicated for callers with array keys.
2756 : *
2757 : * Callers with array keys must first consider advancing the arrays when
2758 : * continuescan has been set to false here by us. They must then consider if
2759 : * it really does make sense to end the current (primitive) index scan, in
2760 : * light of everything that is known at that point. (In general when we set
2761 : * continuescan=false for these callers it must be treated as provisional.)
2762 : *
2763 : * We deal with advancing unsatisfied non-required arrays directly, though.
2764 : * This is safe, since by definition non-required keys can't end the scan.
2765 : * This is just how we determine if non-required arrays are just unsatisfied
2766 : * by the current array key, or if they're truly unsatisfied (that is, if
2767 : * they're unsatisfied by every possible array key).
2768 : *
2769 : * Pass advancenonrequired=false to avoid all array related side effects.
2770 : * This allows _bt_advance_array_keys caller to avoid infinite recursion.
2771 : *
2772 : * Pass forcenonrequired=true to instruct us to treat all keys as nonrequired.
2773 : * This is used to make it safe to temporarily stop properly maintaining the
2774 : * scan's required arrays. _bt_checkkeys caller (_bt_readpage, actually)
2775 : * determines a prefix of keys that must satisfy every possible corresponding
2776 : * index attribute value from its page, which is passed to us via *ikey arg
2777 : * (this is the first key that might be unsatisfied by tuples on the page).
2778 : * Obviously, we won't maintain any array keys from before *ikey, so it's
2779 : * quite possible for such arrays to "fall behind" the index's keyspace.
2780 : * Caller will need to "catch up" by passing forcenonrequired=true (alongside
2781 : * an *ikey=0) once the page's finaltup is reached.
2782 : *
2783 : * Note: it's safe to pass an *ikey > 0 with forcenonrequired=false, but only
2784 : * when caller determines that it won't affect array maintenance.
2785 : */
2786 : static bool
2787 62492268 : _bt_check_compare(IndexScanDesc scan, ScanDirection dir,
2788 : IndexTuple tuple, int tupnatts, TupleDesc tupdesc,
2789 : bool advancenonrequired, bool forcenonrequired,
2790 : bool *continuescan, int *ikey)
2791 : {
2792 62492268 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
2793 :
2794 62492268 : *continuescan = true; /* default assumption */
2795 :
2796 120186466 : for (; *ikey < so->numberOfKeys; (*ikey)++)
2797 : {
2798 71244888 : ScanKey key = so->keyData + *ikey;
2799 : Datum datum;
2800 : bool isNull;
2801 71244888 : bool requiredSameDir = false,
2802 71244888 : requiredOppositeDirOnly = false;
2803 :
2804 : /*
2805 : * Check if the key is required in the current scan direction, in the
2806 : * opposite scan direction _only_, or in neither direction (except
2807 : * when we're forced to treat all scan keys as nonrequired)
2808 : */
2809 71244888 : if (forcenonrequired)
2810 : {
2811 : /* treating scan's keys as non-required */
2812 : }
2813 70820192 : else if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsForward(dir)) ||
2814 14808016 : ((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsBackward(dir)))
2815 56036922 : requiredSameDir = true;
2816 14783270 : else if (((key->sk_flags & SK_BT_REQFWD) && ScanDirectionIsBackward(dir)) ||
2817 6107934 : ((key->sk_flags & SK_BT_REQBKWD) && ScanDirectionIsForward(dir)))
2818 14783270 : requiredOppositeDirOnly = true;
2819 :
2820 71244888 : if (key->sk_attno > tupnatts)
2821 : {
2822 : /*
2823 : * This attribute is truncated (must be high key). The value for
2824 : * this attribute in the first non-pivot tuple on the page to the
2825 : * right could be any possible value. Assume that truncated
2826 : * attribute passes the qual.
2827 : */
2828 : Assert(BTreeTupleIsPivot(tuple));
2829 19099052 : continue;
2830 : }
2831 :
2832 : /*
2833 : * A skip array scan key uses one of several sentinel values. We just
2834 : * fall back on _bt_tuple_before_array_skeys when we see such a value.
2835 : */
2836 71242608 : if (key->sk_flags & (SK_BT_MINVAL | SK_BT_MAXVAL |
2837 : SK_BT_NEXT | SK_BT_PRIOR))
2838 : {
2839 : Assert(key->sk_flags & SK_SEARCHARRAY);
2840 : Assert(key->sk_flags & SK_BT_SKIP);
2841 : Assert(requiredSameDir || forcenonrequired);
2842 :
2843 : /*
2844 : * Cannot fall back on _bt_tuple_before_array_skeys when we're
2845 : * treating the scan's keys as nonrequired, though. Just handle
2846 : * this like any other non-required equality-type array key.
2847 : */
2848 35798 : if (forcenonrequired)
2849 13550690 : return _bt_advance_array_keys(scan, NULL, tuple, tupnatts,
2850 : tupdesc, *ikey, false);
2851 :
2852 33770 : *continuescan = false;
2853 33770 : return false;
2854 : }
2855 :
2856 : /* row-comparison keys need special processing */
2857 71206810 : if (key->sk_flags & SK_ROW_HEADER)
2858 : {
2859 2454 : if (_bt_check_rowcompare(key, tuple, tupnatts, tupdesc, dir,
2860 : forcenonrequired, continuescan))
2861 2388 : continue;
2862 66 : return false;
2863 : }
2864 :
2865 71204356 : datum = index_getattr(tuple,
2866 71204356 : key->sk_attno,
2867 : tupdesc,
2868 : &isNull);
2869 :
2870 71204356 : if (key->sk_flags & SK_ISNULL)
2871 : {
2872 : /* Handle IS NULL/NOT NULL tests */
2873 19112156 : if (key->sk_flags & SK_SEARCHNULL)
2874 : {
2875 18128 : if (isNull)
2876 428 : continue; /* tuple satisfies this qual */
2877 : }
2878 : else
2879 : {
2880 : Assert(key->sk_flags & SK_SEARCHNOTNULL);
2881 : Assert(!(key->sk_flags & SK_BT_SKIP));
2882 19094028 : if (!isNull)
2883 19093956 : continue; /* tuple satisfies this qual */
2884 : }
2885 :
2886 : /*
2887 : * Tuple fails this qual. If it's a required qual for the current
2888 : * scan direction, then we can conclude no further tuples will
2889 : * pass, either.
2890 : */
2891 17772 : if (requiredSameDir)
2892 204 : *continuescan = false;
2893 17568 : else if (unlikely(key->sk_flags & SK_BT_SKIP))
2894 : {
2895 : /*
2896 : * If we're treating scan keys as nonrequired, and encounter a
2897 : * skip array scan key whose current element is NULL, then it
2898 : * must be a non-range skip array. It must be satisfied, so
2899 : * there's no need to call _bt_advance_array_keys to check.
2900 : */
2901 : Assert(forcenonrequired && *ikey > 0);
2902 0 : continue;
2903 : }
2904 :
2905 : /*
2906 : * This indextuple doesn't match the qual.
2907 : */
2908 17772 : return false;
2909 : }
2910 :
2911 52092200 : if (isNull)
2912 : {
2913 : /*
2914 : * Scalar scan key isn't satisfied by NULL tuple value.
2915 : *
2916 : * If we're treating scan keys as nonrequired, and key is for a
2917 : * skip array, then we must attempt to advance the array to NULL
2918 : * (if we're successful then the tuple might match the qual).
2919 : */
2920 228 : if (unlikely(forcenonrequired && key->sk_flags & SK_BT_SKIP))
2921 0 : return _bt_advance_array_keys(scan, NULL, tuple, tupnatts,
2922 : tupdesc, *ikey, false);
2923 :
2924 228 : if (key->sk_flags & SK_BT_NULLS_FIRST)
2925 : {
2926 : /*
2927 : * Since NULLs are sorted before non-NULLs, we know we have
2928 : * reached the lower limit of the range of values for this
2929 : * index attr. On a backward scan, we can stop if this qual
2930 : * is one of the "must match" subset. We can stop regardless
2931 : * of whether the qual is > or <, so long as it's required,
2932 : * because it's not possible for any future tuples to pass. On
2933 : * a forward scan, however, we must keep going, because we may
2934 : * have initially positioned to the start of the index.
2935 : * (_bt_advance_array_keys also relies on this behavior during
2936 : * forward scans.)
2937 : */
2938 0 : if ((requiredSameDir || requiredOppositeDirOnly) &&
2939 : ScanDirectionIsBackward(dir))
2940 0 : *continuescan = false;
2941 : }
2942 : else
2943 : {
2944 : /*
2945 : * Since NULLs are sorted after non-NULLs, we know we have
2946 : * reached the upper limit of the range of values for this
2947 : * index attr. On a forward scan, we can stop if this qual is
2948 : * one of the "must match" subset. We can stop regardless of
2949 : * whether the qual is > or <, so long as it's required,
2950 : * because it's not possible for any future tuples to pass. On
2951 : * a backward scan, however, we must keep going, because we
2952 : * may have initially positioned to the end of the index.
2953 : * (_bt_advance_array_keys also relies on this behavior during
2954 : * backward scans.)
2955 : */
2956 228 : if ((requiredSameDir || requiredOppositeDirOnly) &&
2957 : ScanDirectionIsForward(dir))
2958 222 : *continuescan = false;
2959 : }
2960 :
2961 : /*
2962 : * This indextuple doesn't match the qual.
2963 : */
2964 228 : return false;
2965 : }
2966 :
2967 52091972 : if (!DatumGetBool(FunctionCall2Coll(&key->sk_func, key->sk_collation,
2968 : datum, key->sk_argument)))
2969 : {
2970 : /*
2971 : * Tuple fails this qual. If it's a required qual for the current
2972 : * scan direction, then we can conclude no further tuples will
2973 : * pass, either.
2974 : *
2975 : * Note: because we stop the scan as soon as any required equality
2976 : * qual fails, it is critical that equality quals be used for the
2977 : * initial positioning in _bt_first() when they are available. See
2978 : * comments in _bt_first().
2979 : */
2980 13496826 : if (requiredSameDir)
2981 13122364 : *continuescan = false;
2982 :
2983 : /*
2984 : * If this is a non-required equality-type array key, the tuple
2985 : * needs to be checked against every possible array key. Handle
2986 : * this by "advancing" the scan key's array to a matching value
2987 : * (if we're successful then the tuple might match the qual).
2988 : */
2989 374462 : else if (advancenonrequired &&
2990 367020 : key->sk_strategy == BTEqualStrategyNumber &&
2991 291228 : (key->sk_flags & SK_SEARCHARRAY))
2992 6614 : return _bt_advance_array_keys(scan, NULL, tuple, tupnatts,
2993 : tupdesc, *ikey, false);
2994 :
2995 : /*
2996 : * This indextuple doesn't match the qual.
2997 : */
2998 13490212 : return false;
2999 : }
3000 : }
3001 :
3002 : /* If we get here, the tuple passes all index quals. */
3003 48941578 : return true;
3004 : }
3005 :
3006 : /*
3007 : * Call here when a row compare member returns a non-zero result, or with the
3008 : * result for the final ROW_END row compare member (no matter the cmpresult).
3009 : *
3010 : * cmpresult indicates the overall result of the row comparison (must already
3011 : * be commuted for DESC subkeys), and subkey is the deciding row member.
3012 : */
3013 : static bool
3014 2388 : _bt_rowcompare_cmpresult(ScanKey subkey, int cmpresult)
3015 : {
3016 : bool satisfied;
3017 :
3018 2388 : switch (subkey->sk_strategy)
3019 : {
3020 186 : case BTLessStrategyNumber:
3021 186 : satisfied = (cmpresult < 0);
3022 186 : break;
3023 1584 : case BTLessEqualStrategyNumber:
3024 1584 : satisfied = (cmpresult <= 0);
3025 1584 : break;
3026 246 : case BTGreaterEqualStrategyNumber:
3027 246 : satisfied = (cmpresult >= 0);
3028 246 : break;
3029 372 : case BTGreaterStrategyNumber:
3030 372 : satisfied = (cmpresult > 0);
3031 372 : break;
3032 0 : default:
3033 : /* EQ and NE cases aren't allowed here */
3034 0 : elog(ERROR, "unexpected strategy number %d", subkey->sk_strategy);
3035 : satisfied = false; /* keep compiler quiet */
3036 : break;
3037 : }
3038 :
3039 2388 : return satisfied;
3040 : }
3041 :
3042 : /*
3043 : * Test whether an indextuple satisfies a row-comparison scan condition.
3044 : *
3045 : * Return true if so, false if not. If not, also clear *continuescan if
3046 : * it's not possible for any future tuples in the current scan direction
3047 : * to pass the qual.
3048 : *
3049 : * This is a subroutine for _bt_checkkeys/_bt_check_compare.
3050 : */
3051 : static bool
3052 2454 : _bt_check_rowcompare(ScanKey skey, IndexTuple tuple, int tupnatts,
3053 : TupleDesc tupdesc, ScanDirection dir,
3054 : bool forcenonrequired, bool *continuescan)
3055 : {
3056 2454 : ScanKey subkey = (ScanKey) DatumGetPointer(skey->sk_argument);
3057 2454 : int32 cmpresult = 0;
3058 : bool result;
3059 :
3060 : /* First subkey should be same as the header says */
3061 : Assert(subkey->sk_attno == skey->sk_attno);
3062 :
3063 : /* Loop over columns of the row condition */
3064 : for (;;)
3065 240 : {
3066 : Datum datum;
3067 : bool isNull;
3068 :
3069 : Assert(subkey->sk_flags & SK_ROW_MEMBER);
3070 :
3071 : /* When a NULL row member is compared, the row never matches */
3072 2694 : if (subkey->sk_flags & SK_ISNULL)
3073 : {
3074 : /*
3075 : * Unlike the simple-scankey case, this isn't a disallowed case
3076 : * (except when it's the first row element that has the NULL arg).
3077 : * But it can never match. If all the earlier row comparison
3078 : * columns are required for the scan direction, we can stop the
3079 : * scan, because there can't be another tuple that will succeed.
3080 : */
3081 : Assert(subkey != (ScanKey) DatumGetPointer(skey->sk_argument));
3082 12 : subkey--;
3083 12 : if (forcenonrequired)
3084 : {
3085 : /* treating scan's keys as non-required */
3086 : }
3087 12 : else if ((subkey->sk_flags & SK_BT_REQFWD) &&
3088 : ScanDirectionIsForward(dir))
3089 6 : *continuescan = false;
3090 6 : else if ((subkey->sk_flags & SK_BT_REQBKWD) &&
3091 : ScanDirectionIsBackward(dir))
3092 6 : *continuescan = false;
3093 66 : return false;
3094 : }
3095 :
3096 2682 : if (subkey->sk_attno > tupnatts)
3097 : {
3098 : /*
3099 : * This attribute is truncated (must be high key). The value for
3100 : * this attribute in the first non-pivot tuple on the page to the
3101 : * right could be any possible value. Assume that truncated
3102 : * attribute passes the qual.
3103 : */
3104 : Assert(BTreeTupleIsPivot(tuple));
3105 6 : return true;
3106 : }
3107 :
3108 2676 : datum = index_getattr(tuple,
3109 2676 : subkey->sk_attno,
3110 : tupdesc,
3111 : &isNull);
3112 :
3113 2676 : if (isNull)
3114 : {
3115 : int reqflags;
3116 :
3117 48 : if (forcenonrequired)
3118 : {
3119 : /* treating scan's keys as non-required */
3120 : }
3121 48 : else if (subkey->sk_flags & SK_BT_NULLS_FIRST)
3122 : {
3123 : /*
3124 : * Since NULLs are sorted before non-NULLs, we know we have
3125 : * reached the lower limit of the range of values for this
3126 : * index attr. On a backward scan, we can stop if this qual
3127 : * is one of the "must match" subset. However, on a forwards
3128 : * scan, we must keep going, because we may have initially
3129 : * positioned to the start of the index.
3130 : *
3131 : * All required NULLS FIRST > row members can use NULL tuple
3132 : * values to end backwards scans, just like with other values.
3133 : * A qual "WHERE (a, b, c) > (9, 42, 'foo')" can terminate a
3134 : * backwards scan upon reaching the index's rightmost "a = 9"
3135 : * tuple whose "b" column contains a NULL (if not sooner).
3136 : * Since "b" is NULLS FIRST, we can treat its NULLs as "<" 42.
3137 : */
3138 0 : reqflags = SK_BT_REQBKWD;
3139 :
3140 : /*
3141 : * When a most significant required NULLS FIRST < row compare
3142 : * member sees NULL tuple values during a backwards scan, it
3143 : * signals the end of matches for the whole row compare/scan.
3144 : * A qual "WHERE (a, b, c) < (9, 42, 'foo')" will terminate a
3145 : * backwards scan upon reaching the rightmost tuple whose "a"
3146 : * column has a NULL. The "a" NULL value is "<" 9, and yet
3147 : * our < row compare will still end the scan. (This isn't
3148 : * safe with later/lower-order row members. Notice that it
3149 : * can only happen with an "a" NULL some time after the scan
3150 : * completely stops needing to use its "b" and "c" members.)
3151 : */
3152 0 : if (subkey == (ScanKey) DatumGetPointer(skey->sk_argument))
3153 0 : reqflags |= SK_BT_REQFWD; /* safe, first row member */
3154 :
3155 0 : if ((subkey->sk_flags & reqflags) &&
3156 : ScanDirectionIsBackward(dir))
3157 0 : *continuescan = false;
3158 : }
3159 : else
3160 : {
3161 : /*
3162 : * Since NULLs are sorted after non-NULLs, we know we have
3163 : * reached the upper limit of the range of values for this
3164 : * index attr. On a forward scan, we can stop if this qual is
3165 : * one of the "must match" subset. However, on a backward
3166 : * scan, we must keep going, because we may have initially
3167 : * positioned to the end of the index.
3168 : *
3169 : * All required NULLS LAST < row members can use NULL tuple
3170 : * values to end forwards scans, just like with other values.
3171 : * A qual "WHERE (a, b, c) < (9, 42, 'foo')" can terminate a
3172 : * forwards scan upon reaching the index's leftmost "a = 9"
3173 : * tuple whose "b" column contains a NULL (if not sooner).
3174 : * Since "b" is NULLS LAST, we can treat its NULLs as ">" 42.
3175 : */
3176 48 : reqflags = SK_BT_REQFWD;
3177 :
3178 : /*
3179 : * When a most significant required NULLS LAST > row compare
3180 : * member sees NULL tuple values during a forwards scan, it
3181 : * signals the end of matches for the whole row compare/scan.
3182 : * A qual "WHERE (a, b, c) > (9, 42, 'foo')" will terminate a
3183 : * forwards scan upon reaching the leftmost tuple whose "a"
3184 : * column has a NULL. The "a" NULL value is ">" 9, and yet
3185 : * our > row compare will end the scan. (This isn't safe with
3186 : * later/lower-order row members. Notice that it can only
3187 : * happen with an "a" NULL some time after the scan completely
3188 : * stops needing to use its "b" and "c" members.)
3189 : */
3190 48 : if (subkey == (ScanKey) DatumGetPointer(skey->sk_argument))
3191 0 : reqflags |= SK_BT_REQBKWD; /* safe, first row member */
3192 :
3193 48 : if ((subkey->sk_flags & reqflags) &&
3194 : ScanDirectionIsForward(dir))
3195 0 : *continuescan = false;
3196 : }
3197 :
3198 : /*
3199 : * In any case, this indextuple doesn't match the qual.
3200 : */
3201 48 : return false;
3202 : }
3203 :
3204 : /* Perform the test --- three-way comparison not bool operator */
3205 2628 : cmpresult = DatumGetInt32(FunctionCall2Coll(&subkey->sk_func,
3206 : subkey->sk_collation,
3207 : datum,
3208 : subkey->sk_argument));
3209 :
3210 2628 : if (subkey->sk_flags & SK_BT_DESC)
3211 0 : INVERT_COMPARE_RESULT(cmpresult);
3212 :
3213 : /* Done comparing if unequal, else advance to next column */
3214 2628 : if (cmpresult != 0)
3215 2388 : break;
3216 :
3217 240 : if (subkey->sk_flags & SK_ROW_END)
3218 0 : break;
3219 240 : subkey++;
3220 : }
3221 :
3222 : /* Final subkey/column determines if row compare is satisfied */
3223 2388 : result = _bt_rowcompare_cmpresult(subkey, cmpresult);
3224 :
3225 2388 : if (!result && !forcenonrequired)
3226 : {
3227 : /*
3228 : * Tuple fails this qual. If it's a required qual for the current
3229 : * scan direction, then we can conclude no further tuples will pass,
3230 : * either. Note we have to look at the deciding column, not
3231 : * necessarily the first or last column of the row condition.
3232 : */
3233 6 : if ((subkey->sk_flags & SK_BT_REQFWD) &&
3234 : ScanDirectionIsForward(dir))
3235 6 : *continuescan = false;
3236 0 : else if ((subkey->sk_flags & SK_BT_REQBKWD) &&
3237 : ScanDirectionIsBackward(dir))
3238 0 : *continuescan = false;
3239 : }
3240 :
3241 2388 : return result;
3242 : }
3243 :
3244 : /*
3245 : * Determine if a scan with array keys should skip over uninteresting tuples.
3246 : *
3247 : * This is a subroutine for _bt_checkkeys. Called when _bt_readpage's linear
3248 : * search process (started after it finishes reading an initial group of
3249 : * matching tuples, used to locate the start of the next group of tuples
3250 : * matching the next set of required array keys) has already scanned an
3251 : * excessive number of tuples whose key space is "between arrays".
3252 : *
3253 : * When we perform look ahead successfully, we'll sets pstate.skip, which
3254 : * instructs _bt_readpage to skip ahead to that tuple next (could be past the
3255 : * end of the scan's leaf page). Pages where the optimization is effective
3256 : * will generally still need to skip several times. Each call here performs
3257 : * only a single "look ahead" comparison of a later tuple, whose distance from
3258 : * the current tuple's offset number is determined by applying heuristics.
3259 : */
3260 : static void
3261 10742 : _bt_checkkeys_look_ahead(IndexScanDesc scan, BTReadPageState *pstate,
3262 : int tupnatts, TupleDesc tupdesc)
3263 : {
3264 10742 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
3265 10742 : ScanDirection dir = so->currPos.dir;
3266 : OffsetNumber aheadoffnum;
3267 : IndexTuple ahead;
3268 :
3269 : Assert(!pstate->forcenonrequired);
3270 :
3271 : /* Avoid looking ahead when comparing the page high key */
3272 10742 : if (pstate->offnum < pstate->minoff)
3273 0 : return;
3274 :
3275 : /*
3276 : * Don't look ahead when there aren't enough tuples remaining on the page
3277 : * (in the current scan direction) for it to be worth our while
3278 : */
3279 10742 : if (ScanDirectionIsForward(dir) &&
3280 10664 : pstate->offnum >= pstate->maxoff - LOOK_AHEAD_DEFAULT_DISTANCE)
3281 384 : return;
3282 10358 : else if (ScanDirectionIsBackward(dir) &&
3283 78 : pstate->offnum <= pstate->minoff + LOOK_AHEAD_DEFAULT_DISTANCE)
3284 24 : return;
3285 :
3286 : /*
3287 : * The look ahead distance starts small, and ramps up as each call here
3288 : * allows _bt_readpage to skip over more tuples
3289 : */
3290 10334 : if (!pstate->targetdistance)
3291 6268 : pstate->targetdistance = LOOK_AHEAD_DEFAULT_DISTANCE;
3292 4066 : else if (pstate->targetdistance < MaxIndexTuplesPerPage / 2)
3293 4066 : pstate->targetdistance *= 2;
3294 :
3295 : /* Don't read past the end (or before the start) of the page, though */
3296 10334 : if (ScanDirectionIsForward(dir))
3297 10280 : aheadoffnum = Min((int) pstate->maxoff,
3298 : (int) pstate->offnum + pstate->targetdistance);
3299 : else
3300 54 : aheadoffnum = Max((int) pstate->minoff,
3301 : (int) pstate->offnum - pstate->targetdistance);
3302 :
3303 10334 : ahead = (IndexTuple) PageGetItem(pstate->page,
3304 10334 : PageGetItemId(pstate->page, aheadoffnum));
3305 10334 : if (_bt_tuple_before_array_skeys(scan, dir, ahead, tupdesc, tupnatts,
3306 : false, 0, NULL))
3307 : {
3308 : /*
3309 : * Success -- instruct _bt_readpage to skip ahead to very next tuple
3310 : * after the one we determined was still before the current array keys
3311 : */
3312 3440 : if (ScanDirectionIsForward(dir))
3313 3404 : pstate->skip = aheadoffnum + 1;
3314 : else
3315 36 : pstate->skip = aheadoffnum - 1;
3316 : }
3317 : else
3318 : {
3319 : /*
3320 : * Failure -- "ahead" tuple is too far ahead (we were too aggressive).
3321 : *
3322 : * Reset the number of rechecks, and aggressively reduce the target
3323 : * distance (we're much more aggressive here than we were when the
3324 : * distance was initially ramped up).
3325 : */
3326 6894 : pstate->rechecks = 0;
3327 6894 : pstate->targetdistance = Max(pstate->targetdistance / 8, 1);
3328 : }
3329 : }
3330 :
3331 : /*
3332 : * _bt_killitems - set LP_DEAD state for items an indexscan caller has
3333 : * told us were killed
3334 : *
3335 : * scan->opaque, referenced locally through so, contains information about the
3336 : * current page and killed tuples thereon (generally, this should only be
3337 : * called if so->numKilled > 0).
3338 : *
3339 : * Caller should not have a lock on the so->currPos page, but must hold a
3340 : * buffer pin when !so->dropPin. When we return, it still won't be locked.
3341 : * It'll continue to hold whatever pins were held before calling here.
3342 : *
3343 : * We match items by heap TID before assuming they are the right ones to set
3344 : * LP_DEAD. If the scan is one that holds a buffer pin on the target page
3345 : * continuously from initially reading the items until applying this function
3346 : * (if it is a !so->dropPin scan), VACUUM cannot have deleted any items on the
3347 : * page, so the page's TIDs can't have been recycled by now. There's no risk
3348 : * that we'll confuse a new index tuple that happens to use a recycled TID
3349 : * with a now-removed tuple with the same TID (that used to be on this same
3350 : * page). We can't rely on that during scans that drop buffer pins eagerly
3351 : * (so->dropPin scans), though, so we must condition setting LP_DEAD bits on
3352 : * the page LSN having not changed since back when _bt_readpage saw the page.
3353 : * We totally give up on setting LP_DEAD bits when the page LSN changed.
3354 : *
3355 : * We give up much less often during !so->dropPin scans, but it still happens.
3356 : * We cope with cases where items have moved right due to insertions. If an
3357 : * item has moved off the current page due to a split, we'll fail to find it
3358 : * and just give up on it.
3359 : */
3360 : void
3361 171466 : _bt_killitems(IndexScanDesc scan)
3362 : {
3363 171466 : Relation rel = scan->indexRelation;
3364 171466 : BTScanOpaque so = (BTScanOpaque) scan->opaque;
3365 : Page page;
3366 : BTPageOpaque opaque;
3367 : OffsetNumber minoff;
3368 : OffsetNumber maxoff;
3369 171466 : int numKilled = so->numKilled;
3370 171466 : bool killedsomething = false;
3371 : Buffer buf;
3372 :
3373 : Assert(numKilled > 0);
3374 : Assert(BTScanPosIsValid(so->currPos));
3375 : Assert(scan->heapRelation != NULL); /* can't be a bitmap index scan */
3376 :
3377 : /* Always invalidate so->killedItems[] before leaving so->currPos */
3378 171466 : so->numKilled = 0;
3379 :
3380 171466 : if (!so->dropPin)
3381 : {
3382 : /*
3383 : * We have held the pin on this page since we read the index tuples,
3384 : * so all we need to do is lock it. The pin will have prevented
3385 : * concurrent VACUUMs from recycling any of the TIDs on the page.
3386 : */
3387 : Assert(BTScanPosIsPinned(so->currPos));
3388 39104 : buf = so->currPos.buf;
3389 39104 : _bt_lockbuf(rel, buf, BT_READ);
3390 : }
3391 : else
3392 : {
3393 : XLogRecPtr latestlsn;
3394 :
3395 : Assert(!BTScanPosIsPinned(so->currPos));
3396 : Assert(RelationNeedsWAL(rel));
3397 132362 : buf = _bt_getbuf(rel, so->currPos.currPage, BT_READ);
3398 :
3399 132362 : latestlsn = BufferGetLSNAtomic(buf);
3400 : Assert(!XLogRecPtrIsInvalid(so->currPos.lsn));
3401 : Assert(so->currPos.lsn <= latestlsn);
3402 132362 : if (so->currPos.lsn != latestlsn)
3403 : {
3404 : /* Modified, give up on hinting */
3405 134 : _bt_relbuf(rel, buf);
3406 134 : return;
3407 : }
3408 :
3409 : /* Unmodified, hinting is safe */
3410 : }
3411 :
3412 171332 : page = BufferGetPage(buf);
3413 171332 : opaque = BTPageGetOpaque(page);
3414 171332 : minoff = P_FIRSTDATAKEY(opaque);
3415 171332 : maxoff = PageGetMaxOffsetNumber(page);
3416 :
3417 656464 : for (int i = 0; i < numKilled; i++)
3418 : {
3419 485132 : int itemIndex = so->killedItems[i];
3420 485132 : BTScanPosItem *kitem = &so->currPos.items[itemIndex];
3421 485132 : OffsetNumber offnum = kitem->indexOffset;
3422 :
3423 : Assert(itemIndex >= so->currPos.firstItem &&
3424 : itemIndex <= so->currPos.lastItem);
3425 485132 : if (offnum < minoff)
3426 0 : continue; /* pure paranoia */
3427 9912206 : while (offnum <= maxoff)
3428 : {
3429 9836532 : ItemId iid = PageGetItemId(page, offnum);
3430 9836532 : IndexTuple ituple = (IndexTuple) PageGetItem(page, iid);
3431 9836532 : bool killtuple = false;
3432 :
3433 9836532 : if (BTreeTupleIsPosting(ituple))
3434 : {
3435 3019352 : int pi = i + 1;
3436 3019352 : int nposting = BTreeTupleGetNPosting(ituple);
3437 : int j;
3438 :
3439 : /*
3440 : * We rely on the convention that heap TIDs in the scanpos
3441 : * items array are stored in ascending heap TID order for a
3442 : * group of TIDs that originally came from a posting list
3443 : * tuple. This convention even applies during backwards
3444 : * scans, where returning the TIDs in descending order might
3445 : * seem more natural. This is about effectiveness, not
3446 : * correctness.
3447 : *
3448 : * Note that the page may have been modified in almost any way
3449 : * since we first read it (in the !so->dropPin case), so it's
3450 : * possible that this posting list tuple wasn't a posting list
3451 : * tuple when we first encountered its heap TIDs.
3452 : */
3453 3096664 : for (j = 0; j < nposting; j++)
3454 : {
3455 3094228 : ItemPointer item = BTreeTupleGetPostingN(ituple, j);
3456 :
3457 3094228 : if (!ItemPointerEquals(item, &kitem->heapTid))
3458 3016916 : break; /* out of posting list loop */
3459 :
3460 : /*
3461 : * kitem must have matching offnum when heap TIDs match,
3462 : * though only in the common case where the page can't
3463 : * have been concurrently modified
3464 : */
3465 : Assert(kitem->indexOffset == offnum || !so->dropPin);
3466 :
3467 : /*
3468 : * Read-ahead to later kitems here.
3469 : *
3470 : * We rely on the assumption that not advancing kitem here
3471 : * will prevent us from considering the posting list tuple
3472 : * fully dead by not matching its next heap TID in next
3473 : * loop iteration.
3474 : *
3475 : * If, on the other hand, this is the final heap TID in
3476 : * the posting list tuple, then tuple gets killed
3477 : * regardless (i.e. we handle the case where the last
3478 : * kitem is also the last heap TID in the last index tuple
3479 : * correctly -- posting tuple still gets killed).
3480 : */
3481 77312 : if (pi < numKilled)
3482 41440 : kitem = &so->currPos.items[so->killedItems[pi++]];
3483 : }
3484 :
3485 : /*
3486 : * Don't bother advancing the outermost loop's int iterator to
3487 : * avoid processing killed items that relate to the same
3488 : * offnum/posting list tuple. This micro-optimization hardly
3489 : * seems worth it. (Further iterations of the outermost loop
3490 : * will fail to match on this same posting list's first heap
3491 : * TID instead, so we'll advance to the next offnum/index
3492 : * tuple pretty quickly.)
3493 : */
3494 3019352 : if (j == nposting)
3495 2436 : killtuple = true;
3496 : }
3497 6817180 : else if (ItemPointerEquals(&ituple->t_tid, &kitem->heapTid))
3498 408232 : killtuple = true;
3499 :
3500 : /*
3501 : * Mark index item as dead, if it isn't already. Since this
3502 : * happens while holding a buffer lock possibly in shared mode,
3503 : * it's possible that multiple processes attempt to do this
3504 : * simultaneously, leading to multiple full-page images being sent
3505 : * to WAL (if wal_log_hints or data checksums are enabled), which
3506 : * is undesirable.
3507 : */
3508 9836532 : if (killtuple && !ItemIdIsDead(iid))
3509 : {
3510 : /* found the item/all posting list items */
3511 409458 : ItemIdMarkDead(iid);
3512 409458 : killedsomething = true;
3513 409458 : break; /* out of inner search loop */
3514 : }
3515 9427074 : offnum = OffsetNumberNext(offnum);
3516 : }
3517 : }
3518 :
3519 : /*
3520 : * Since this can be redone later if needed, mark as dirty hint.
3521 : *
3522 : * Whenever we mark anything LP_DEAD, we also set the page's
3523 : * BTP_HAS_GARBAGE flag, which is likewise just a hint. (Note that we
3524 : * only rely on the page-level flag in !heapkeyspace indexes.)
3525 : */
3526 171332 : if (killedsomething)
3527 : {
3528 134242 : opaque->btpo_flags |= BTP_HAS_GARBAGE;
3529 134242 : MarkBufferDirtyHint(buf, true);
3530 : }
3531 :
3532 171332 : if (!so->dropPin)
3533 39104 : _bt_unlockbuf(rel, buf);
3534 : else
3535 132228 : _bt_relbuf(rel, buf);
3536 : }
3537 :
3538 :
3539 : /*
3540 : * The following routines manage a shared-memory area in which we track
3541 : * assignment of "vacuum cycle IDs" to currently-active btree vacuuming
3542 : * operations. There is a single counter which increments each time we
3543 : * start a vacuum to assign it a cycle ID. Since multiple vacuums could
3544 : * be active concurrently, we have to track the cycle ID for each active
3545 : * vacuum; this requires at most MaxBackends entries (usually far fewer).
3546 : * We assume at most one vacuum can be active for a given index.
3547 : *
3548 : * Access to the shared memory area is controlled by BtreeVacuumLock.
3549 : * In principle we could use a separate lmgr locktag for each index,
3550 : * but a single LWLock is much cheaper, and given the short time that
3551 : * the lock is ever held, the concurrency hit should be minimal.
3552 : */
3553 :
3554 : typedef struct BTOneVacInfo
3555 : {
3556 : LockRelId relid; /* global identifier of an index */
3557 : BTCycleId cycleid; /* cycle ID for its active VACUUM */
3558 : } BTOneVacInfo;
3559 :
3560 : typedef struct BTVacInfo
3561 : {
3562 : BTCycleId cycle_ctr; /* cycle ID most recently assigned */
3563 : int num_vacuums; /* number of currently active VACUUMs */
3564 : int max_vacuums; /* allocated length of vacuums[] array */
3565 : BTOneVacInfo vacuums[FLEXIBLE_ARRAY_MEMBER];
3566 : } BTVacInfo;
3567 :
3568 : static BTVacInfo *btvacinfo;
3569 :
3570 :
3571 : /*
3572 : * _bt_vacuum_cycleid --- get the active vacuum cycle ID for an index,
3573 : * or zero if there is no active VACUUM
3574 : *
3575 : * Note: for correct interlocking, the caller must already hold pin and
3576 : * exclusive lock on each buffer it will store the cycle ID into. This
3577 : * ensures that even if a VACUUM starts immediately afterwards, it cannot
3578 : * process those pages until the page split is complete.
3579 : */
3580 : BTCycleId
3581 22452 : _bt_vacuum_cycleid(Relation rel)
3582 : {
3583 22452 : BTCycleId result = 0;
3584 : int i;
3585 :
3586 : /* Share lock is enough since this is a read-only operation */
3587 22452 : LWLockAcquire(BtreeVacuumLock, LW_SHARED);
3588 :
3589 22464 : for (i = 0; i < btvacinfo->num_vacuums; i++)
3590 : {
3591 14 : BTOneVacInfo *vac = &btvacinfo->vacuums[i];
3592 :
3593 14 : if (vac->relid.relId == rel->rd_lockInfo.lockRelId.relId &&
3594 2 : vac->relid.dbId == rel->rd_lockInfo.lockRelId.dbId)
3595 : {
3596 2 : result = vac->cycleid;
3597 2 : break;
3598 : }
3599 : }
3600 :
3601 22452 : LWLockRelease(BtreeVacuumLock);
3602 22452 : return result;
3603 : }
3604 :
3605 : /*
3606 : * _bt_start_vacuum --- assign a cycle ID to a just-starting VACUUM operation
3607 : *
3608 : * Note: the caller must guarantee that it will eventually call
3609 : * _bt_end_vacuum, else we'll permanently leak an array slot. To ensure
3610 : * that this happens even in elog(FATAL) scenarios, the appropriate coding
3611 : * is not just a PG_TRY, but
3612 : * PG_ENSURE_ERROR_CLEANUP(_bt_end_vacuum_callback, PointerGetDatum(rel))
3613 : */
3614 : BTCycleId
3615 2966 : _bt_start_vacuum(Relation rel)
3616 : {
3617 : BTCycleId result;
3618 : int i;
3619 : BTOneVacInfo *vac;
3620 :
3621 2966 : LWLockAcquire(BtreeVacuumLock, LW_EXCLUSIVE);
3622 :
3623 : /*
3624 : * Assign the next cycle ID, being careful to avoid zero as well as the
3625 : * reserved high values.
3626 : */
3627 2966 : result = ++(btvacinfo->cycle_ctr);
3628 2966 : if (result == 0 || result > MAX_BT_CYCLE_ID)
3629 0 : result = btvacinfo->cycle_ctr = 1;
3630 :
3631 : /* Let's just make sure there's no entry already for this index */
3632 2968 : for (i = 0; i < btvacinfo->num_vacuums; i++)
3633 : {
3634 2 : vac = &btvacinfo->vacuums[i];
3635 2 : if (vac->relid.relId == rel->rd_lockInfo.lockRelId.relId &&
3636 0 : vac->relid.dbId == rel->rd_lockInfo.lockRelId.dbId)
3637 : {
3638 : /*
3639 : * Unlike most places in the backend, we have to explicitly
3640 : * release our LWLock before throwing an error. This is because
3641 : * we expect _bt_end_vacuum() to be called before transaction
3642 : * abort cleanup can run to release LWLocks.
3643 : */
3644 0 : LWLockRelease(BtreeVacuumLock);
3645 0 : elog(ERROR, "multiple active vacuums for index \"%s\"",
3646 : RelationGetRelationName(rel));
3647 : }
3648 : }
3649 :
3650 : /* OK, add an entry */
3651 2966 : if (btvacinfo->num_vacuums >= btvacinfo->max_vacuums)
3652 : {
3653 0 : LWLockRelease(BtreeVacuumLock);
3654 0 : elog(ERROR, "out of btvacinfo slots");
3655 : }
3656 2966 : vac = &btvacinfo->vacuums[btvacinfo->num_vacuums];
3657 2966 : vac->relid = rel->rd_lockInfo.lockRelId;
3658 2966 : vac->cycleid = result;
3659 2966 : btvacinfo->num_vacuums++;
3660 :
3661 2966 : LWLockRelease(BtreeVacuumLock);
3662 2966 : return result;
3663 : }
3664 :
3665 : /*
3666 : * _bt_end_vacuum --- mark a btree VACUUM operation as done
3667 : *
3668 : * Note: this is deliberately coded not to complain if no entry is found;
3669 : * this allows the caller to put PG_TRY around the start_vacuum operation.
3670 : */
3671 : void
3672 2966 : _bt_end_vacuum(Relation rel)
3673 : {
3674 : int i;
3675 :
3676 2966 : LWLockAcquire(BtreeVacuumLock, LW_EXCLUSIVE);
3677 :
3678 : /* Find the array entry */
3679 2966 : for (i = 0; i < btvacinfo->num_vacuums; i++)
3680 : {
3681 2966 : BTOneVacInfo *vac = &btvacinfo->vacuums[i];
3682 :
3683 2966 : if (vac->relid.relId == rel->rd_lockInfo.lockRelId.relId &&
3684 2966 : vac->relid.dbId == rel->rd_lockInfo.lockRelId.dbId)
3685 : {
3686 : /* Remove it by shifting down the last entry */
3687 2966 : *vac = btvacinfo->vacuums[btvacinfo->num_vacuums - 1];
3688 2966 : btvacinfo->num_vacuums--;
3689 2966 : break;
3690 : }
3691 : }
3692 :
3693 2966 : LWLockRelease(BtreeVacuumLock);
3694 2966 : }
3695 :
3696 : /*
3697 : * _bt_end_vacuum wrapped as an on_shmem_exit callback function
3698 : */
3699 : void
3700 0 : _bt_end_vacuum_callback(int code, Datum arg)
3701 : {
3702 0 : _bt_end_vacuum((Relation) DatumGetPointer(arg));
3703 0 : }
3704 :
3705 : /*
3706 : * BTreeShmemSize --- report amount of shared memory space needed
3707 : */
3708 : Size
3709 6234 : BTreeShmemSize(void)
3710 : {
3711 : Size size;
3712 :
3713 6234 : size = offsetof(BTVacInfo, vacuums);
3714 6234 : size = add_size(size, mul_size(MaxBackends, sizeof(BTOneVacInfo)));
3715 6234 : return size;
3716 : }
3717 :
3718 : /*
3719 : * BTreeShmemInit --- initialize this module's shared memory
3720 : */
3721 : void
3722 2178 : BTreeShmemInit(void)
3723 : {
3724 : bool found;
3725 :
3726 2178 : btvacinfo = (BTVacInfo *) ShmemInitStruct("BTree Vacuum State",
3727 : BTreeShmemSize(),
3728 : &found);
3729 :
3730 2178 : if (!IsUnderPostmaster)
3731 : {
3732 : /* Initialize shared memory area */
3733 : Assert(!found);
3734 :
3735 : /*
3736 : * It doesn't really matter what the cycle counter starts at, but
3737 : * having it always start the same doesn't seem good. Seed with
3738 : * low-order bits of time() instead.
3739 : */
3740 2178 : btvacinfo->cycle_ctr = (BTCycleId) time(NULL);
3741 :
3742 2178 : btvacinfo->num_vacuums = 0;
3743 2178 : btvacinfo->max_vacuums = MaxBackends;
3744 : }
3745 : else
3746 : Assert(found);
3747 2178 : }
3748 :
3749 : bytea *
3750 322 : btoptions(Datum reloptions, bool validate)
3751 : {
3752 : static const relopt_parse_elt tab[] = {
3753 : {"fillfactor", RELOPT_TYPE_INT, offsetof(BTOptions, fillfactor)},
3754 : {"vacuum_cleanup_index_scale_factor", RELOPT_TYPE_REAL,
3755 : offsetof(BTOptions, vacuum_cleanup_index_scale_factor)},
3756 : {"deduplicate_items", RELOPT_TYPE_BOOL,
3757 : offsetof(BTOptions, deduplicate_items)}
3758 : };
3759 :
3760 322 : return (bytea *) build_reloptions(reloptions, validate,
3761 : RELOPT_KIND_BTREE,
3762 : sizeof(BTOptions),
3763 : tab, lengthof(tab));
3764 : }
3765 :
3766 : /*
3767 : * btproperty() -- Check boolean properties of indexes.
3768 : *
3769 : * This is optional, but handling AMPROP_RETURNABLE here saves opening the rel
3770 : * to call btcanreturn.
3771 : */
3772 : bool
3773 756 : btproperty(Oid index_oid, int attno,
3774 : IndexAMProperty prop, const char *propname,
3775 : bool *res, bool *isnull)
3776 : {
3777 756 : switch (prop)
3778 : {
3779 42 : case AMPROP_RETURNABLE:
3780 : /* answer only for columns, not AM or whole index */
3781 42 : if (attno == 0)
3782 12 : return false;
3783 : /* otherwise, btree can always return data */
3784 30 : *res = true;
3785 30 : return true;
3786 :
3787 714 : default:
3788 714 : return false; /* punt to generic code */
3789 : }
3790 : }
3791 :
3792 : /*
3793 : * btbuildphasename() -- Return name of index build phase.
3794 : */
3795 : char *
3796 0 : btbuildphasename(int64 phasenum)
3797 : {
3798 0 : switch (phasenum)
3799 : {
3800 0 : case PROGRESS_CREATEIDX_SUBPHASE_INITIALIZE:
3801 0 : return "initializing";
3802 0 : case PROGRESS_BTREE_PHASE_INDEXBUILD_TABLESCAN:
3803 0 : return "scanning table";
3804 0 : case PROGRESS_BTREE_PHASE_PERFORMSORT_1:
3805 0 : return "sorting live tuples";
3806 0 : case PROGRESS_BTREE_PHASE_PERFORMSORT_2:
3807 0 : return "sorting dead tuples";
3808 0 : case PROGRESS_BTREE_PHASE_LEAF_LOAD:
3809 0 : return "loading tuples in tree";
3810 0 : default:
3811 0 : return NULL;
3812 : }
3813 : }
3814 :
3815 : /*
3816 : * _bt_truncate() -- create tuple without unneeded suffix attributes.
3817 : *
3818 : * Returns truncated pivot index tuple allocated in caller's memory context,
3819 : * with key attributes copied from caller's firstright argument. If rel is
3820 : * an INCLUDE index, non-key attributes will definitely be truncated away,
3821 : * since they're not part of the key space. More aggressive suffix
3822 : * truncation can take place when it's clear that the returned tuple does not
3823 : * need one or more suffix key attributes. We only need to keep firstright
3824 : * attributes up to and including the first non-lastleft-equal attribute.
3825 : * Caller's insertion scankey is used to compare the tuples; the scankey's
3826 : * argument values are not considered here.
3827 : *
3828 : * Note that returned tuple's t_tid offset will hold the number of attributes
3829 : * present, so the original item pointer offset is not represented. Caller
3830 : * should only change truncated tuple's downlink. Note also that truncated
3831 : * key attributes are treated as containing "minus infinity" values by
3832 : * _bt_compare().
3833 : *
3834 : * In the worst case (when a heap TID must be appended to distinguish lastleft
3835 : * from firstright), the size of the returned tuple is the size of firstright
3836 : * plus the size of an additional MAXALIGN()'d item pointer. This guarantee
3837 : * is important, since callers need to stay under the 1/3 of a page
3838 : * restriction on tuple size. If this routine is ever taught to truncate
3839 : * within an attribute/datum, it will need to avoid returning an enlarged
3840 : * tuple to caller when truncation + TOAST compression ends up enlarging the
3841 : * final datum.
3842 : */
3843 : IndexTuple
3844 62170 : _bt_truncate(Relation rel, IndexTuple lastleft, IndexTuple firstright,
3845 : BTScanInsert itup_key)
3846 : {
3847 62170 : TupleDesc itupdesc = RelationGetDescr(rel);
3848 62170 : int16 nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
3849 : int keepnatts;
3850 : IndexTuple pivot;
3851 : IndexTuple tidpivot;
3852 : ItemPointer pivotheaptid;
3853 : Size newsize;
3854 :
3855 : /*
3856 : * We should only ever truncate non-pivot tuples from leaf pages. It's
3857 : * never okay to truncate when splitting an internal page.
3858 : */
3859 : Assert(!BTreeTupleIsPivot(lastleft) && !BTreeTupleIsPivot(firstright));
3860 :
3861 : /* Determine how many attributes must be kept in truncated tuple */
3862 62170 : keepnatts = _bt_keep_natts(rel, lastleft, firstright, itup_key);
3863 :
3864 : #ifdef DEBUG_NO_TRUNCATE
3865 : /* Force truncation to be ineffective for testing purposes */
3866 : keepnatts = nkeyatts + 1;
3867 : #endif
3868 :
3869 62170 : pivot = index_truncate_tuple(itupdesc, firstright,
3870 : Min(keepnatts, nkeyatts));
3871 :
3872 62170 : if (BTreeTupleIsPosting(pivot))
3873 : {
3874 : /*
3875 : * index_truncate_tuple() just returns a straight copy of firstright
3876 : * when it has no attributes to truncate. When that happens, we may
3877 : * need to truncate away a posting list here instead.
3878 : */
3879 : Assert(keepnatts == nkeyatts || keepnatts == nkeyatts + 1);
3880 : Assert(IndexRelationGetNumberOfAttributes(rel) == nkeyatts);
3881 1254 : pivot->t_info &= ~INDEX_SIZE_MASK;
3882 1254 : pivot->t_info |= MAXALIGN(BTreeTupleGetPostingOffset(firstright));
3883 : }
3884 :
3885 : /*
3886 : * If there is a distinguishing key attribute within pivot tuple, we're
3887 : * done
3888 : */
3889 62170 : if (keepnatts <= nkeyatts)
3890 : {
3891 61078 : BTreeTupleSetNAtts(pivot, keepnatts, false);
3892 61078 : return pivot;
3893 : }
3894 :
3895 : /*
3896 : * We have to store a heap TID in the new pivot tuple, since no non-TID
3897 : * key attribute value in firstright distinguishes the right side of the
3898 : * split from the left side. nbtree conceptualizes this case as an
3899 : * inability to truncate away any key attributes, since heap TID is
3900 : * treated as just another key attribute (despite lacking a pg_attribute
3901 : * entry).
3902 : *
3903 : * Use enlarged space that holds a copy of pivot. We need the extra space
3904 : * to store a heap TID at the end (using the special pivot tuple
3905 : * representation). Note that the original pivot already has firstright's
3906 : * possible posting list/non-key attribute values removed at this point.
3907 : */
3908 1092 : newsize = MAXALIGN(IndexTupleSize(pivot)) + MAXALIGN(sizeof(ItemPointerData));
3909 1092 : tidpivot = palloc0(newsize);
3910 1092 : memcpy(tidpivot, pivot, MAXALIGN(IndexTupleSize(pivot)));
3911 : /* Cannot leak memory here */
3912 1092 : pfree(pivot);
3913 :
3914 : /*
3915 : * Store all of firstright's key attribute values plus a tiebreaker heap
3916 : * TID value in enlarged pivot tuple
3917 : */
3918 1092 : tidpivot->t_info &= ~INDEX_SIZE_MASK;
3919 1092 : tidpivot->t_info |= newsize;
3920 1092 : BTreeTupleSetNAtts(tidpivot, nkeyatts, true);
3921 1092 : pivotheaptid = BTreeTupleGetHeapTID(tidpivot);
3922 :
3923 : /*
3924 : * Lehman & Yao use lastleft as the leaf high key in all cases, but don't
3925 : * consider suffix truncation. It seems like a good idea to follow that
3926 : * example in cases where no truncation takes place -- use lastleft's heap
3927 : * TID. (This is also the closest value to negative infinity that's
3928 : * legally usable.)
3929 : */
3930 1092 : ItemPointerCopy(BTreeTupleGetMaxHeapTID(lastleft), pivotheaptid);
3931 :
3932 : /*
3933 : * We're done. Assert() that heap TID invariants hold before returning.
3934 : *
3935 : * Lehman and Yao require that the downlink to the right page, which is to
3936 : * be inserted into the parent page in the second phase of a page split be
3937 : * a strict lower bound on items on the right page, and a non-strict upper
3938 : * bound for items on the left page. Assert that heap TIDs follow these
3939 : * invariants, since a heap TID value is apparently needed as a
3940 : * tiebreaker.
3941 : */
3942 : #ifndef DEBUG_NO_TRUNCATE
3943 : Assert(ItemPointerCompare(BTreeTupleGetMaxHeapTID(lastleft),
3944 : BTreeTupleGetHeapTID(firstright)) < 0);
3945 : Assert(ItemPointerCompare(pivotheaptid,
3946 : BTreeTupleGetHeapTID(lastleft)) >= 0);
3947 : Assert(ItemPointerCompare(pivotheaptid,
3948 : BTreeTupleGetHeapTID(firstright)) < 0);
3949 : #else
3950 :
3951 : /*
3952 : * Those invariants aren't guaranteed to hold for lastleft + firstright
3953 : * heap TID attribute values when they're considered here only because
3954 : * DEBUG_NO_TRUNCATE is defined (a heap TID is probably not actually
3955 : * needed as a tiebreaker). DEBUG_NO_TRUNCATE must therefore use a heap
3956 : * TID value that always works as a strict lower bound for items to the
3957 : * right. In particular, it must avoid using firstright's leading key
3958 : * attribute values along with lastleft's heap TID value when lastleft's
3959 : * TID happens to be greater than firstright's TID.
3960 : */
3961 : ItemPointerCopy(BTreeTupleGetHeapTID(firstright), pivotheaptid);
3962 :
3963 : /*
3964 : * Pivot heap TID should never be fully equal to firstright. Note that
3965 : * the pivot heap TID will still end up equal to lastleft's heap TID when
3966 : * that's the only usable value.
3967 : */
3968 : ItemPointerSetOffsetNumber(pivotheaptid,
3969 : OffsetNumberPrev(ItemPointerGetOffsetNumber(pivotheaptid)));
3970 : Assert(ItemPointerCompare(pivotheaptid,
3971 : BTreeTupleGetHeapTID(firstright)) < 0);
3972 : #endif
3973 :
3974 1092 : return tidpivot;
3975 : }
3976 :
3977 : /*
3978 : * _bt_keep_natts - how many key attributes to keep when truncating.
3979 : *
3980 : * Caller provides two tuples that enclose a split point. Caller's insertion
3981 : * scankey is used to compare the tuples; the scankey's argument values are
3982 : * not considered here.
3983 : *
3984 : * This can return a number of attributes that is one greater than the
3985 : * number of key attributes for the index relation. This indicates that the
3986 : * caller must use a heap TID as a unique-ifier in new pivot tuple.
3987 : */
3988 : static int
3989 62170 : _bt_keep_natts(Relation rel, IndexTuple lastleft, IndexTuple firstright,
3990 : BTScanInsert itup_key)
3991 : {
3992 62170 : int nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
3993 62170 : TupleDesc itupdesc = RelationGetDescr(rel);
3994 : int keepnatts;
3995 : ScanKey scankey;
3996 :
3997 : /*
3998 : * _bt_compare() treats truncated key attributes as having the value minus
3999 : * infinity, which would break searches within !heapkeyspace indexes. We
4000 : * must still truncate away non-key attribute values, though.
4001 : */
4002 62170 : if (!itup_key->heapkeyspace)
4003 0 : return nkeyatts;
4004 :
4005 62170 : scankey = itup_key->scankeys;
4006 62170 : keepnatts = 1;
4007 74980 : for (int attnum = 1; attnum <= nkeyatts; attnum++, scankey++)
4008 : {
4009 : Datum datum1,
4010 : datum2;
4011 : bool isNull1,
4012 : isNull2;
4013 :
4014 73888 : datum1 = index_getattr(lastleft, attnum, itupdesc, &isNull1);
4015 73888 : datum2 = index_getattr(firstright, attnum, itupdesc, &isNull2);
4016 :
4017 73888 : if (isNull1 != isNull2)
4018 61078 : break;
4019 :
4020 147746 : if (!isNull1 &&
4021 73858 : DatumGetInt32(FunctionCall2Coll(&scankey->sk_func,
4022 : scankey->sk_collation,
4023 : datum1,
4024 : datum2)) != 0)
4025 61078 : break;
4026 :
4027 12810 : keepnatts++;
4028 : }
4029 :
4030 : /*
4031 : * Assert that _bt_keep_natts_fast() agrees with us in passing. This is
4032 : * expected in an allequalimage index.
4033 : */
4034 : Assert(!itup_key->allequalimage ||
4035 : keepnatts == _bt_keep_natts_fast(rel, lastleft, firstright));
4036 :
4037 62170 : return keepnatts;
4038 : }
4039 :
4040 : /*
4041 : * _bt_keep_natts_fast - fast bitwise variant of _bt_keep_natts.
4042 : *
4043 : * This is exported so that a candidate split point can have its effect on
4044 : * suffix truncation inexpensively evaluated ahead of time when finding a
4045 : * split location. A naive bitwise approach to datum comparisons is used to
4046 : * save cycles.
4047 : *
4048 : * The approach taken here usually provides the same answer as _bt_keep_natts
4049 : * will (for the same pair of tuples from a heapkeyspace index), since the
4050 : * majority of btree opclasses can never indicate that two datums are equal
4051 : * unless they're bitwise equal after detoasting. When an index only has
4052 : * "equal image" columns, routine is guaranteed to give the same result as
4053 : * _bt_keep_natts would.
4054 : *
4055 : * Callers can rely on the fact that attributes considered equal here are
4056 : * definitely also equal according to _bt_keep_natts, even when the index uses
4057 : * an opclass or collation that is not "allequalimage"/deduplication-safe.
4058 : * This weaker guarantee is good enough for nbtsplitloc.c caller, since false
4059 : * negatives generally only have the effect of making leaf page splits use a
4060 : * more balanced split point.
4061 : */
4062 : int
4063 13425996 : _bt_keep_natts_fast(Relation rel, IndexTuple lastleft, IndexTuple firstright)
4064 : {
4065 13425996 : TupleDesc itupdesc = RelationGetDescr(rel);
4066 13425996 : int keysz = IndexRelationGetNumberOfKeyAttributes(rel);
4067 : int keepnatts;
4068 :
4069 13425996 : keepnatts = 1;
4070 22628226 : for (int attnum = 1; attnum <= keysz; attnum++)
4071 : {
4072 : Datum datum1,
4073 : datum2;
4074 : bool isNull1,
4075 : isNull2;
4076 : CompactAttribute *att;
4077 :
4078 20248438 : datum1 = index_getattr(lastleft, attnum, itupdesc, &isNull1);
4079 20248438 : datum2 = index_getattr(firstright, attnum, itupdesc, &isNull2);
4080 20248438 : att = TupleDescCompactAttr(itupdesc, attnum - 1);
4081 :
4082 20248438 : if (isNull1 != isNull2)
4083 11046208 : break;
4084 :
4085 20248234 : if (!isNull1 &&
4086 20201178 : !datum_image_eq(datum1, datum2, att->attbyval, att->attlen))
4087 11046004 : break;
4088 :
4089 9202230 : keepnatts++;
4090 : }
4091 :
4092 13425996 : return keepnatts;
4093 : }
4094 :
4095 : /*
4096 : * _bt_check_natts() -- Verify tuple has expected number of attributes.
4097 : *
4098 : * Returns value indicating if the expected number of attributes were found
4099 : * for a particular offset on page. This can be used as a general purpose
4100 : * sanity check.
4101 : *
4102 : * Testing a tuple directly with BTreeTupleGetNAtts() should generally be
4103 : * preferred to calling here. That's usually more convenient, and is always
4104 : * more explicit. Call here instead when offnum's tuple may be a negative
4105 : * infinity tuple that uses the pre-v11 on-disk representation, or when a low
4106 : * context check is appropriate. This routine is as strict as possible about
4107 : * what is expected on each version of btree.
4108 : */
4109 : bool
4110 4058730 : _bt_check_natts(Relation rel, bool heapkeyspace, Page page, OffsetNumber offnum)
4111 : {
4112 4058730 : int16 natts = IndexRelationGetNumberOfAttributes(rel);
4113 4058730 : int16 nkeyatts = IndexRelationGetNumberOfKeyAttributes(rel);
4114 4058730 : BTPageOpaque opaque = BTPageGetOpaque(page);
4115 : IndexTuple itup;
4116 : int tupnatts;
4117 :
4118 : /*
4119 : * We cannot reliably test a deleted or half-dead page, since they have
4120 : * dummy high keys
4121 : */
4122 4058730 : if (P_IGNORE(opaque))
4123 0 : return true;
4124 :
4125 : Assert(offnum >= FirstOffsetNumber &&
4126 : offnum <= PageGetMaxOffsetNumber(page));
4127 :
4128 4058730 : itup = (IndexTuple) PageGetItem(page, PageGetItemId(page, offnum));
4129 4058730 : tupnatts = BTreeTupleGetNAtts(itup, rel);
4130 :
4131 : /* !heapkeyspace indexes do not support deduplication */
4132 4058730 : if (!heapkeyspace && BTreeTupleIsPosting(itup))
4133 0 : return false;
4134 :
4135 : /* Posting list tuples should never have "pivot heap TID" bit set */
4136 4058730 : if (BTreeTupleIsPosting(itup) &&
4137 21928 : (ItemPointerGetOffsetNumberNoCheck(&itup->t_tid) &
4138 : BT_PIVOT_HEAP_TID_ATTR) != 0)
4139 0 : return false;
4140 :
4141 : /* INCLUDE indexes do not support deduplication */
4142 4058730 : if (natts != nkeyatts && BTreeTupleIsPosting(itup))
4143 0 : return false;
4144 :
4145 4058730 : if (P_ISLEAF(opaque))
4146 : {
4147 4044378 : if (offnum >= P_FIRSTDATAKEY(opaque))
4148 : {
4149 : /*
4150 : * Non-pivot tuple should never be explicitly marked as a pivot
4151 : * tuple
4152 : */
4153 4031146 : if (BTreeTupleIsPivot(itup))
4154 0 : return false;
4155 :
4156 : /*
4157 : * Leaf tuples that are not the page high key (non-pivot tuples)
4158 : * should never be truncated. (Note that tupnatts must have been
4159 : * inferred, even with a posting list tuple, because only pivot
4160 : * tuples store tupnatts directly.)
4161 : */
4162 4031146 : return tupnatts == natts;
4163 : }
4164 : else
4165 : {
4166 : /*
4167 : * Rightmost page doesn't contain a page high key, so tuple was
4168 : * checked above as ordinary leaf tuple
4169 : */
4170 : Assert(!P_RIGHTMOST(opaque));
4171 :
4172 : /*
4173 : * !heapkeyspace high key tuple contains only key attributes. Note
4174 : * that tupnatts will only have been explicitly represented in
4175 : * !heapkeyspace indexes that happen to have non-key attributes.
4176 : */
4177 13232 : if (!heapkeyspace)
4178 0 : return tupnatts == nkeyatts;
4179 :
4180 : /* Use generic heapkeyspace pivot tuple handling */
4181 : }
4182 : }
4183 : else /* !P_ISLEAF(opaque) */
4184 : {
4185 14352 : if (offnum == P_FIRSTDATAKEY(opaque))
4186 : {
4187 : /*
4188 : * The first tuple on any internal page (possibly the first after
4189 : * its high key) is its negative infinity tuple. Negative
4190 : * infinity tuples are always truncated to zero attributes. They
4191 : * are a particular kind of pivot tuple.
4192 : */
4193 1114 : if (heapkeyspace)
4194 1114 : return tupnatts == 0;
4195 :
4196 : /*
4197 : * The number of attributes won't be explicitly represented if the
4198 : * negative infinity tuple was generated during a page split that
4199 : * occurred with a version of Postgres before v11. There must be
4200 : * a problem when there is an explicit representation that is
4201 : * non-zero, or when there is no explicit representation and the
4202 : * tuple is evidently not a pre-pg_upgrade tuple.
4203 : *
4204 : * Prior to v11, downlinks always had P_HIKEY as their offset.
4205 : * Accept that as an alternative indication of a valid
4206 : * !heapkeyspace negative infinity tuple.
4207 : */
4208 0 : return tupnatts == 0 ||
4209 0 : ItemPointerGetOffsetNumber(&(itup->t_tid)) == P_HIKEY;
4210 : }
4211 : else
4212 : {
4213 : /*
4214 : * !heapkeyspace downlink tuple with separator key contains only
4215 : * key attributes. Note that tupnatts will only have been
4216 : * explicitly represented in !heapkeyspace indexes that happen to
4217 : * have non-key attributes.
4218 : */
4219 13238 : if (!heapkeyspace)
4220 0 : return tupnatts == nkeyatts;
4221 :
4222 : /* Use generic heapkeyspace pivot tuple handling */
4223 : }
4224 : }
4225 :
4226 : /* Handle heapkeyspace pivot tuples (excluding minus infinity items) */
4227 : Assert(heapkeyspace);
4228 :
4229 : /*
4230 : * Explicit representation of the number of attributes is mandatory with
4231 : * heapkeyspace index pivot tuples, regardless of whether or not there are
4232 : * non-key attributes.
4233 : */
4234 26470 : if (!BTreeTupleIsPivot(itup))
4235 0 : return false;
4236 :
4237 : /* Pivot tuple should not use posting list representation (redundant) */
4238 26470 : if (BTreeTupleIsPosting(itup))
4239 0 : return false;
4240 :
4241 : /*
4242 : * Heap TID is a tiebreaker key attribute, so it cannot be untruncated
4243 : * when any other key attribute is truncated
4244 : */
4245 26470 : if (BTreeTupleGetHeapTID(itup) != NULL && tupnatts != nkeyatts)
4246 0 : return false;
4247 :
4248 : /*
4249 : * Pivot tuple must have at least one untruncated key attribute (minus
4250 : * infinity pivot tuples are the only exception). Pivot tuples can never
4251 : * represent that there is a value present for a key attribute that
4252 : * exceeds pg_index.indnkeyatts for the index.
4253 : */
4254 26470 : return tupnatts > 0 && tupnatts <= nkeyatts;
4255 : }
4256 :
4257 : /*
4258 : *
4259 : * _bt_check_third_page() -- check whether tuple fits on a btree page at all.
4260 : *
4261 : * We actually need to be able to fit three items on every page, so restrict
4262 : * any one item to 1/3 the per-page available space. Note that itemsz should
4263 : * not include the ItemId overhead.
4264 : *
4265 : * It might be useful to apply TOAST methods rather than throw an error here.
4266 : * Using out of line storage would break assumptions made by suffix truncation
4267 : * and by contrib/amcheck, though.
4268 : */
4269 : void
4270 264 : _bt_check_third_page(Relation rel, Relation heap, bool needheaptidspace,
4271 : Page page, IndexTuple newtup)
4272 : {
4273 : Size itemsz;
4274 : BTPageOpaque opaque;
4275 :
4276 264 : itemsz = MAXALIGN(IndexTupleSize(newtup));
4277 :
4278 : /* Double check item size against limit */
4279 264 : if (itemsz <= BTMaxItemSize)
4280 0 : return;
4281 :
4282 : /*
4283 : * Tuple is probably too large to fit on page, but it's possible that the
4284 : * index uses version 2 or version 3, or that page is an internal page, in
4285 : * which case a slightly higher limit applies.
4286 : */
4287 264 : if (!needheaptidspace && itemsz <= BTMaxItemSizeNoHeapTid)
4288 264 : return;
4289 :
4290 : /*
4291 : * Internal page insertions cannot fail here, because that would mean that
4292 : * an earlier leaf level insertion that should have failed didn't
4293 : */
4294 0 : opaque = BTPageGetOpaque(page);
4295 0 : if (!P_ISLEAF(opaque))
4296 0 : elog(ERROR, "cannot insert oversized tuple of size %zu on internal page of index \"%s\"",
4297 : itemsz, RelationGetRelationName(rel));
4298 :
4299 0 : ereport(ERROR,
4300 : (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
4301 : errmsg("index row size %zu exceeds btree version %u maximum %zu for index \"%s\"",
4302 : itemsz,
4303 : needheaptidspace ? BTREE_VERSION : BTREE_NOVAC_VERSION,
4304 : needheaptidspace ? BTMaxItemSize : BTMaxItemSizeNoHeapTid,
4305 : RelationGetRelationName(rel)),
4306 : errdetail("Index row references tuple (%u,%u) in relation \"%s\".",
4307 : ItemPointerGetBlockNumber(BTreeTupleGetHeapTID(newtup)),
4308 : ItemPointerGetOffsetNumber(BTreeTupleGetHeapTID(newtup)),
4309 : RelationGetRelationName(heap)),
4310 : errhint("Values larger than 1/3 of a buffer page cannot be indexed.\n"
4311 : "Consider a function index of an MD5 hash of the value, "
4312 : "or use full text indexing."),
4313 : errtableconstraint(heap, RelationGetRelationName(rel))));
4314 : }
4315 :
4316 : /*
4317 : * Are all attributes in rel "equality is image equality" attributes?
4318 : *
4319 : * We use each attribute's BTEQUALIMAGE_PROC opclass procedure. If any
4320 : * opclass either lacks a BTEQUALIMAGE_PROC procedure or returns false, we
4321 : * return false; otherwise we return true.
4322 : *
4323 : * Returned boolean value is stored in index metapage during index builds.
4324 : * Deduplication can only be used when we return true.
4325 : */
4326 : bool
4327 58546 : _bt_allequalimage(Relation rel, bool debugmessage)
4328 : {
4329 58546 : bool allequalimage = true;
4330 :
4331 : /* INCLUDE indexes can never support deduplication */
4332 58546 : if (IndexRelationGetNumberOfAttributes(rel) !=
4333 58546 : IndexRelationGetNumberOfKeyAttributes(rel))
4334 272 : return false;
4335 :
4336 153746 : for (int i = 0; i < IndexRelationGetNumberOfKeyAttributes(rel); i++)
4337 : {
4338 95990 : Oid opfamily = rel->rd_opfamily[i];
4339 95990 : Oid opcintype = rel->rd_opcintype[i];
4340 95990 : Oid collation = rel->rd_indcollation[i];
4341 : Oid equalimageproc;
4342 :
4343 95990 : equalimageproc = get_opfamily_proc(opfamily, opcintype, opcintype,
4344 : BTEQUALIMAGE_PROC);
4345 :
4346 : /*
4347 : * If there is no BTEQUALIMAGE_PROC then deduplication is assumed to
4348 : * be unsafe. Otherwise, actually call proc and see what it says.
4349 : */
4350 95990 : if (!OidIsValid(equalimageproc) ||
4351 95516 : !DatumGetBool(OidFunctionCall1Coll(equalimageproc, collation,
4352 : ObjectIdGetDatum(opcintype))))
4353 : {
4354 518 : allequalimage = false;
4355 518 : break;
4356 : }
4357 : }
4358 :
4359 58274 : if (debugmessage)
4360 : {
4361 50254 : if (allequalimage)
4362 49736 : elog(DEBUG1, "index \"%s\" can safely use deduplication",
4363 : RelationGetRelationName(rel));
4364 : else
4365 518 : elog(DEBUG1, "index \"%s\" cannot use deduplication",
4366 : RelationGetRelationName(rel));
4367 : }
4368 :
4369 58274 : return allequalimage;
4370 : }
|
