Per-table provenance metadata persisted alongside the circuit store. More...

#include <stdint.h>
#include "postgres.h"
#include "access/attnum.h"

Include dependency graph for MMappedTableInfo.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	ProvenanceTableInfo
	Per-relation metadata for the safe-query optimisation. More...

Macros
#define	PROVSQL_TABLE_INFO_MAX_BLOCK_KEY 16
	Cap on the number of block-key columns recorded per relation.
#define	PROVSQL_TABLE_INFO_MAX_ANCESTORS 64
	Cap on the number of base ancestors recorded per relation.

Enumerations
enum	provsql_table_kind { PROVSQL_TABLE_TID = 0 , PROVSQL_TABLE_BID = 1 , PROVSQL_TABLE_OPAQUE = 2 }
	How the provenance leaves of a tracked relation are correlated. More...

Detailed Description

Per-table provenance metadata persisted alongside the circuit store.

ProvenanceTableInfo records, one per relation tracked by ProvSQL, are stored in a fifth mmap-backed file (provsql_table_info.mmap) inside each database's $PGDATA/base/<db_oid>/ directory. They feed the safe-query optimisation: the planner-time hierarchy detector needs to know whether each base relation is TID (independent leaves; default after add_provenance) or BID (block-correlated leaves; produced by repair_key) before it can decide whether a query is safe to rewrite into read-once form.

The file uses the same 16-byte header convention as every other ProvSQL mmap file (magic / version / elem_size / _reserved); records are fixed-stride so we can back it with MMappedVector directly, without introducing a second variable-length region.

Warning: ON-DISK ABI: the layout of ProvenanceTableInfo is serialised verbatim into provsql_table_info.mmap. Adding, removing, or resizing a field requires bumping the mmap file format version and providing a migration path, exactly as for GateInformation in MMappedCircuit.h.

Definition in file MMappedTableInfo.h.

Macro Definition Documentation

◆ PROVSQL_TABLE_INFO_MAX_ANCESTORS

#define PROVSQL_TABLE_INFO_MAX_ANCESTORS 64

Cap on the number of base ancestors recorded per relation.

The base-ancestor set lists the pg_class OIDs of the original add_provenance / repair_key relations a derived (CTAS / SELECT INTO / CREATE MATERIALIZED VIEW) relation's provenance ultimately reads from. Base tables carry {self}; the safe-query rewriter consults the set to enforce that joined FROM entries have disjoint base ancestors before firing the read-once factoring. Sixty-four covers practical CTAS workloads (typical derivations span 1-10 sources); set-ancestors raises a clear error if a wider set is requested, in which case the relation should be left untracked (the safe-query rewriter will then refuse it on the missing-ancestry conservative path).

Definition at line 64 of file MMappedTableInfo.h.

◆ PROVSQL_TABLE_INFO_MAX_BLOCK_KEY

#define PROVSQL_TABLE_INFO_MAX_BLOCK_KEY 16

Cap on the number of block-key columns recorded per relation.

BID tables (produced by repair_key) can have multi-column keys. We store the column numbers inline in a fixed-size array so each record is fixed-stride and MMappedVector can back the file directly. Sixteen is generous in practice — provenance-tracked tables rarely use composite keys wider than a handful of columns. repair_key raises a clear error if a wider key is requested.

Definition at line 47 of file MMappedTableInfo.h.

Enumeration Type Documentation

◆ provsql_table_kind

enum provsql_table_kind

How the provenance leaves of a tracked relation are correlated.

Three cases need distinguishing for the safe-query rewriter:

PROVSQL_TABLE_TID – independent input leaves; the post-add_provenance default. Each row's provenance token is a fresh gate_input with its own probability.
PROVSQL_TABLE_BID – block-correlated leaves produced by repair_key. Rows sharing the same value of block_key are mutually exclusive (they originate from a single block gate_input via gate_mulinput children). An empty block_key means the whole table is one block.
PROVSQL_TABLE_OPAQUE – correlations are unknown. Used for relations whose provenance is derived from a tracked source via CREATE TABLE AS SELECT, INSERT INTO SELECT, or UPDATE under provsql.update_provenance. The safe-query rewriter must bail on these.

Stored as uint8_t in ProvenanceTableInfo so the on-disk size matches the previous bool field exactly.

Warning: ON-DISK ABI: these integer values are persisted in provsql_table_info.mmap. Do not reorder or renumber existing members; new kinds must be appended.

Enumerator
PROVSQL_TABLE_TID
PROVSQL_TABLE_BID
PROVSQL_TABLE_OPAQUE

Definition at line 92 of file MMappedTableInfo.h.

Classes