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