| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | /* | ||
| 2 | * Copyright (c) 2026 Tiger Data, Inc. | ||
| 3 | * Licensed under the PostgreSQL License. See LICENSE for details. | ||
| 4 | * | ||
| 5 | * meta.h - Metadata page layout for prism index | ||
| 6 | * | ||
| 7 | * Block 0 of every prism index stores a PrismMetaPage in the | ||
| 8 | * page special area. It records index parameters (dimension, tree | ||
| 9 | * depth, centroid format, distance metric, RaBitQ seed) and the | ||
| 10 | * global mean vector used for RaBitQ query preparation. | ||
| 11 | */ | ||
| 12 | |||
| 13 | #ifndef PRISM_META_H | ||
| 14 | #define PRISM_META_H | ||
| 15 | |||
| 16 | #include <postgres.h> | ||
| 17 | |||
| 18 | #pragma GCC diagnostic push | ||
| 19 | #pragma GCC diagnostic ignored "-Wunused-parameter" | ||
| 20 | #include <storage/bufpage.h> | ||
| 21 | #pragma GCC diagnostic pop | ||
| 22 | |||
| 23 | #include "core/types.h" | ||
| 24 | #include "index/index_base.h" | ||
| 25 | |||
| 26 | /* | ||
| 27 | * "PRI" + a format-version byte. Bump the low byte on any incompatible | ||
| 28 | * metapage/layout change so an index built by an older format is rejected at | ||
| 29 | * open rather than silently misread. It is the only version gate the index | ||
| 30 | * has, so it also covers changes outside the metapage. 06 is the initial | ||
| 31 | * format. 07 keeps references too wide for a page on reference pages, and | ||
| 32 | * lets fastscan groups continue across posting pages. | ||
| 33 | */ | ||
| 34 | #define PRISM_META_MAGIC ((uint32_t)0x50524907) /* "PRI\x07" */ | ||
| 35 | |||
| 36 | /* Metadata flags */ | ||
| 37 | #define PRISM_META_FLAG_FASTSCAN 0x01 | ||
| 38 | |||
| 39 | typedef struct PrismMetaPage | ||
| 40 | { | ||
| 41 | uint32_t magic; /* PRISM_META_MAGIC */ | ||
| 42 | Dimension dim; /* vector dimension */ | ||
| 43 | uint8_t nlevels; /* centroid tree depth */ | ||
| 44 | uint8_t centroid_format; /* PrismCentroidFormat */ | ||
| 45 | BlockNumber first_centroid; /* root centroid page */ | ||
| 46 | BlockNumber first_posting; /* first posting page (one past the last | ||
| 47 | * centroid page); lets VACUUM skip the whole | ||
| 48 | * centroid region without scanning it */ | ||
| 49 | uint32_t nlist; /* number of leaf centroids */ | ||
| 50 | /* | ||
| 51 | * Centroid pages reachable from first_centroid. Maintained rather than | ||
| 52 | * derived: the region a build reserves is [prism_first_centroid_blkno, | ||
| 53 | * first_posting), but a split with no room on a level-0 page extends the | ||
| 54 | * relation and chains the new page past the posting region, so a block | ||
| 55 | * range stops measuring it. prism_rebalance folds each split's additions | ||
| 56 | * back in here. | ||
| 57 | */ | ||
| 58 | uint32_t ncentroid_pages; | ||
| 59 | uint8_t metric; /* DistanceMetric */ | ||
| 60 | uint8_t fan_out; /* children per tree node */ | ||
| 61 | uint8_t flags; /* PRISM_META_FLAG_* */ | ||
| 62 | uint8_t reserved; | ||
| 63 | uint64_t rabitq_seed; /* seed for RaBitQ params */ | ||
| 64 | /* Global mean vector stored inline after struct, up | ||
| 65 | * to PRISM_GLOBAL_MEAN_MAX_INLINE_DIM; past it the | ||
| 66 | * mean lives in the reference pages at | ||
| 67 | * PRISM_GLOBAL_MEAN_BLKNO (see index_base.h). */ | ||
| 68 | } PrismMetaPage; | ||
| 69 | |||
| 70 | #define PRISM_META_FIXED_SIZE \ | ||
| 71 | (offsetof(PrismMetaPage, rabitq_seed) + sizeof(uint64_t)) | ||
| 72 | |||
| 73 | static inline bool | ||
| 74 | 1154 | prism_meta_mean_inline(Dimension dim) | |
| 75 | { | ||
| 76 |
4/4✓ Branch 0 taken 494 times.
✓ Branch 1 taken 83 times.
✓ Branch 3 taken 272 times.
✓ Branch 4 taken 305 times.
|
879 | return prism_global_mean_pages(dim) == 0; |
| 77 | } | ||
| 78 | |||
| 79 | /* Special-area size: the struct plus the inline global mean where it fits */ | ||
| 80 | #define PRISM_META_SIZE(dim) \ | ||
| 81 | (MAXALIGN( \ | ||
| 82 | PRISM_META_FIXED_SIZE + (prism_meta_mean_inline(dim) \ | ||
| 83 | ? (size_t)(dim) * sizeof(float) \ | ||
| 84 | : 0))) | ||
| 85 | |||
| 86 | /* | ||
| 87 | * The shared inline threshold is tight at 8-byte alignment. A smaller | ||
| 88 | * alignment can leave slack in the metapage. | ||
| 89 | */ | ||
| 90 | StaticAssertDecl( | ||
| 91 | PRISM_CEILING_ALIGN(PRISM_META_FIXED_SIZE) + | ||
| 92 | (size_t)PRISM_GLOBAL_MEAN_MAX_INLINE_DIM * | ||
| 93 | sizeof(float) <= | ||
| 94 | BLCKSZ - PRISM_CEILING_ALIGN(SizeOfPageHeaderData), | ||
| 95 | "the inline mean must fit the metapage at the threshold"); | ||
| 96 | StaticAssertDecl( | ||
| 97 | PRISM_CEILING_ALIGN(PRISM_META_FIXED_SIZE) + | ||
| 98 | (size_t)(PRISM_GLOBAL_MEAN_MAX_INLINE_DIM + 1) * | ||
| 99 | sizeof(float) > | ||
| 100 | BLCKSZ - PRISM_CEILING_ALIGN(SizeOfPageHeaderData), | ||
| 101 | "the inline-mean threshold is tight"); | ||
| 102 | |||
| 103 | /* Access the inline global mean vector after the struct (inline layout) */ | ||
| 104 | static inline float * | ||
| 105 | 219 | prism_meta_global_mean(PrismMetaPage *meta) | |
| 106 | { | ||
| 107 | 219 | return (float *)((char *)meta + PRISM_META_FIXED_SIZE); | |
| 108 | } | ||
| 109 | |||
| 110 | static inline const float * | ||
| 111 | 275 | prism_meta_global_mean_const(const PrismMetaPage *meta) | |
| 112 | { | ||
| 113 | 275 | return (const float *)((const char *)meta + PRISM_META_FIXED_SIZE); | |
| 114 | } | ||
| 115 | |||
| 116 | #endif /* PRISM_META_H */ | ||
| 117 |