| 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 | |||
| 25 | /* | ||
| 26 | * "PRI" + a format-version byte. Bump the low byte on any incompatible | ||
| 27 | * metapage/layout change so an index built by an older format is rejected at | ||
| 28 | * open rather than silently misread. v2 added PrismMetaPage.first_posting, | ||
| 29 | * which shifted the struct layout; v3 removed the unused indexed-row count, | ||
| 30 | * which shifted it again; v4 grew the fastscan group section by one | ||
| 31 | * tombstone_mask word, which moves every group after the first on a page -- | ||
| 32 | * a posting page format change, not a metapage one, but this is the only | ||
| 33 | * version gate the index has. | ||
| 34 | */ | ||
| 35 | #define PRISM_META_MAGIC ((uint32_t)0x50524906) /* "PRI\x06" */ | ||
| 36 | |||
| 37 | /* Metadata flags */ | ||
| 38 | #define PRISM_META_FLAG_FASTSCAN 0x01 | ||
| 39 | |||
| 40 | typedef struct PrismMetaPage | ||
| 41 | { | ||
| 42 | uint32_t magic; /* PRISM_META_MAGIC */ | ||
| 43 | Dimension dim; /* vector dimension */ | ||
| 44 | uint8_t nlevels; /* centroid tree depth */ | ||
| 45 | uint8_t centroid_format; /* PrismCentroidFormat */ | ||
| 46 | BlockNumber first_centroid; /* root centroid page */ | ||
| 47 | BlockNumber first_posting; /* first posting page (one past the last | ||
| 48 | * centroid page); lets VACUUM skip the whole | ||
| 49 | * centroid region without scanning it */ | ||
| 50 | uint32_t nlist; /* number of leaf centroids */ | ||
| 51 | /* | ||
| 52 | * Centroid pages reachable from first_centroid. Maintained rather than | ||
| 53 | * derived: the region a build reserves is [PRISM_FIRST_CENTROID_BLKNO, | ||
| 54 | * first_posting), but a split with no room on a level-0 page extends the | ||
| 55 | * relation and chains the new page past the posting region, so a block | ||
| 56 | * range stops measuring it. prism_rebalance folds each split's additions | ||
| 57 | * back in here. | ||
| 58 | */ | ||
| 59 | uint32_t ncentroid_pages; | ||
| 60 | uint8_t metric; /* DistanceMetric */ | ||
| 61 | uint8_t fan_out; /* children per tree node */ | ||
| 62 | uint8_t flags; /* PRISM_META_FLAG_* */ | ||
| 63 | uint8_t reserved; | ||
| 64 | uint64_t rabitq_seed; /* seed for RaBitQ params */ | ||
| 65 | /* Global mean vector stored inline after struct */ | ||
| 66 | } PrismMetaPage; | ||
| 67 | |||
| 68 | /* Total special-area size including inline global mean */ | ||
| 69 | #define PRISM_META_SIZE(dim) \ | ||
| 70 | (MAXALIGN( \ | ||
| 71 | offsetof(PrismMetaPage, rabitq_seed) + sizeof(uint64_t) + \ | ||
| 72 | (size_t)(dim) * sizeof(float))) | ||
| 73 | |||
| 74 | /* Access the inline global mean vector after the struct */ | ||
| 75 | static inline float * | ||
| 76 | 194 | prism_meta_global_mean(PrismMetaPage *meta) | |
| 77 | { | ||
| 78 | 194 | return (float *)((char *)meta + offsetof(PrismMetaPage, rabitq_seed) + | |
| 79 | sizeof(uint64_t)); | ||
| 80 | } | ||
| 81 | |||
| 82 | static inline const float * | ||
| 83 | 244 | prism_meta_global_mean_const(const PrismMetaPage *meta) | |
| 84 | { | ||
| 85 | 244 | return (const float *)((const char *)meta + | |
| 86 | offsetof(PrismMetaPage, rabitq_seed) + | ||
| 87 | sizeof(uint64_t)); | ||
| 88 | } | ||
| 89 | |||
| 90 | #endif /* PRISM_META_H */ | ||
| 91 |