GCC Code Coverage Report


Directory: src/
File: src/pg/inspect.c
Date: 2026-11-18 16:12:57
Exec Total Coverage
Lines: 391 416 94.0%
Functions: 18 18 100.0%
Branches: 154 184 83.7%

Line Branch Exec Source
1 /*
2 * Copyright (c) 2026 Tiger Data, Inc.
3 * Licensed under the PostgreSQL License. See LICENSE for details.
4 *
5 * inspect.c - read-only index inspection functions
6 *
7 * Set-returning functions that expose the internal structure of prism
8 * indexes via SQL. All are read-only (AccessShareLock, no WAL); the mutating
9 * maintenance operations live in maintenance.c. The centroid-tree leaf walk
10 * they share, collect_leaf_entries, is declared in inspect.h.
11 *
12 * Functions:
13 * prism_centroid_pages(regclass) -- centroid tree structure
14 * prism_posting_pages(regclass) -- posting list page chains
15 * prism_tids_clusters(regclass, tid[]) -- which cluster(s) hold each TID
16 * prism_index_settings(regclass) -- effective (resolved) settings
17 */
18
19 #include <postgres.h>
20
21 #include <access/genam.h>
22 #include <catalog/index.h>
23 #include <catalog/pg_class.h>
24 #include <catalog/pg_type.h>
25 #include <funcapi.h>
26 #include <miscadmin.h>
27 #include <nodes/parsenodes.h>
28 #include <storage/bufmgr.h>
29 #include <utils/acl.h>
30 #include <utils/array.h>
31 #include <utils/builtins.h>
32 #include <utils/lsyscache.h>
33 #include <utils/rel.h>
34 #include <utils/syscache.h>
35 #include <utils/tuplestore.h>
36
37 #include "index/centroid_page.h"
38 #include "index/index_base.h"
39 #include "index/index_build.h"
40 #include "index/posting_page.h"
41 #include "index/query_scan.h"
42 #include "inspect.h"
43 #include "meta.h"
44 #include "pg/bufstorage.h"
45 #include "support_pg.h"
46
47 28 PG_FUNCTION_INFO_V1(vs_centroid_pages);
48 43 PG_FUNCTION_INFO_V1(vs_posting_pages);
49 10 PG_FUNCTION_INFO_V1(vs_tids_clusters);
50 18 PG_FUNCTION_INFO_V1(vs_index_settings);
51
52 /*
53 * The functions below iterate an on-disk entry_count read straight from a
54 * page. Reject a count past the format's real per-page capacity before
55 * looping so a corrupt or truncated page can't drive a read past the page.
56 * Posting pages get the same treatment from prism_posting_check_count.
57 */
58 static void
59 22795 check_centroid_count(
60 BlockNumber blkno,
61 uint32_t count,
62 Dimension dim,
63 PrismCentroidFormat fmt)
64 {
65 22795 uint32_t max_entries = prism_centroid_max_entries_fmt(dim, fmt);
66
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 22795 times.
22795 if (count > max_entries)
67 ✗ ereport(ERROR,
68 (errcode(ERRCODE_DATA_CORRUPTED),
69 errmsg("centroid page %u has an invalid entry count "
70 "(%u > %u)",
71 blkno,
72 count,
73 max_entries),
74 errhint("The index may be corrupted; REINDEX it.")));
75 22795 }
76
77 /*
78 * Authorization for the inspection functions. They expose an index's
79 * internal structure (block numbers, cluster ids, tombstone state), so
80 * gate them on the caller's privileges on the *table* the index belongs
81 * to -- the same model PostgreSQL's pgrowlocks/pgstattuple use for
82 * relation inspection. EXECUTE stays granted to PUBLIC; these runtime
83 * checks do the per-object authorization that a static GRANT cannot
84 * express for a regclass argument. Superusers pass automatically.
85 *
86 * Read-only inspectors require SELECT on the table (its owner has that, so an
87 * owner can always inspect their own index). prism_tids_clusters is the
88 * exception: it answers which rows live where, so it requires ownership.
89 * The mutating maintenance functions check ownership separately.
90 */
91 static void
92 220 require_index_select(Relation index, LOCKMODE lockmode)
93 {
94 220 Oid heaprelid = IndexGetRelation(RelationGetRelid(index), false);
95 220 AclResult aclresult =
96 220 pg_class_aclcheck(heaprelid, GetUserId(), ACL_SELECT);
97
2/2
✓ Branch 0 taken 3 times.
✓ Branch 1 taken 217 times.
220 if (aclresult != ACLCHECK_OK)
98 {
99 3 char *relname = get_rel_name(heaprelid);
100 3 ObjectType objtype = get_relkind_objtype(get_rel_relkind(heaprelid));
101 3 index_close(index, lockmode);
102 3 aclcheck_error(aclresult, objtype, relname);
103 }
104 217 }
105
106 /* Same ownership gate as the maintenance procedures. A SELECT grant is not
107 * enough: the function confirms which TIDs the index holds. */
108 static void
109 7 require_index_owner(Relation index, LOCKMODE lockmode)
110 {
111 7 Oid heaprelid = IndexGetRelation(RelationGetRelid(index), false);
112
2/2
✓ Branch 2 taken 2 times.
✓ Branch 3 taken 5 times.
7 if (!object_ownercheck(RelationRelationId, heaprelid, GetUserId()))
113 {
114 2 char *relname = get_rel_name(heaprelid);
115 2 ObjectType objtype = get_relkind_objtype(get_rel_relkind(heaprelid));
116 2 index_close(index, lockmode);
117 2 aclcheck_error(ACLCHECK_NOT_OWNER, objtype, relname);
118 }
119 5 }
120
121 /* ----------------------------------------------------------------
122 * Shared helpers
123 * ---------------------------------------------------------------- */
124
125 /*
126 * Grow a doubling array before an append: when len has reached *cap, double
127 * *cap and repalloc. Returns the (possibly moved) base pointer; pass
128 * sizeof(*arr) as elem_size. A no-op with room to spare, so it is safe to call
129 * unconditionally before every append.
130 */
131 static void *
132 92575 grow_if_full(void *arr, int len, int *cap, Size elem_size)
133 {
134 92575 if (len < *cap)
135 return arr;
136 787 *cap *= 2;
137 787 return repalloc(arr, (Size)*cap * elem_size);
138 }
139
140 /*
141 * BFS the centroid tree and collect all leaf entries. Returns the count and
142 * fills *out (palloc'd array). Caller must pfree. Declared in inspect.h and
143 * shared with the maintenance functions; LeafEntry is defined there too.
144 */
145 int
146 453 collect_leaf_entries(
147 Relation index,
148 BlockNumber first_centroid,
149 uint8_t nlevels,
150 Dimension dim,
151 LeafEntry **out)
152 {
153 453 VsPgStorage store;
154 453 VsStorage *st = &store.base;
155
156 453 vs_pg_storage_init_inspect(&store, index);
157
158 453 int wl_cap = 64;
159 453 int wl_len = 0;
160 453 int wl_head = 0;
161 453 BlockNumber *wl = palloc(wl_cap * sizeof(BlockNumber));
162
163 453 int leaves_cap = 64;
164 453 int leaves_len = 0;
165 453 LeafEntry *leaves = palloc(leaves_cap * sizeof(LeafEntry));
166
167 453 wl[wl_len++] = first_centroid;
168
169
2/2
✓ Branch 0 taken 22483 times.
✓ Branch 1 taken 453 times.
22936 while (wl_head < wl_len)
170 {
171 22483 BlockNumber blkno = wl[wl_head++];
172
173 22483 Page page = vs_storage_read_page(st, blkno);
174
175 22483 const PrismCentroidPageOpaque *opaque = PRISM_CENTROID_OPAQUE(page);
176 22483 uint16_t nentries = opaque->entry_count;
177 22483 PrismCentroidFormat fmt =
178 22483 (PrismCentroidFormat)(opaque->flags & PRISM_CENTROID_FMT_MASK);
179 22483 bool is_leaf_page = (opaque->level == nlevels - 1);
180
181 22483 check_centroid_count(blkno, nentries, dim, fmt);
182
183
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 22482 times.
22483 if (BlockNumberIsValid(opaque->next_blkno))
184 {
185
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 1 times.
1 wl = grow_if_full(wl, wl_len, &wl_cap, sizeof(*wl));
186 1 wl[wl_len++] = opaque->next_blkno;
187 }
188
189
2/2
✓ Branch 0 taken 92574 times.
✓ Branch 1 taken 22483 times.
115057 for (uint16_t i = 0; i < nentries; i++)
190 {
191 92574 BlockNumber child;
192 92574 bool is_leaf;
193
194
2/2
✓ Branch 0 taken 90614 times.
✓ Branch 1 taken 1960 times.
92574 if (fmt == PRISM_CENTROID_FMT_FASTSCAN)
195 {
196 /* No per-entry meta: read the child from the packed
197 * group array and take leaf status from the page level. */
198 90614 char *content = (char *)PageGetContents(page);
199 90614 uint32_t g = i / VS_FASTSCAN_GROUP;
200 90614 uint32_t slot = i % VS_FASTSCAN_GROUP;
201 90614 BlockNumber *grp =
202 90614 prism_centroid_fastscan_group_child(content, g, dim);
203 90614 child = grp[slot];
204 90614 is_leaf = is_leaf_page;
205 }
206 else
207 {
208 1960 const PrismCentroidEntryMeta *entry =
209 1960 prism_centroid_meta(page, i);
210 1960 child = entry->child_blkno;
211 1960 is_leaf = (entry->flags & PRISM_CENTROID_FLAG_LEAF) != 0;
212 }
213
214
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 92574 times.
92574 if (!BlockNumberIsValid(child))
215 ✗ continue;
216
217
2/2
✓ Branch 0 taken 70545 times.
✓ Branch 1 taken 22029 times.
92574 if (is_leaf)
218 {
219
2/2
✓ Branch 0 taken 526 times.
✓ Branch 1 taken 70019 times.
70545 leaves = grow_if_full(
220 leaves, leaves_len, &leaves_cap, sizeof(*leaves));
221 70545 leaves[leaves_len++] = (LeafEntry){
222 .posting_head = child,
223 .centroid_page = blkno,
224 .entry_idx = i,
225 };
226 }
227 else
228 {
229
2/2
✓ Branch 0 taken 261 times.
✓ Branch 1 taken 21768 times.
22029 wl = grow_if_full(wl, wl_len, &wl_cap, sizeof(*wl));
230 22029 wl[wl_len++] = child;
231 }
232 }
233
234 22483 vs_storage_release_page(st, blkno);
235 }
236
237 453 pfree(wl);
238 453 *out = leaves;
239 453 return leaves_len;
240 }
241
242 /* Format name lookup (indexed by PrismCentroidFormat) */
243 static const char *centroid_format_names[] = {
244 [PRISM_CENTROID_FMT_RABITQ] = "rabitq",
245 [PRISM_CENTROID_FMT_FLOAT] = "float",
246 [PRISM_CENTROID_FMT_HALF] = "half",
247 [PRISM_CENTROID_FMT_FASTSCAN] = "fastscan",
248 };
249
250 /*
251 * vs_centroid_pages(regclass)
252 *
253 * Returns one row per centroid entry: blkno, entry, level, format,
254 * child_blkno, child_count, is_leaf. Traverses the tree via BFS
255 * starting from the metapage's first_centroid, following next_blkno
256 * chains and child_blkno links.
257 */
258 Datum
259 44 vs_centroid_pages(PG_FUNCTION_ARGS)
260 {
261 44 Oid indexoid = PG_GETARG_OID(0);
262 44 ReturnSetInfo *rsinfo = (ReturnSetInfo *)fcinfo->resultinfo;
263
264 44 InitMaterializedSRF(fcinfo, 0);
265
266 44 Relation index = index_open(indexoid, AccessShareLock);
267
268 44 prism_check_index(index);
269 43 require_index_select(index, AccessShareLock);
270
271 42 VsPgStorage store;
272 42 VsStorage *st = &store.base;
273
274 42 vs_pg_storage_init_inspect(&store, index);
275
276 /* Read metapage and verify magic */
277 42 Page meta_page = vs_storage_read_page(st, 0);
278
279 42 const PrismMetaPage *meta = (const PrismMetaPage *)PageGetSpecialPointer(
280 meta_page);
281
282
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 42 times.
42 if (meta->magic != PRISM_META_MAGIC)
283 {
284 ✗ vs_storage_release_page(st, 0);
285 ✗ index_close(index, AccessShareLock);
286 ✗ ereport(ERROR,
287 (errcode(ERRCODE_WRONG_OBJECT_TYPE),
288 errmsg("\"%s\" is not a prism index",
289 RelationGetRelationName(index))));
290 }
291
292 42 BlockNumber first_centroid = meta->first_centroid;
293 42 Dimension dim = (Dimension)meta->dim;
294 42 uint8_t nlevels = meta->nlevels;
295
296 42 vs_storage_release_page(st, 0);
297
298
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 42 times.
42 if (!BlockNumberIsValid(first_centroid))
299 {
300 ✗ index_close(index, AccessShareLock);
301 ✗ PG_RETURN_NULL();
302 }
303
304 /*
305 * BFS worklist — simple dynamic array of block numbers.
306 * Start with the root centroid page.
307 */
308 42 int worklist_cap = 64;
309 42 int worklist_len = 0;
310 42 int worklist_head = 0;
311 42 BlockNumber *worklist = palloc(worklist_cap * sizeof(BlockNumber));
312
313 42 worklist[worklist_len++] = first_centroid;
314
315
2/2
✓ Branch 0 taken 312 times.
✓ Branch 1 taken 42 times.
354 while (worklist_head < worklist_len)
316 {
317 312 BlockNumber blkno = worklist[worklist_head++];
318
319 312 Page page = vs_storage_read_page(st, blkno);
320
321 312 const PrismCentroidPageOpaque *opaque = PRISM_CENTROID_OPAQUE(page);
322 312 PrismCentroidFormat fmt =
323 312 (PrismCentroidFormat)(opaque->flags & PRISM_CENTROID_FMT_MASK);
324 /* FASTSCAN doesn't have per-entry flags, so determine leaf
325 * status from tree depth: bottom level holds posting heads. */
326 312 bool is_leaf_page = (opaque->level == nlevels - 1);
327
328 /* Emit one row per entry. FASTSCAN pages have a different
329 * layout (group section instead of per-entry meta + data),
330 * so child_blkno lives in the group array and per-entry
331 * flags don't exist — the leaf bit is page-level. */
332 312 uint16_t nentries = opaque->entry_count;
333
334 312 check_centroid_count(blkno, nentries, dim, fmt);
335
336
2/2
✓ Branch 0 taken 205 times.
✓ Branch 1 taken 107 times.
312 if (fmt == PRISM_CENTROID_FMT_FASTSCAN)
337 {
338 char *content = (char *)PageGetContents(page);
339
340
2/2
✓ Branch 0 taken 1476 times.
✓ Branch 1 taken 205 times.
1681 for (uint16_t i = 0; i < nentries; i++)
341 {
342 1476 uint32_t g = i / VS_FASTSCAN_GROUP;
343 1476 uint32_t slot = i % VS_FASTSCAN_GROUP;
344 1476 BlockNumber *child =
345 1476 prism_centroid_fastscan_group_child(content, g, dim);
346
347 1476 Datum values[7];
348 1476 bool nulls[7] = {0};
349
350 1476 values[0] = Int32GetDatum((int32)blkno);
351 1476 values[1] = Int16GetDatum((int16)i);
352 1476 values[2] = Int16GetDatum((int16)opaque->level);
353
1/2
✓ Branch 1 taken 1476 times.
✗ Branch 2 not taken.
1476 values[3] = CStringGetTextDatum(centroid_format_names[fmt]);
354
355
1/2
✓ Branch 0 taken 1476 times.
✗ Branch 1 not taken.
1476 if (BlockNumberIsValid(child[slot]))
356 1476 values[4] = Int32GetDatum((int32)child[slot]);
357 else
358 ✗ nulls[4] = true;
359
360 /* child_count is not stored per-entry in FASTSCAN — the
361 * page-level leaf flag tells us whether children are
362 * posting heads (child_count = 0) or another centroid
363 * page. Leave as 0 / NULL. */
364 1476 nulls[5] = true;
365
2/2
✓ Branch 0 taken 193 times.
✓ Branch 1 taken 1283 times.
1476 values[6] = BoolGetDatum(is_leaf_page);
366
367 1476 tuplestore_putvalues(
368 rsinfo->setResult, rsinfo->setDesc, values, nulls);
369
370 /* Enqueue children if this isn't a leaf page */
371
3/4
✓ Branch 0 taken 193 times.
✓ Branch 1 taken 1283 times.
✓ Branch 2 taken 193 times.
✗ Branch 3 not taken.
1476 if (!is_leaf_page && BlockNumberIsValid(child[slot]))
372 {
373
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 192 times.
193 if (worklist_len >= worklist_cap)
374 {
375 1 worklist_cap *= 2;
376 1 worklist = repalloc(
377 1 worklist, worklist_cap * sizeof(BlockNumber));
378 }
379 193 worklist[worklist_len++] = child[slot];
380 }
381 }
382 }
383 else
384 {
385
2/2
✓ Branch 0 taken 1345 times.
✓ Branch 1 taken 107 times.
1452 for (uint16_t i = 0; i < nentries; i++)
386 {
387 1345 const PrismCentroidEntryMeta *entry =
388 1345 prism_centroid_meta(page, i);
389 1345 bool is_leaf = (entry->flags & PRISM_CENTROID_FLAG_LEAF) != 0;
390
391 1345 Datum values[7];
392 1345 bool nulls[7] = {0};
393
394 1345 values[0] = Int32GetDatum((int32)blkno);
395 1345 values[1] = Int16GetDatum((int16)i);
396 1345 values[2] = Int16GetDatum((int16)opaque->level);
397
1/2
✓ Branch 1 taken 1345 times.
✗ Branch 2 not taken.
1345 values[3] = CStringGetTextDatum(centroid_format_names[fmt]);
398
399 /* Leaf entries carry their posting-list head block in
400 * child_blkno (formula-derived: first_posting + leaf), so
401 * expose it -- structural tests join it against the posting
402 * heads. */
403
1/2
✓ Branch 0 taken 1345 times.
✗ Branch 1 not taken.
1345 if (BlockNumberIsValid(entry->child_blkno))
404 1345 values[4] = Int32GetDatum((int32)entry->child_blkno);
405 else
406 ✗ nulls[4] = true;
407
408
2/2
✓ Branch 0 taken 61 times.
✓ Branch 1 taken 1284 times.
1345 values[5] = Int16GetDatum((int16)entry->child_count);
409
2/2
✓ Branch 0 taken 61 times.
✓ Branch 1 taken 1284 times.
1345 values[6] = BoolGetDatum(is_leaf);
410
411 1345 tuplestore_putvalues(
412 rsinfo->setResult, rsinfo->setDesc, values, nulls);
413
414
3/4
✓ Branch 0 taken 61 times.
✓ Branch 1 taken 1284 times.
✓ Branch 2 taken 61 times.
✗ Branch 3 not taken.
1345 if (!is_leaf && BlockNumberIsValid(entry->child_blkno))
415 {
416
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 61 times.
61 if (worklist_len >= worklist_cap)
417 {
418 ✗ worklist_cap *= 2;
419 ✗ worklist = repalloc(
420 ✗ worklist, worklist_cap * sizeof(BlockNumber));
421 }
422 61 worklist[worklist_len++] = entry->child_blkno;
423 }
424 }
425 }
426
427 /* Enqueue sibling (next_blkno chain) */
428
2/2
✓ Branch 0 taken 16 times.
✓ Branch 1 taken 296 times.
312 if (BlockNumberIsValid(opaque->next_blkno))
429 {
430
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 16 times.
16 if (worklist_len >= worklist_cap)
431 {
432 ✗ worklist_cap *= 2;
433 ✗ worklist =
434 ✗ repalloc(worklist, worklist_cap * sizeof(BlockNumber));
435 }
436 16 worklist[worklist_len++] = opaque->next_blkno;
437 }
438
439 312 vs_storage_release_page(st, blkno);
440 }
441
442 42 pfree(worklist);
443 42 index_close(index, AccessShareLock);
444
445 42 PG_RETURN_NULL();
446 }
447
448 /*
449 * One prism_posting_pages() row per page of a chain.
450 *
451 * Everything the rows need beyond the page itself -- the tuplestore to emit
452 * into, the dimension, the running position in the chain -- rides in the
453 * walk's caller state, so the walk itself carries nothing about what it is
454 * being walked for.
455 */
456 typedef struct PostingRowCtx
457 {
458 ReturnSetInfo *rsinfo;
459 Dimension dim;
460 int chain_pos;
461 } PostingRowCtx;
462
463 static bool
464 4303 emit_posting_row(PrismPostingChainPos *pos, void *state)
465 {
466 4303 PostingRowCtx *ctx = state;
467 4303 Dimension dim = ctx->dim;
468 4303 const PrismPostingPageOpaque *op = prism_posting_opaque(pos->page);
469
2/2
✓ Branch 0 taken 1283 times.
✓ Branch 1 taken 3020 times.
4303 bool is_first = prism_posting_is_head_start(op->flags);
470 4303 bool tombstoned = (op->flags & PRISM_POSTING_PAGE_TOMBSTONED) != 0;
471 4303 bool is_fastscan = (op->flags & PRISM_POSTING_PAGE_FASTSCAN) != 0;
472 4303 bool is_ref = prism_posting_is_reference_only_page(op->flags, dim);
473
474 4303 Datum values[10];
475 4303 bool nulls[10] = {0};
476
477
2/2
✓ Branch 0 taken 1283 times.
✓ Branch 1 taken 3020 times.
4303 values[0] = Int32GetDatum((int32)pos->blkno);
478 4303 values[1] = Int32GetDatum((int32)op->cluster_id);
479
2/2
✓ Branch 0 taken 1283 times.
✓ Branch 1 taken 3020 times.
4303 values[2] = BoolGetDatum(is_first);
480
2/2
✓ Branch 0 taken 4204 times.
✓ Branch 1 taken 99 times.
4303 values[3] = BoolGetDatum(tombstoned);
481 4303 values[4] = Int32GetDatum((int32)op->entry_count);
482
483 {
484 /* AoS entries carry a per-entry DELETED flag; count them directly.
485 * FASTSCAN entries carry a per-group tombstone_mask instead, one bit
486 * per lane; popcount every group's mask and sum. Either way this is
487 * the exact dead count, not an estimate. */
488 4303 char *content = prism_posting_page_content(pos->page, dim);
489 4303 int32 dead = 0;
490
491 4303 prism_posting_check_count(pos->blkno, pos->page, dim);
492
493
2/2
✓ Branch 0 taken 2421 times.
✓ Branch 1 taken 1882 times.
4303 if (!is_fastscan)
494 {
495
2/2
✓ Branch 0 taken 84701 times.
✓ Branch 1 taken 2421 times.
87122 for (uint32_t i = 0; i < op->entry_count; i++)
496 {
497 84701 const PrismPostingEntryHeader *h =
498
2/2
✓ Branch 0 taken 2200 times.
✓ Branch 1 taken 82501 times.
84701 prism_posting_entry_at(content, i, dim);
499
500
2/2
✓ Branch 0 taken 2200 times.
✓ Branch 1 taken 82501 times.
84701 if (h->meta.flags & PRISM_POSTING_FLAG_DELETED)
501 2200 dead++;
502 }
503 }
504 else
505 {
506 1882 uint32_t n = op->entry_count;
507 1882 uint32_t ngroups = (n + VS_FASTSCAN_GROUP - 1) / VS_FASTSCAN_GROUP;
508
509
2/2
✓ Branch 0 taken 2746 times.
✓ Branch 1 taken 1882 times.
4628 for (uint32_t g = 0; g < ngroups; g++)
510 {
511 2746 uint32_t mask =
512 2746 *prism_fastscan_group_tombstone_mask(content, g);
513 /* GCC/Clang builtin, not pg_popcount32: this file already
514 * relies on compiler builtins elsewhere, and a per-page,
515 * per-call count is far from hot enough to need a
516 * runtime-dispatched popcount. */
517 2746 dead += __builtin_popcount(mask);
518 }
519 }
520
2/2
✓ Branch 0 taken 1283 times.
✓ Branch 1 taken 3020 times.
4303 values[5] = Int32GetDatum(dead);
521 }
522
523 /* Capacity from the layout: a fastscan page keeps its code length where
524 * an AoS page keeps its capacity. */
525 4303 values[6] = Int32GetDatum((int32)prism_posting_page_cap(op, dim));
526
527
2/2
✓ Branch 0 taken 1283 times.
✓ Branch 1 taken 3020 times.
4303 if (BlockNumberIsValid(pos->next))
528 1283 values[7] = Int32GetDatum((int32)pos->next);
529 else
530 3020 nulls[7] = true;
531
532
2/2
✓ Branch 0 taken 4005 times.
✓ Branch 1 taken 298 times.
4303 values[8] = Int32GetDatum(ctx->chain_pos++);
533
4/4
✓ Branch 0 taken 4005 times.
✓ Branch 1 taken 298 times.
✓ Branch 2 taken 2123 times.
✓ Branch 3 taken 1882 times.
6426 values[9] = CStringGetTextDatum(
534 is_ref ? "reference" : (is_fastscan ? "fastscan" : "aos"));
535
536 4303 tuplestore_putvalues(
537 4303 ctx->rsinfo->setResult, ctx->rsinfo->setDesc, values, nulls);
538 4303 return true;
539 }
540
541 /* ----------------------------------------------------------------
542 * prism_posting_pages(regclass)
543 *
544 * Returns one row per posting page: blkno, cluster_id, is_first,
545 * tombstoned, entry_count, dead_count, max_entries, next_blkno,
546 * chain_pos, format. Tombstoned (all-dead, but still linked) pages stay
547 * in the output so bloat is visible; filter with WHERE NOT tombstoned
548 * for live pages. dead_count is the per-entry DELETED tally for AoS pages
549 * and the summed tombstone_mask popcount across groups for fastscan
550 * pages -- exact either way, never NULL.
551 *
552 * Walks all posting chains by finding leaf centroids (which store
553 * posting_head block numbers) and following next_blkno links.
554 * ---------------------------------------------------------------- */
555 Datum
556 130 vs_posting_pages(PG_FUNCTION_ARGS)
557 {
558 130 Oid indexoid = PG_GETARG_OID(0);
559 130 ReturnSetInfo *rsinfo = (ReturnSetInfo *)fcinfo->resultinfo;
560
561 130 InitMaterializedSRF(fcinfo, 0);
562
563 130 Relation index = index_open(indexoid, AccessShareLock);
564
565 130 prism_check_index(index);
566 129 require_index_select(index, AccessShareLock);
567
568 128 VsPgStorage store;
569 128 VsStorage *st = &store.base;
570
571 128 vs_pg_storage_init_inspect(&store, index);
572
573 128 Page meta_page = vs_storage_read_page(st, 0);
574
575 128 const PrismMetaPage *meta = (const PrismMetaPage *)PageGetSpecialPointer(
576 meta_page);
577
578
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 128 times.
128 if (meta->magic != PRISM_META_MAGIC)
579 {
580 ✗ vs_storage_release_page(st, 0);
581 ✗ index_close(index, AccessShareLock);
582 ✗ ereport(ERROR,
583 (errcode(ERRCODE_WRONG_OBJECT_TYPE),
584 errmsg("\"%s\" is not a prism index",
585 RelationGetRelationName(index))));
586 }
587
588 128 BlockNumber first_centroid = meta->first_centroid;
589 128 Dimension dim = meta->dim;
590 128 uint8_t nlevels = meta->nlevels;
591 128 vs_storage_release_page(st, 0);
592
593
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 128 times.
128 if (!BlockNumberIsValid(first_centroid))
594 {
595 ✗ index_close(index, AccessShareLock);
596 ✗ PG_RETURN_NULL();
597 }
598
599 128 LeafEntry *leaves;
600 128 int nleaves =
601 128 collect_leaf_entries(index, first_centroid, nlevels, dim, &leaves);
602
603 /* Walk each posting chain */
604
2/2
✓ Branch 1 taken 3020 times.
✓ Branch 2 taken 128 times.
3148 for (int c = 0; c < nleaves; c++)
605 {
606 3020 PostingRowCtx ctx = {.rsinfo = rsinfo, .dim = dim};
607
608 3020 prism_posting_chain_walk(
609 3020 st, leaves[c].posting_head, emit_posting_row, &ctx);
610 }
611
612 128 pfree(leaves);
613 128 index_close(index, AccessShareLock);
614
615 128 PG_RETURN_NULL();
616 }
617
618 /* ----------------------------------------------------------------
619 * prism_tids_clusters(regclass, tid[])
620 *
621 * Diagnostic: for each input heap TID, return which cluster(s) it is
622 * stored in (primary + any SOAR/boundary replica). One pass over all
623 * leaf posting lists; emits (tid, cluster_id) for matched TIDs only.
624 * Lets a caller compare "where the true nearest neighbors live" against
625 * "which clusters a query scans". Owner-only: a SELECT grant must not be
626 * enough to confirm which TIDs the index holds.
627 * ---------------------------------------------------------------- */
628 static int
629 52373 cmp_u64(const void *a, const void *b)
630 {
631 52373 uint64 x = *(const uint64 *)a, y = *(const uint64 *)b;
632
2/2
✓ Branch 0 taken 43214 times.
✓ Branch 1 taken 5163 times.
48377 return (x > y) - (x < y);
633 }
634
635 /* Emit (tid, cluster_id) if tid is one of the sorted target keys. */
636 static void
637 7163 emit_tid_cluster(
638 ReturnSetInfo *rsinfo,
639 const uint64 *keys,
640 int nk,
641 ItemPointer tid,
642 uint32_t cluster_id)
643 {
644 7163 uint64 enc = prism_posting_encode_tid(tid);
645
2/2
✓ Branch 0 taken 2000 times.
✓ Branch 1 taken 5163 times.
14326 if (bsearch(&enc, keys, nk, sizeof(uint64), cmp_u64) == NULL)
646 2000 return;
647
648 5163 Datum values[2];
649 5163 bool nulls[2] = {0};
650 5163 ItemPointer out = palloc(sizeof(ItemPointerData));
651 5163 *out = *tid;
652 5163 values[0] = PointerGetDatum(out);
653 5163 values[1] = Int32GetDatum((int32)cluster_id);
654 5163 tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc, values, nulls);
655 }
656
657 Datum
658 9 vs_tids_clusters(PG_FUNCTION_ARGS)
659 {
660 9 Oid indexoid = PG_GETARG_OID(0);
661 9 ArrayType *arr = PG_GETARG_ARRAYTYPE_P(1);
662 9 ReturnSetInfo *rsinfo = (ReturnSetInfo *)fcinfo->resultinfo;
663
664 9 InitMaterializedSRF(fcinfo, 0);
665
666 /* Deconstruct tid[] into a sorted array of encoded uint64 keys. */
667 9 Datum *elems;
668 9 bool *elnulls;
669 9 int nelems;
670 9 deconstruct_array(
671 arr,
672 TIDOID,
673 sizeof(ItemPointerData),
674 false,
675 TYPALIGN_SHORT,
676 &elems,
677 &elnulls,
678 &nelems);
679 9 uint64 *keys = palloc(Max(nelems, 1) * sizeof(uint64));
680 9 int nk = 0;
681
2/2
✓ Branch 1 taken 4005 times.
✓ Branch 2 taken 9 times.
4014 for (int i = 0; i < nelems; i++)
682 {
683
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 4005 times.
4005 if (elnulls[i])
684 ✗ continue;
685 4005 keys[nk++] = prism_posting_encode_tid(
686 4005 (ItemPointer)DatumGetPointer(elems[i]));
687 }
688 9 qsort(keys, nk, sizeof(uint64), cmp_u64);
689
690 9 Relation index = index_open(indexoid, AccessShareLock);
691
692 8 prism_check_index(index);
693 7 require_index_owner(index, AccessShareLock);
694
695 5 VsPgStorage store;
696 5 VsStorage *st = &store.base;
697
698 5 vs_pg_storage_init_inspect(&store, index);
699
700 /*
701 * Through a local: PageGetSpecialPointer is a macro that evaluates its
702 * argument three times, and reading a page is not free of side effects
703 * -- inlining the read pins the buffer once per evaluation.
704 */
705 5 Page meta_page = vs_storage_read_page(st, 0);
706 5 const PrismMetaPage *meta = (const PrismMetaPage *)PageGetSpecialPointer(
707 meta_page);
708 5 Dimension dim = (Dimension)meta->dim;
709 5 vs_storage_release_page(st, 0);
710
711 /* Scan every block and pick out posting pages directly (identified by
712 * page_id), rather than walking the centroid tree to find posting
713 * heads — that avoids any dependency on the leaf-enumeration path and
714 * each posting page already carries its cluster_id. */
715 5 BlockNumber nblocks = RelationGetNumberOfBlocks(index);
716
2/2
✓ Branch 1 taken 222 times.
✓ Branch 2 taken 5 times.
227 for (BlockNumber blkno = 1; nk > 0 && blkno < nblocks; blkno++)
717 {
718 222 Page page = vs_storage_read_page(st, blkno);
719
720
2/2
✓ Branch 1 taken 217 times.
✓ Branch 2 taken 5 times.
222 if (prism_page_is_posting(page))
721 {
722 217 const PrismPostingPageOpaque *op = prism_posting_opaque(page);
723 217 char *content = prism_posting_page_content(page, dim);
724 217 uint32_t count = op->entry_count;
725
726 217 prism_posting_check_count(blkno, page, dim);
727
728
2/2
✓ Branch 0 taken 93 times.
✓ Branch 1 taken 124 times.
217 if (op->flags & PRISM_POSTING_PAGE_FASTSCAN)
729 {
730 /* SoA: TIDs packed per group of VS_FASTSCAN_GROUP. */
731 93 uint32_t ngroups = (count + VS_FASTSCAN_GROUP - 1) /
732 VS_FASTSCAN_GROUP;
733
2/2
✓ Branch 0 taken 151 times.
✓ Branch 1 taken 93 times.
244 for (uint32_t g = 0; g < ngroups; g++)
734 {
735 151 ItemPointerData *tids =
736 151 prism_fastscan_group_tids(content, g);
737 151 uint32_t gc = count - g * VS_FASTSCAN_GROUP;
738 151 if (gc > VS_FASTSCAN_GROUP)
739 gc = VS_FASTSCAN_GROUP;
740
2/2
✓ Branch 0 taken 3163 times.
✓ Branch 1 taken 151 times.
3314 for (uint32_t v = 0; v < gc; v++)
741 3163 emit_tid_cluster(
742 3163 rsinfo, keys, nk, &tids[v], op->cluster_id);
743 }
744 }
745 else
746 {
747 /* AoS: the TID is at the head of each entry. */
748
2/2
✓ Branch 0 taken 4000 times.
✓ Branch 1 taken 124 times.
4124 for (uint32_t i = 0; i < count; i++)
749 {
750 4000 PrismPostingEntryHeader *e =
751 4000 prism_posting_entry_at(content, i, dim);
752 4000 emit_tid_cluster(
753 4000 rsinfo, keys, nk, &e->meta.tid, op->cluster_id);
754 }
755 }
756 }
757 222 vs_storage_release_page(st, blkno);
758 }
759
760 5 index_close(index, AccessShareLock);
761 5 PG_RETURN_NULL();
762 }
763
764 /* ----------------------------------------------------------------
765 * prism_index_settings(regclass)
766 *
767 * Returns one (name, setting, source) row per effective index
768 * setting, with automatic values resolved to what the build (or the
769 * current session) actually uses. The source column tells where the
770 * value came from:
771 *
772 * 'option' -- reloption set explicitly at CREATE INDEX
773 * 'auto' -- resolved from an automatic default (nlist from the
774 * row count, formats from metric/dimension, nprobe
775 * from nlist)
776 * 'default' -- reloption default in effect
777 * 'column' -- from the indexed column definition
778 * 'opclass' -- from the operator class
779 * 'derived' -- computed from other settings
780 * 'session' -- a session GUC overriding the index setting
781 *
782 * Values the build persists (nlist, fan_out, nlevels, formats) come
783 * from the metadata page and are authoritative for the index as
784 * built. Options only consumed during the build but not persisted
785 * (soar_lambda, boundary_epsilon, kmeans_nredo) are read from the
786 * catalog, so they reflect the build only as long as they have not
787 * been changed with ALTER INDEX ... SET afterwards.
788 * ---------------------------------------------------------------- */
789
790 /* Metric name lookup (indexed by DistanceMetric); the names match
791 * the vector_<metric>_ops opclass names. */
792 static const char *metric_names[] = {
793 [DISTANCE_L2] = "l2",
794 [DISTANCE_INNER_PRODUCT] = "ip",
795 [DISTANCE_COSINE] = "cosine",
796 };
797
798 /* The reloptions explicitly set on a relation, as a list of DefElem.
799 * Unlike rd_options this excludes defaults, so it tells apart "set
800 * to the default value" from "defaulted". Caller must free with
801 * list_free_deep. */
802 static List *
803 47 explicit_reloptions(Oid relid)
804 {
805 47 HeapTuple tuple = SearchSysCache1(RELOID, ObjectIdGetDatum(relid));
806
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 47 times.
47 if (!HeapTupleIsValid(tuple))
807 ✗ elog(ERROR, "cache lookup failed for relation %u", relid);
808
809 47 bool isnull;
810 47 Datum datum =
811 47 SysCacheGetAttr(RELOID, tuple, Anum_pg_class_reloptions, &isnull);
812
2/2
✓ Branch 0 taken 43 times.
✓ Branch 1 taken 4 times.
47 List *options = isnull ? NIL : untransformRelOptions(datum);
813 47 ReleaseSysCache(tuple);
814 47 return options;
815 }
816
817 static bool
818 460 reloption_is_set(const List *options, const char *name)
819 {
820 460 ListCell *lc;
821
4/4
✓ Branch 0 taken 1058 times.
✓ Branch 1 taken 39 times.
✓ Branch 2 taken 713 times.
✓ Branch 3 taken 345 times.
1097 foreach (lc, options)
822 {
823 713 const DefElem *def = lfirst_node(DefElem, lc);
824
2/2
✓ Branch 0 taken 637 times.
✓ Branch 1 taken 76 times.
713 if (strcmp(def->defname, name) == 0)
825 460 return true;
826 }
827 return false;
828 }
829
830 static void
831 799 settings_row(
832 ReturnSetInfo *rsinfo,
833 const char *name,
834 const char *setting,
835 const char *source)
836 {
837 799 Datum values[3];
838 799 bool nulls[3] = {0};
839
840 799 values[0] = CStringGetTextDatum(name);
841 799 values[1] = CStringGetTextDatum(setting);
842 799 values[2] = CStringGetTextDatum(source);
843 799 tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc, values, nulls);
844 799 }
845
846 Datum
847 49 vs_index_settings(PG_FUNCTION_ARGS)
848 {
849 49 Oid indexoid = PG_GETARG_OID(0);
850 49 ReturnSetInfo *rsinfo = (ReturnSetInfo *)fcinfo->resultinfo;
851
852 49 InitMaterializedSRF(fcinfo, 0);
853
854 49 Relation index = index_open(indexoid, AccessShareLock);
855
856 49 prism_check_index(index);
857 48 require_index_select(index, AccessShareLock);
858
859 47 VsPgStorage store;
860 47 VsStorage *st = &store.base;
861
862 47 vs_pg_storage_init_inspect(&store, index);
863
864 /*
865 * Through a local: PageGetSpecialPointer is a macro that evaluates its
866 * argument three times, and reading a page is not free of side effects
867 * -- inlining the read pins the buffer once per evaluation.
868 */
869 47 Page meta_page = vs_storage_read_page(st, 0);
870 47 const PrismMetaPage *meta = (const PrismMetaPage *)PageGetSpecialPointer(
871 meta_page);
872
873
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 47 times.
47 if (meta->magic != PRISM_META_MAGIC)
874 {
875 ✗ vs_storage_release_page(st, 0);
876 ✗ index_close(index, AccessShareLock);
877 ✗ ereport(ERROR,
878 (errcode(ERRCODE_WRONG_OBJECT_TYPE),
879 errmsg("\"%s\" is not a prism index",
880 RelationGetRelationName(index))));
881 }
882
883 47 Dimension dim = meta->dim;
884 47 uint8_t nlevels = meta->nlevels;
885 47 PrismCentroidFormat centroid_format = (PrismCentroidFormat)
886 47 meta->centroid_format;
887 47 uint32_t nlist = meta->nlist;
888 47 DistanceMetric metric = (DistanceMetric)meta->metric;
889 47 uint8_t fan_out = meta->fan_out;
890 47 bool fastscan = (meta->flags & PRISM_META_FLAG_FASTSCAN) != 0;
891 47 uint32_t ncentroid_pages = meta->ncentroid_pages;
892 47 BlockNumber first_posting = meta->first_posting;
893 47 vs_storage_release_page(st, 0);
894
895 47 const PrismOptions *opts = (const PrismOptions *)index->rd_options;
896 47 List *set = explicit_reloptions(indexoid);
897
898 /* Index definition */
899 47 settings_row(rsinfo, "dim", psprintf("%d", dim), "column");
900 47 settings_row(rsinfo, "metric", metric_names[metric], "opclass");
901
902 /* Build-resolved shape, from the metadata page */
903
2/2
✓ Branch 0 taken 29 times.
✓ Branch 1 taken 18 times.
94 settings_row(
904 rsinfo,
905 "nlist",
906 47 psprintf("%u", nlist),
907 47 reloption_is_set(set, "nlist") ? "option" : "auto");
908
2/2
✓ Branch 0 taken 45 times.
✓ Branch 1 taken 2 times.
94 settings_row(
909 rsinfo,
910 "fan_out",
911 47 psprintf("%u", (uint32_t)fan_out),
912 47 reloption_is_set(set, "fan_out") ? "option" : "auto");
913 47 settings_row(
914 47 rsinfo, "nlevels", psprintf("%u", (uint32_t)nlevels), "derived");
915 /* The resting list size nlist was derived from, and the page target
916 * behind it -- resolved, so the effective default shows rather than the
917 * 0 that means "derive". */
918
1/2
✓ Branch 0 taken 47 times.
✗ Branch 1 not taken.
94 settings_row(
919 rsinfo,
920 "target_pages",
921
2/2
✓ Branch 0 taken 43 times.
✓ Branch 1 taken 4 times.
90 psprintf(
922 "%u",
923
1/2
✓ Branch 0 taken 43 times.
✗ Branch 1 not taken.
43 (opts != NULL && opts->target_pages > 0)
924 ? (uint32_t)opts->target_pages
925 : (uint32_t)PRISM_DEFAULT_TARGET_PAGES),
926 47 reloption_is_set(set, "target_pages") ? "option" : "default");
927 47 settings_row(
928 rsinfo,
929 "target_entries",
930
2/2
✓ Branch 0 taken 43 times.
✓ Branch 1 taken 4 times.
90 psprintf(
931 "%u",
932 prism_target_entries_per_dim(
933 dim,
934 43 (opts != NULL) ? (uint32_t)opts->target_pages
935 : 0)),
936 "derived");
937 47 settings_row(
938 rsinfo,
939 "centroid_pages",
940 47 psprintf("%u", ncentroid_pages),
941 "maintained");
942 47 settings_row(
943 47 rsinfo, "first_posting", psprintf("%u", first_posting), "derived");
944 /*
945 * The posting page count the scan cost estimate prices, from the same
946 * helper it calls and the same page count: get_relation_info fills
947 * IndexOptInfo.pages from RelationGetNumberOfBlocks too, so this and the
948 * planner's figure agree without waiting on ANALYZE.
949 */
950 47 settings_row(
951 rsinfo,
952 "posting_pages",
953
2/2
✓ Branch 0 taken 7 times.
✓ Branch 1 taken 40 times.
94 psprintf(
954 "%.0f",
955 prism_index_posting_pages(
956 47 (double)RelationGetNumberOfBlocks(index),
957 dim,
958 (double)ncentroid_pages)),
959 "derived");
960
2/2
✓ Branch 0 taken 38 times.
✓ Branch 1 taken 9 times.
94 settings_row(
961 rsinfo,
962 "centroid_format",
963 centroid_format_names[centroid_format],
964
2/2
✓ Branch 1 taken 32 times.
✓ Branch 2 taken 6 times.
85 (reloption_is_set(set, "centroid_compression") ||
965 38 reloption_is_set(set, "centroid_fastscan"))
966 ? "option"
967 : "auto");
968
4/4
✓ Branch 0 taken 42 times.
✓ Branch 1 taken 5 times.
✓ Branch 2 taken 4 times.
✓ Branch 3 taken 43 times.
93 settings_row(
969 rsinfo,
970 "fastscan",
971 fastscan ? "on" : "off",
972 47 reloption_is_set(set, "fastscan") ? "option" : "auto");
973
974 /* Build options not persisted in the index: current catalog
975 * values, with reloption defaults filled in */
976
2/2
✓ Branch 0 taken 44 times.
✓ Branch 1 taken 3 times.
94 settings_row(
977 rsinfo,
978 "soar_lambda",
979
2/2
✓ Branch 0 taken 43 times.
✓ Branch 1 taken 4 times.
47 psprintf(
980 "%g",
981 (opts != NULL) ? opts->soar_lambda
982 : PRISM_DEFAULT_SOAR_LAMBDA),
983 47 reloption_is_set(set, "soar_lambda") ? "option" : "default");
984
2/2
✓ Branch 0 taken 44 times.
✓ Branch 1 taken 3 times.
94 settings_row(
985 rsinfo,
986 "boundary_epsilon",
987
2/2
✓ Branch 0 taken 43 times.
✓ Branch 1 taken 4 times.
47 psprintf(
988 "%g",
989 (opts != NULL) ? opts->boundary_epsilon
990 : PRISM_DEFAULT_BOUNDARY_EPSILON),
991 47 reloption_is_set(set, "boundary_epsilon") ? "option" : "default");
992
2/2
✓ Branch 0 taken 45 times.
✓ Branch 1 taken 2 times.
94 settings_row(
993 rsinfo,
994 "kmeans_nredo",
995
2/2
✓ Branch 0 taken 43 times.
✓ Branch 1 taken 4 times.
47 psprintf("%d", (opts != NULL) ? opts->kmeans_nredo : 1),
996 47 reloption_is_set(set, "kmeans_nredo") ? "option" : "default");
997
998 /* Query-time settings whose effective value depends on this
999 * index: the session GUC wins when set, otherwise the index
1000 * option or automatic resolution applies. */
1001
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 46 times.
47 if (prism_distance_mode != VS_DISTANCE_MODE_DEFAULT)
1002 1 settings_row(
1003 rsinfo,
1004 "distance_mode",
1005 vs_distance_mode_name((VsDistanceMode)prism_distance_mode),
1006 "session");
1007 else
1008
2/2
✓ Branch 0 taken 44 times.
✓ Branch 1 taken 2 times.
92 settings_row(
1009 rsinfo,
1010 "distance_mode",
1011 vs_distance_mode_name(PrismGetDistanceMode(index)),
1012 46 reloption_is_set(set, "distance_mode") ? "option" : "default");
1013 47 settings_row(
1014 rsinfo,
1015 "nprobe",
1016
2/2
✓ Branch 0 taken 39 times.
✓ Branch 1 taken 8 times.
86 psprintf(
1017 "%u",
1018 (prism_nprobe > 0) ? (uint32_t)prism_nprobe
1019 39 : prism_auto_nprobe(nlist)),
1020
2/2
✓ Branch 0 taken 39 times.
✓ Branch 1 taken 8 times.
47 (prism_nprobe > 0) ? "session" : "auto");
1021
1022 47 list_free_deep(set);
1023 47 index_close(index, AccessShareLock);
1024 47 PG_RETURN_NULL();
1025 }
1026