Core types, constants, and utilities shared across ProvSQL. More...

#include "pg_config.h"
#include "c.h"
#include "postgres.h"
#include "utils/uuid.h"
#include "postgres_ext.h"
#include "nodes/pg_list.h"
#include "MMappedTableInfo.h"
#include "provsql_error.h"

Include dependency graph for provsql_utils.h:

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

Go to the source code of this file.

Classes
struct	constants_t
	Structure to store the value of various constants. More...
struct	database_constants_t
	Structure to store the value of various constants for a specific database. More...
struct	ProvenanceRelationKey
	One PRIMARY-KEY or NOT-NULL-UNIQUE key on a relation. More...
struct	ProvenanceRelationKeys
	Per-relation set of PRIMARY-KEY and NOT-NULL-UNIQUE keys. More...

Macros
#define	PROVSQL_AGG_SCALAR_FLAG 0x80000000u
	Scalar-aggregation flag, stored in the upper bit of a `gate_agg's` `info2` (whose low 31 bits hold the aggregate result-type OID).
#define	PROVSQL_AGG_TYPE_MASK 0x7FFFFFFFu
#define	PROVSQL_COLUMN_NAME "provsql"
	Canonical name of the per-row provenance column installed by `add_provenance` / `repair_key`.
#define	PROVSQL_KEY_CACHE_MAX_KEYS 4
	Upper bounds for the relation-key cache.
#define	PROVSQL_KEY_CACHE_MAX_KEY_COLS 8
#define	PROVSQL_GATE_ZERO_UUID "19257535-6aaf-5275-b02b-899c48576553"
	UUID of the semiring zero gate: the result of the SQL function `gate_zero()`, created with the extension (test `agg_filter` checks the two agree).
#define	PROVSQL_GATE_ONE_UUID "d265daa9-f206-561d-845c-2a85fa0fa72c"
	UUID of the semiring one gate, the result of `gate_one()`.
#define	PROVSQL_GATE_NULL_UUID "417134e7-a404-57a7-86fd-2577ebe0f3ba"
	UUID of the constant value gate standing for the NULL value, the result of `gate_null()`.

Enumerations
enum	gate_type { gate_input , gate_plus , gate_times , gate_monus , gate_project , gate_zero , gate_one , gate_eq , gate_agg , gate_semimod , gate_cmp , gate_delta , gate_value , gate_mulinput , gate_update , gate_rv , gate_arith , gate_mixture , gate_assumed , gate_annotation , gate_conditioned , gate_mobius , gate_case , gate_observe , gate_invalid , nb_gate_types }
	Possible gate types in the provenance circuit. More...
enum	provsql_arith_op { PROVSQL_ARITH_PLUS = 0 , PROVSQL_ARITH_TIMES = 1 , PROVSQL_ARITH_MINUS = 2 , PROVSQL_ARITH_DIV = 3 , PROVSQL_ARITH_NEG = 4 , PROVSQL_ARITH_MAX = 5 , PROVSQL_ARITH_MIN = 6 , PROVSQL_ARITH_POW = 7 , PROVSQL_ARITH_LN = 8 , PROVSQL_ARITH_EXP = 9 , PROVSQL_ARITH_PERCENTILE = 10 , PROVSQL_ARITH_INTDIV = 11 , PROVSQL_ARITH_ROUND = 12 , PROVSQL_ARITH_FLOOR = 13 , PROVSQL_ARITH_CEIL = 14 , PROVSQL_ARITH_ABS = 15 , PROVSQL_ARITH_ASFLOAT8 = 16 , PROVSQL_ARITH_ASFLOAT4 = 17 }
	Arithmetic operator tags used by `gate_arith`. More...
enum	provsql_route { PROVSQL_ROUTE_NONE = 0 , PROVSQL_ROUTE_SQ_REWRITE = 1 , PROVSQL_ROUTE_BOUNDED_JW = 2 , PROVSQL_ROUTE_REACHABILITY = 3 }
	Tags identifying the planner-time route that produced a circuit. More...

Functions
static const char *	provsql_route_name (provsql_route route)
	The name of a route, as the probability dispatcher reports it and as the annotation wrapper of a materialised root carries it (`"route:<name>"`); NULL for `PROVSQL_ROUTE_NONE`.
constants_t	get_constants (bool failure_if_not_possible)
	Retrieve the cached OID constants for the current database.
Oid	find_equality_operator (Oid ltypeId, Oid rtypeId)
	Find the equality operator OID for two given types.
const char *	provsql_kcmcp_managed_endpoint (void)
	Read the live endpoint of the managed KCMCP server from shared memory (e.g.
void	RegisterProvSQLKCMCPWorker (void)
	Register the supervisor background worker that launches and supervises the managed KCMCP server; called from _PG_init alongside the mmap worker.
bool	provsql_lookup_table_info (Oid relid, ProvenanceTableInfo *out)
	Look up per-table provenance metadata with a backend-local cache.
bool	provsql_fetch_table_info (Oid relid, ProvenanceTableInfo *out)
	Raw IPC fetch (no cache).
bool	provsql_lookup_ancestry (Oid relid, uint16 ancestor_n_out, Oid ancestors_out)
	Look up the base-ancestor set of a tracked relation.
bool	provsql_fetch_ancestry (Oid relid, uint16 ancestor_n_out, Oid ancestors_out)
	Raw IPC fetch for the ancestry half (no cache).
bool	provsql_lookup_relation_keys (Oid relid, ProvenanceRelationKeys *out)
	Look up the PRIMARY-KEY and NOT-NULL-UNIQUE keys of a relation with a backend-local cache.
void	provsql_sha1 (const unsigned char *data, size_t len, unsigned char out[20])
	SHA-1 of `len` bytes of `data` (RFC 3174).
pg_uuid_t	provsql_plant_canonical (const char work_name, gate_type type, const pg_uuid_t children, int n, const pg_uuid_t *target, unsigned info1, unsigned info2)
	Pre-create ("plant") a gate at the canonical address of a multiset of tokens, for the working table of the recursive CTE being lowered.
void	provsql_gate_builders_forget (void)
	Forget what `gate_builders.c` remembers of the store (planted gates, value gates written).

Variables
const char *	gate_type_name []
	Names of gate types.
bool	provsql_interrupted
	Global variable that becomes true if this particular backend received an interrupt signal.
bool	provsql_where_provenance
	Global variable that indicates if where-provenance support has been activated through the provsql.where_provenance run-time configuration parameter.
int	provsql_verbose
	Global variable that indicates the verbosity level set by the provsql.verbose_level run-time configuration parameter was set.
char *	provsql_transaction_token
	Global variable backing the provsql.transaction_token run-time configuration parameter: the textual UUID of the update gate standing for the current transaction, or empty when it has none yet.
bool	provsql_synchronous_commit
	Global variable set by the provsql.synchronous_commit run-time configuration parameter: when true, a transaction that has written to the circuit store forces the store to stable storage before it commits.
char *	provsql_last_eval_method
	Global variable holding the probability evaluation method(s) used by the most recent probability_evaluate call, exposed via the provsql.last_eval_method run-time configuration parameter.
bool	provsql_aggtoken_text_as_uuid
	Global flag controlling agg_token text output: when true, agg_token_out emits the underlying provenance UUID instead of the default "value (*)" display string.
unsigned	provsql_stmt_serial
	Serial of the user's current statement (`provsql.c`), read by the `agg_token` conversions to warn once for a statement, not once per row.
char *	provsql_tool_search_path
	Colon-separated list of directories prepended to PATH when ProvSQL spawns external tools (d4, c2d, minic2d, dsharp, weightmc, graph-easy), set by the provsql.tool_search_path run-time configuration parameter.
char *	provsql_fallback_compiler
	Compiler invoked as the final fallback in BooleanCircuit::makeDD when both interpretAsDD() and the in-process tree-decomposition path fail (the latter typically on treewidth blow-up).
char *	provsql_kcmcp_server
	Launch command for the managed KCMCP knowledge-compiler server, set by the provsql.kcmcp_server run-time configuration parameter (PGC_SIGHUP).
int	provsql_monte_carlo_seed
	Seed for the Monte Carlo sampler, set by the provsql.monte_carlo_seed run-time configuration parameter.
int	provsql_rv_mc_samples
	Default sample count for Monte Carlo fallbacks when an analytical evaluator (Expectation, future hybrid evaluator, ...) cannot decompose a sub-circuit structurally.
double	provsql_ess_warn_fraction
	Effective-sample-size warning threshold for likelihood weighting: warn when the posterior ESS falls below this fraction of the accepted draws; controlled by the `provsql.ess_warn_fraction` GUC.
int	provsql_dtree_max_subproblems
	Debug/safety hard cap on d-tree subproblems before it bails (0 = off; the chooser auto-budgets at the next-best method's cost regardless); `provsql.dtree_max_subproblems` GUC.
int	provsql_joint_max_treewidth
	Maximum joint treewidth the joint-width UCQ compiler attempts before declining (caller falls back to the ladder); `provsql.joint_max_treewidth` GUC.
int	provsql_joint_max_states
	Per-bag DP state-count cap of the joint-width UCQ compiler (the true safety net); `provsql.joint_max_states` GUC.
int	provsql_gate_cache_size
	Byte budget, in kB, of the per-backend gate cache; `provsql.gate_cache_size` GUC.
bool	provsql_joint_width
	Recognise unsafe UCQs at planner time and route their existence provenance through the joint-width compiler (on by default); the `provsql.joint_width` GUC is a debug-only switch to disable it.
bool	provsql_mobius
	Try the safe-UCQ Möbius-inversion route (a guaranteed-PTIME exact route for its class) BEFORE the joint-width compiler, which it short-circuits on success (on by default); the `provsql.mobius` GUC is a debug-only switch to disable it.
int	provsql_mobius_max_gates
	Data-cost cap of the Möbius route: it declines (falling through to joint-width / the ladder) once its compile has built more than this many gates, bounding the \(O(\|D\|^k)\) blow-up of a high-level safe query on large data; `provsql.mobius_max_gates` GUC.
int	provsql_mobius_max_cnf
	Query-cost cap of the Möbius route: it declines when a sentence's CNF has more than this many conjuncts, since the inclusion-exclusion lattice it walks has \(2^M\) elements; ranking / shattering can inflate the conjunct count, which is what raising it buys; `provsql.mobius_max_cnf` GUC.
bool	provsql_simplify_on_load
	When `true` (default), every `GenericCircuit` returned by `getGenericCircuit` is run through the universal cmp-resolution passes (RangeCheck for now, plus any future passes that decide comparators to certain Boolean values).
bool	provsql_hybrid_evaluation
	Run the hybrid evaluator (simplifier + per-cmp island decomposer) before dispatching a probability_evaluate query.
bool	provsql_cmp_probability_evaluation
	Hidden diagnostic flag for the family of closed-form / analytic probability evaluators that resolve `gate_cmps` inside `probability_evaluate` ; see the `provsql.cmp_probability_evaluation` GUC.
bool	provsql_inversion_free
	Kill-switch for the inversion-free structured-d-DNNF probability path; see the `provsql.inversion_free` GUC.
bool	provsql_boolean_provenance
	Opt-in safe-query optimisation for hierarchical conjunctive queries; see the `provsql.boolean_provenance` GUC.
bool	provsql_absorptive_provenance
	Derived flag of the `provsql.provenance` GUC: the session's provenance class is 'absorptive' or 'boolean', licensing constructions sound for absorptive semirings only (cyclic recursion stopped at the absorptive value fixpoint, tagged tokens).

Detailed Description

Core types, constants, and utilities shared across ProvSQL.

This header is included by virtually every source file in the extension. It provides:

The gate_type enumeration listing all circuit-gate kinds recognised by ProvSQL (input, semiring operations, aggregation, etc.)
The constants_t structure caching PostgreSQL OIDs for the types, functions, and operators that ProvSQL installs, so that OID lookups happen once per session rather than on every query.
The database_constants_t wrapper for per-database OID caches.
Helper declarations for OID lookup and UUID manipulation.
Global flags controlling interrupt handling, where-provenance, and verbosity.
An implicit inclusion of provsql_error.h for the provsql_error / provsql_warning / provsql_notice / provsql_log macros.

Definition in file provsql_utils.h.

Macro Definition Documentation

◆ PROVSQL_AGG_SCALAR_FLAG

#define PROVSQL_AGG_SCALAR_FLAG 0x80000000u

Scalar-aggregation flag, stored in the upper bit of a gate_agg's info2 (whose low 31 bits hold the aggregate result-type OID).

Set by the query rewriter when the aggregation has no GROUP BY (a single always-present result row). It tells the value-aware evaluators that the empty-input world is a real possible world (carrying the aggregate's empty-group value), rather than the "no row" of a grouped query. Result-type OIDs never use bit 31, so the low 31 bits still recover the type via PROVSQL_AGG_TYPE_MASK.

Warning: The flag is folded into the gate's content UUID (see provenance_aggregate), so a scalar and a grouped aggregate over identical children stay distinct gates recording different infos.

Definition at line 87 of file provsql_utils.h.

◆ PROVSQL_AGG_TYPE_MASK

#define PROVSQL_AGG_TYPE_MASK 0x7FFFFFFFu

Definition at line 88 of file provsql_utils.h.

◆ PROVSQL_COLUMN_NAME

#define PROVSQL_COLUMN_NAME "provsql"

Canonical name of the per-row provenance column installed by add_provenance / repair_key.

Centralised so the planner-hook entry points (src/provsql.c) and the safe-query detector (src/safe_query.c) agree on the literal; see the provenance_guard trigger in sql/provsql.common.sql.

Definition at line 205 of file provsql_utils.h.

◆ PROVSQL_GATE_NULL_UUID

#define PROVSQL_GATE_NULL_UUID "417134e7-a404-57a7-86fd-2577ebe0f3ba"

UUID of the constant value gate standing for the NULL value, the result of gate_null().

Definition at line 907 of file provsql_utils.h.

◆ PROVSQL_GATE_ONE_UUID

#define PROVSQL_GATE_ONE_UUID "d265daa9-f206-561d-845c-2a85fa0fa72c"

UUID of the semiring one gate, the result of gate_one().

Definition at line 904 of file provsql_utils.h.

◆ PROVSQL_GATE_ZERO_UUID

#define PROVSQL_GATE_ZERO_UUID "19257535-6aaf-5275-b02b-899c48576553"

UUID of the semiring zero gate: the result of the SQL function gate_zero(), created with the extension (test agg_filter checks the two agree).

Definition at line 902 of file provsql_utils.h.

◆ PROVSQL_KEY_CACHE_MAX_KEY_COLS

#define PROVSQL_KEY_CACHE_MAX_KEY_COLS 8

Definition at line 783 of file provsql_utils.h.

◆ PROVSQL_KEY_CACHE_MAX_KEYS

#define PROVSQL_KEY_CACHE_MAX_KEYS 4

Upper bounds for the relation-key cache.

Each relation contributes at most PROVSQL_KEY_CACHE_MAX_KEYS distinct PRIMARY-KEY / NOT-NULL-UNIQUE column-sets, each over at most PROVSQL_KEY_CACHE_MAX_KEY_COLS columns. These bounds keep the cache entry fixed-size (so the backend-local sorted-array representation can reuse the provsql_lookup_table_info pattern verbatim); relations with more or wider keys silently drop the overflow, treating the missing keys as if they did not exist (over-conservative – the §2 FD-aware detector simply misses an optimisation, never produces an unsound rewrite).

Definition at line 782 of file provsql_utils.h.

Enumeration Type Documentation

◆ gate_type

enum gate_type

Possible gate types in the provenance circuit.

Warning: ON-DISK ABI: this enum's integer values are stored in the gates.mmap backing file (see MMappedCircuit). Reordering, inserting, or renumbering existing members will silently invalidate every existing installation's persistent circuit. New gate types must be appended at the end, just before gate_invalid. If an existing gate type ever needs to be removed or renumbered, the mmap format must gain a version header and a migration path.

Enumerator
gate_input	Input (variable) gate of the circuit.
gate_plus	Semiring plus.
gate_times	Semiring times.
gate_monus	M-Semiring monus.
gate_project	Project gate (for where provenance).
gate_zero	Semiring zero.
gate_one	Semiring one.
gate_eq	Equijoin gate (for where provenance).
gate_agg	Aggregation operator (for aggregate provenance).
gate_semimod	Semimodule scalar multiplication (for aggregate provenance).
gate_cmp	Comparison of aggregate values (HAVING-clause provenance).
gate_delta	δ-semiring operator (see Amsterdamer, Deutch, Tannen, PODS 2011)
gate_value	Scalar value (for aggregate provenance).
gate_mulinput	Multivalued input (for Boolean provenance).
gate_update	Update operation.
gate_rv	Continuous random-variable leaf (extra encodes distribution).
gate_arith	n-ary arithmetic gate over scalar-valued children (info1 holds operator tag)
gate_mixture	Probabilistic mixture: three wires [p_token (gate_input Bernoulli), x_token, y_token]; samples x when p is true, y otherwise.
gate_assumed	Structural marker over a single child whose sub-circuit was computed under a Boolean-provenance assumption (e.g. the safe-query rewrite); transparent (identity) for Boolean-compatible evaluators, fatal error for the rest, kept as an explicit node in PROV-XML export.
gate_annotation	Transparent single-child wrapper carrying a query-level annotation in `extra` (inversion-free certificate / per-input order key); identity for EVERY evaluator, and – unlike the children-only convention – its UUID folds in `extra` so distinct annotations over the same child are distinct gates.
gate_conditioned	Conditioning marker with two children [target, evidence]: measure-only, `probability_evaluate` returns P(target ∧ evidence)/P(evidence) and the RV / agg_token evaluators the restricted distribution; for the uuid carrier a TERMINAL gate (never a semiring child), nested conditioning folding into a conjunction of evidence; refused by every general `sr_*` semiring (normalization is not a semiring operation).
gate_mobius	Signed Möbius combination: a MEASURE-only gate carrying one integer coefficient per child (in `extra`, the `gate_arith` precedent), `probability_evaluate` returns Σ_i coeff_i · P(child_i); the one new primitive of the safe-UCQ Möbius-inversion route (see `MobiusCompiler.h`), with certified-independent Boolean islands below it; refused by every general `sr_*` semiring (a signed combination is not a semiring operation).
gate_case	N-ary guarded selection over scalar (RV) children: wires are [guard_1, value_1, ..., guard_k, value_k, default] (odd length 2k+1), first-match semantics – the value of the first guard (a Boolean `gate_cmp` / event) that holds, else the default. Carries data only in its wires (the `gate_conditioned` precedent: no `info` / `extra`). RV/measure-carrier: a real arm in the MC sampler / RangeCheck / Expectation footprint, refused by every general `sr_*` semiring (a guarded selection is not a semiring operation).
gate_observe	Latent-variable observation (likelihood-weighting evidence): one wire → an observed bare `gate_rv` leaf, the datum in `extra`. Contributes a continuous density factor (the leaf's pdf at the datum) instead of a Boolean truth value, composing into an evidence circuit by `gate_times` exactly like a conditioning event. Evaluated only by the importance-sampling weight walk (`Sampler::evalWeight`); refused by every Boolean / semiring evaluator (a density factor is not a semiring operation).
gate_invalid	Invalid gate type.
nb_gate_types	Total number of gate types.

Definition at line 43 of file provsql_utils.h.

◆ provsql_arith_op

enum provsql_arith_op

Arithmetic operator tags used by gate_arith.

Stored in the gate's info1 field. Local enum (not a PostgreSQL operator OID) because arithmetic in the sampler / evaluator is just C++ doubles, with no need to dispatch through the PG catalog.

Warning: ON-DISK ABI: like gate_type, these integer values are persisted (in info1). Reordering or renumbering existing tags will silently invalidate every existing installation's persistent circuit. New tags must be appended at the end.

Enumerator
PROVSQL_ARITH_PLUS	n-ary, sum of children
PROVSQL_ARITH_TIMES	n-ary, product of children
PROVSQL_ARITH_MINUS	binary, child0 - child1
PROVSQL_ARITH_DIV	binary, child0 / child1
PROVSQL_ARITH_NEG	unary, -child0
PROVSQL_ARITH_MAX	n-ary, max of children (order statistic; greatest / max aggregate)
PROVSQL_ARITH_MIN	n-ary, min of children (order statistic; least / min aggregate)
PROVSQL_ARITH_POW	binary, child0 ^ child1 (real branch only: a negative base drawn with a non-integer exponent raises at evaluation)
PROVSQL_ARITH_LN	unary, natural logarithm of child0 (a negative draw raises at evaluation)
PROVSQL_ARITH_EXP	unary, e^child0
PROVSQL_ARITH_PERCENTILE	continuous percentile (order-statistic aggregate): wires are interleaved [ind_1, x_1, ..., ind_n, x_n] (even count) where ind_i is the row's 0/1 presence indicator; the fraction is text-encoded in `extra`. Per draw: the values whose indicator draws 1 are sorted and linearly interpolated at the fraction (SQL `percentile_cont`); an empty draw is NaN (undefined world).
PROVSQL_ARITH_INTDIV	binary, child0 / child1 truncated toward zero: SQL's division of two integers
PROVSQL_ARITH_ROUND	child0 rounded half away from zero, to child1 decimal digits where a second child is given (SQL `round(v)` / `round(v, d)`)
PROVSQL_ARITH_FLOOR	unary, greatest integer <= child0
PROVSQL_ARITH_CEIL	unary, least integer >= child0
PROVSQL_ARITH_ABS	unary, \|child0\|
PROVSQL_ARITH_ASFLOAT8	unary, child0 as `double` `precision` reads it. The gates compute in `numeric`, which loses nothing; a query whose expression is a float reads the value as SQL does, and this is what says so – the rewriter puts it where the type would otherwise be lost (the widening cast it peels off an aggregate, the result of arithmetic it swapped onto the agg_token operators). Transparent to every pass that walks arithmetic: it is the value of its child, rounded to that type.
PROVSQL_ARITH_ASFLOAT4	unary, child0 as `real` reads it

Definition at line 102 of file provsql_utils.h.

◆ provsql_route

enum provsql_route

Tags identifying the planner-time route that produced a circuit.

Three rewrites replace a query's ordinary lineage with a circuit of their own – the safe-query (read-once) rewriter, the joint-width UCQ compiler and the recursive-reachability compiler – and all three then hand that circuit to the ordinary probability dispatcher, which evaluates it by an independent / certified-island sweep. Without a tag the three are indistinguishable at evaluation time and all report independent. Each route therefore stamps its tag on the root gate it produces, and probability_evaluate.cpp turns that into a first-class method name (sq-rewrite / bounded-jw / reachability) for provsql.last_eval_method and for byName dispatch.

Where the tag lives depends on what the route's root already carries: PROVSQL_ROUTE_SQ_REWRITE and PROVSQL_ROUTE_REACHABILITY go in info1 of the gate_assumed wrapper the route puts on its root (the assumption kind in extra – 'boolean' / 'absorptive' – does not identify the route: both are also reachable through the public provenance_assume), while PROVSQL_ROUTE_BOUNDED_JW goes in info2 of the materialised d-D root, whose info1 is already DNNF_CERT_INFO.

Warning: ON-DISK ABI: like gate_type and provsql_arith_op, these integer values are persisted (in info1 / info2). Reordering or renumbering existing tags will silently mislabel every existing installation's persistent circuit. New tags must be appended at the end.

Enumerator
PROVSQL_ROUTE_NONE	No route rewrite: ordinary lineage.
PROVSQL_ROUTE_SQ_REWRITE	Hierarchical-CQ read-once rewrite (`src/safe_query.c`).
PROVSQL_ROUTE_BOUNDED_JW	Joint-width UCQ compiler (`src/UCQJointCompiler.h`).
PROVSQL_ROUTE_REACHABILITY	Recursive-reachability compiler (`src/reachability_evaluate.cpp`).

Definition at line 174 of file provsql_utils.h.

Function Documentation

◆ find_equality_operator()

Oid find_equality_operator	(	Oid	ltypeId,
		Oid	rtypeId )

Find the equality operator OID for two given types.

Searches pg_operator for the = operator that accepts ltypeId on the left and rtypeId on the right.

Parameters

ltypeId	OID of the left operand type.
rtypeId	OID of the right operand type.

Returns: The operator OID, or InvalidOid if none is found.

Definition at line 135 of file provsql_utils.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_constants()

constants_t get_constants ( bool failure_if_not_possible )

Retrieve the cached OID constants for the current database.

On first call (or after a cache miss) this function looks up the OIDs of all ProvSQL-specific types, functions, and operators in the system catalogs and stores them in a per-database cache. Subsequent calls return the cached values without touching the catalogs.

Parameters

failure_if_not_possible If true, call provsql_error when the ProvSQL schema cannot be found (e.g. the extension is not installed in the current database). If false, return a constants_t with ok==false instead of aborting.

Returns: A constants_t whose ok field is true on success.

Definition at line 811 of file provsql_utils.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_fetch_ancestry()

bool provsql_fetch_ancestry	(	Oid	relid,
		uint16 *	ancestor_n_out,
		Oid *	ancestors_out )

extern

Raw IPC fetch for the ancestry half (no cache).

Implementation detail of provsql_lookup_ancestry, exposed so the cache layer in provsql_utils.c can reach it. Callers in the planner hot path should go through provsql_lookup_ancestry.

Definition at line 180 of file table_info.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_fetch_table_info()

bool provsql_fetch_table_info	(	Oid	relid,
		ProvenanceTableInfo *	out )

extern

Raw IPC fetch (no cache).

Implementation detail of provsql_lookup_table_info, exposed only so the cache layer in provsql_utils.c can reach it. Callers in the planner hot path should go through provsql_lookup_table_info.

Definition at line 175 of file table_info.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_gate_builders_forget()

void provsql_gate_builders_forget ( void )

Forget what gate_builders.c remembers of the store (planted gates, value gates written).

For circuit_cleanup, which may remove gates.

Definition at line 473 of file gate_builders.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_kcmcp_managed_endpoint()

const char * provsql_kcmcp_managed_endpoint ( void )

Read the live endpoint of the managed KCMCP server from shared memory (e.g.

"unix:/tmp/..."), or an empty string when none is running.

Definition at line 67 of file kcmcp_supervisor.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_lookup_ancestry()

bool provsql_lookup_ancestry	(	Oid	relid,
		uint16 *	ancestor_n_out,
		Oid *	ancestors_out )

extern

Look up the base-ancestor set of a tracked relation.

Per-backend cached over IPC. Returns the ancestor set when relid is tracked and the registry has a non-empty entry for it. false either when relid has no metadata record at all (the relation was never run through add_provenance / repair_key) or when the record exists but ancestor_n == 0 (the CTAS hook hasn't populated the lineage yet, or the registry was explicitly cleared). The two failure modes share the false return because both make the safe-query rewriter take the conservative refuse path – there is no use case for treating them differently.

Backed by the same per-backend cache as provsql_lookup_table_info and invalidated through the same relcache-invalidation callback, so concurrent set_ancestors / add_provenance / repair_key calls in other backends are reflected here without polling.

Parameters

relid	pg_class OID of the relation to look up.
ancestor_n_out	On `true` return, count of valid entries in `ancestors_out`.
ancestors_out	On `true` return, the sorted-deduplicated ancestor OIDs (caller-allocated buffer of `PROVSQL_TABLE_INFO_MAX_ANCESTORS` `Oid`).

Returns: true on a non-empty ancestor set; false otherwise.

Definition at line 1072 of file provsql_utils.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_lookup_relation_keys()

bool provsql_lookup_relation_keys	(	Oid	relid,
		ProvenanceRelationKeys *	out )

extern

Look up the PRIMARY-KEY and NOT-NULL-UNIQUE keys of a relation with a backend-local cache.

Companion to provsql_lookup_table_info. The cache lives in a separate backing array with its own relcache-invalidation callback so that a future ALTER TABLE that adds / drops a constraint refreshes the next lookup without polling. Returns true when the relation has at least one PRIMARY KEY or NOT-NULL UNIQUE constraint; false otherwise (in which case *out is filled with key_n = 0). Safe to call from the planner hot path.

Parameters

relid	pg_class OID of the relation to inspect.
out	Filled on return. `out->relid` is set to `relid` regardless of return value; `out->keys` holds up to `PROVSQL_KEY_CACHE_MAX_KEYS` keys.

Definition at line 1305 of file provsql_utils.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_lookup_table_info()

bool provsql_lookup_table_info	(	Oid	relid,
		ProvenanceTableInfo *	out )

extern

Look up per-table provenance metadata with a backend-local cache.

Resolves to a cached value when the relation's relcache entry has not been invalidated since the last fetch; otherwise issues one 's' IPC to the background worker. The cache is invalidated via CacheRegisterRelcacheCallback, so concurrent add_provenance / repair_key / remove_provenance in other backends are reflected here without polling.

Safe to call from the planner hot path.

Parameters

relid	pg_class OID of the relation to look up.
out	On `true` return, filled with the stored record.

Returns: true if a record exists for relid, false otherwise.

Definition at line 944 of file provsql_utils.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_plant_canonical()

pg_uuid_t provsql_plant_canonical	(	const char *	work_name,
		gate_type	type,
		const pg_uuid_t *	children,
		int	n,
		const pg_uuid_t *	target,
		unsigned	info1,
		unsigned	info2 )

Pre-create ("plant") a gate at the canonical address of a multiset of tokens, for the working table of the recursive CTE being lowered.

The gate, of type type (gate_plus or gate_times), has the single child target and the given infos; its address is remembered in this backend, where provenance_plus / provenance_times return it in place of an ordinary gate over children. Defined in gate_builders.c.

Parameters

work_name	working table the tokens belong to; NULL for the one declared last by `planted_scope()`
type	`gate_plus` or `gate_times`
children	the multiset the planted gate stands for
n	number of `children`
target	root of the certified circuit, the gate's single child
info1	first info of the planted gate
info2	second info of the planted gate

Returns: the address of the planted gate

Definition at line 267 of file gate_builders.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ provsql_route_name()

const char * provsql_route_name ( provsql_route route )

inlinestatic

The name of a route, as the probability dispatcher reports it and as the annotation wrapper of a materialised root carries it ("route:<name>"); NULL for PROVSQL_ROUTE_NONE.

Definition at line 184 of file provsql_utils.h.

Here is the caller graph for this function:

◆ provsql_sha1()

void provsql_sha1	(	const unsigned char *	data,
		size_t	len,
		unsigned char	out[20] )

SHA-1 of len bytes of data (RFC 3174).

Self-contained, so that gate addresses, which are version-5 UUIDs, are computed the same way on every supported PostgreSQL version. Defined in CertifiedDDMaterialize.cpp.

Definition at line 96 of file CertifiedDDMaterialize.cpp.

Here is the caller graph for this function:

◆ RegisterProvSQLKCMCPWorker()

void RegisterProvSQLKCMCPWorker ( void )

Register the supervisor background worker that launches and supervises the managed KCMCP server; called from _PG_init alongside the mmap worker.

Definition at line 260 of file kcmcp_supervisor.c.

Here is the caller graph for this function:

Variable Documentation

◆ gate_type_name

const char* gate_type_name[]

extern

Names of gate types.

Definition at line 55 of file provsql_utils.c.

◆ provsql_absorptive_provenance

bool provsql_absorptive_provenance

extern

Derived flag of the provsql.provenance GUC: the session's provenance class is 'absorptive' or 'boolean', licensing constructions sound for absorptive semirings only (cyclic recursion stopped at the absorptive value fixpoint, tagged tokens).

Definition at line 139 of file provsql.c.

◆ provsql_aggtoken_text_as_uuid

bool provsql_aggtoken_text_as_uuid

extern

Global flag controlling agg_token text output: when true, agg_token_out emits the underlying provenance UUID instead of the default "value (*)" display string.

Driven by the provsql.aggtoken_text_as_uuid GUC.

Global flag controlling agg_token text output: when true, agg_token_out emits the underlying provenance UUID instead of the default "value (*)" display string.

Definition at line 119 of file provsql.c.

◆ provsql_boolean_provenance

bool provsql_boolean_provenance

extern

Opt-in safe-query optimisation for hierarchical conjunctive queries; see the provsql.boolean_provenance GUC.

When true, the planner is permitted to rewrite self-join-free hierarchical CQs (and independent UCQs) over TID / BID tables to a read-once form whose probability is computable in linear time. The rewriter tags the resulting root gate so that semiring evaluations incompatible with this rewrite refuse to run on the produced circuit.

Opt-in safe-query optimisation for hierarchical conjunctive queries; see the provsql.boolean_provenance GUC.

Definition at line 138 of file provsql.c.

◆ provsql_cmp_probability_evaluation

bool provsql_cmp_probability_evaluation

extern

Hidden diagnostic flag for the family of closed-form / analytic probability evaluators that resolve gate_cmps inside probability_evaluate ; see the provsql.cmp_probability_evaluation GUC.

When on (default), probability_evaluate runs pre-passes that recognise specific gate_cmp shapes and replace each cmp with a Bernoulli gate_input carrying the closed-form probability, bypassing the DNF that provsql_having's enumerate_valid_worlds would otherwise emit. The first implementation in this family is the Poisson-binomial pre-pass for HAVING COUNT(*) op C over distinct gate_input leaves (see CountCmpEvaluator.h) ; future MIN / MAX / SUM evaluators will gate on the same flag. Off forces every cmp to fall through to the enumeration path. End users have no reason to flip this ; exists for developer A/B testing and as a bisection escape valve.

Hidden diagnostic flag for the family of closed-form / analytic probability evaluators that resolve gate_cmps inside probability_evaluate ; see the provsql.cmp_probability_evaluation GUC.

Definition at line 136 of file provsql.c.

◆ provsql_dtree_max_subproblems

int provsql_dtree_max_subproblems

extern

Debug/safety hard cap on d-tree subproblems before it bails (0 = off; the chooser auto-budgets at the next-best method's cost regardless); provsql.dtree_max_subproblems GUC.

Definition at line 126 of file provsql.c.

◆ provsql_ess_warn_fraction

double provsql_ess_warn_fraction

extern

Effective-sample-size warning threshold for likelihood weighting: warn when the posterior ESS falls below this fraction of the accepted draws; controlled by the provsql.ess_warn_fraction GUC.

Definition at line 125 of file provsql.c.

◆ provsql_fallback_compiler

char* provsql_fallback_compiler

extern

Compiler invoked as the final fallback in BooleanCircuit::makeDD when both interpretAsDD() and the in-process tree-decomposition path fail (the latter typically on treewidth blow-up).

Defaults to "d4"; set by the provsql.fallback_compiler run-time configuration parameter to any compiler accepted by BooleanCircuit::compilation (d4 / d4v2 / c2d / minic2d / dsharp / panini-*).

Compiler invoked as the final fallback in BooleanCircuit::makeDD when both interpretAsDD() and the in-process tree-decomposition path fail (the latter typically on treewidth blow-up).

Definition at line 121 of file provsql.c.

◆ provsql_gate_cache_size

int provsql_gate_cache_size

extern

Byte budget, in kB, of the per-backend gate cache; provsql.gate_cache_size GUC.

Definition at line 128 of file provsql.c.

◆ provsql_hybrid_evaluation

bool provsql_hybrid_evaluation

extern

Run the hybrid evaluator (simplifier + per-cmp island decomposer) before dispatching a probability_evaluate query.

Debug-only GUC, hidden from SHOW ALL and from postgresql.conf.sample (registered with GUC_NO_SHOW_ALL | GUC_NOT_IN_SAMPLE). When on (default), probability_evaluate runs the HybridEvaluator simplifier between RangeCheck and AnalyticEvaluator and the per-cmp MC island decomposer after AnalyticEvaluator: gate_arith subtrees are constant-folded and family-closed (normals, Erlang), and residual continuous-island comparators are MC-marginalised into Bernoulli gate_input leaves so the surrounding circuit becomes purely Boolean.

Set to off to bypass both passes: undecidable comparators then fall through to whole-circuit MC (for the monte-carlo method) or raise (for independent / tree-decomposition). End users have no reason to flip this – on is strictly better for them. Exists for developer A/B testing of the analytic path against the raw MC path and as a bisection knob if a closure rule turns out to be unsound on some workload.

Run the hybrid evaluator (simplifier + per-cmp island decomposer) before dispatching a probability_evaluate query.

Definition at line 135 of file provsql.c.

◆ provsql_interrupted

bool provsql_interrupted

extern

Global variable that becomes true if this particular backend received an interrupt signal.

Definition at line 109 of file provsql.c.

◆ provsql_inversion_free

bool provsql_inversion_free

extern

Kill-switch for the inversion-free structured-d-DNNF probability path; see the provsql.inversion_free GUC.

When on (default), probability_evaluate, on a query carrying an inversion-free tractability certificate, tries the structured-d-DNNF builder after independentEvaluation and before tree-decomposition / d4. Off disables only that automatic insertion (for A/B testing); the explicit probability_evaluate(token,'inversion-free') method ignores this flag. The path is self-gating on the certificate, which is attached only to certified queries, so leaving it on is safe.

Kill-switch for the inversion-free structured-d-DNNF probability path; see the provsql.inversion_free GUC.

Definition at line 137 of file provsql.c.

◆ provsql_joint_max_states

int provsql_joint_max_states

extern

Per-bag DP state-count cap of the joint-width UCQ compiler (the true safety net); provsql.joint_max_states GUC.

Definition at line 129 of file provsql.c.

◆ provsql_joint_max_treewidth

int provsql_joint_max_treewidth

extern

Maximum joint treewidth the joint-width UCQ compiler attempts before declining (caller falls back to the ladder); provsql.joint_max_treewidth GUC.

Definition at line 127 of file provsql.c.

◆ provsql_joint_width

bool provsql_joint_width

extern

Recognise unsafe UCQs at planner time and route their existence provenance through the joint-width compiler (on by default); the provsql.joint_width GUC is a debug-only switch to disable it.

Definition at line 130 of file provsql.c.

◆ provsql_kcmcp_server

char* provsql_kcmcp_server

extern

Launch command for the managed KCMCP knowledge-compiler server, set by the provsql.kcmcp_server run-time configuration parameter (PGC_SIGHUP).

The literal substring "{endpoint}" is replaced by the Unix-socket path the supervisor background worker chooses, e.g. "tdkc --kcmcp unix:{endpoint}". NULL or empty means no managed server is launched.

Launch command for the managed KCMCP knowledge-compiler server, set by the provsql.kcmcp_server run-time configuration parameter (PGC_SIGHUP).

Definition at line 122 of file provsql.c.

◆ provsql_last_eval_method

char* provsql_last_eval_method

extern

Global variable holding the probability evaluation method(s) used by the most recent probability_evaluate call, exposed via the provsql.last_eval_method run-time configuration parameter.

Definition at line 117 of file provsql.c.

◆ provsql_mobius

bool provsql_mobius

extern

Try the safe-UCQ Möbius-inversion route (a guaranteed-PTIME exact route for its class) BEFORE the joint-width compiler, which it short-circuits on success (on by default); the provsql.mobius GUC is a debug-only switch to disable it.

Definition at line 131 of file provsql.c.

◆ provsql_mobius_max_cnf

int provsql_mobius_max_cnf

extern

Query-cost cap of the Möbius route: it declines when a sentence's CNF has more than this many conjuncts, since the inclusion-exclusion lattice it walks has \(2^M\) elements; ranking / shattering can inflate the conjunct count, which is what raising it buys; provsql.mobius_max_cnf GUC.

Definition at line 133 of file provsql.c.

◆ provsql_mobius_max_gates

int provsql_mobius_max_gates

extern

Data-cost cap of the Möbius route: it declines (falling through to joint-width / the ladder) once its compile has built more than this many gates, bounding the \(O(|D|^k)\) blow-up of a high-level safe query on large data; provsql.mobius_max_gates GUC.

Definition at line 132 of file provsql.c.

◆ provsql_monte_carlo_seed

int provsql_monte_carlo_seed

extern

Seed for the Monte Carlo sampler, set by the provsql.monte_carlo_seed run-time configuration parameter.

-1 (default) means seed from std::random_device for non-deterministic sampling; any other value (including 0) is a literal seed for std::mt19937_64. Used by both the Bernoulli path (BooleanCircuit::monteCarlo) and the continuous path (gate_rv sampling), so a single GUC controls reproducibility end-to-end.

Seed for the Monte Carlo sampler, set by the provsql.monte_carlo_seed run-time configuration parameter.

Definition at line 123 of file provsql.c.

◆ provsql_rv_mc_samples

int provsql_rv_mc_samples

extern

Default sample count for Monte Carlo fallbacks when an analytical evaluator (Expectation, future hybrid evaluator, ...) cannot decompose a sub-circuit structurally.

Unlike probability_evaluate(token, 'monte-carlo', n) where the sample count is an explicit argument, these implicit MC paths have no natural place to take n from.

Set by the provsql.rv_mc_samples run-time configuration parameter; default 10000. Setting it to 0 disables the implicit MC fallback entirely: callers must then raise an exception rather than sampling. Useful for callers that want to guarantee analytical-only evaluation.

Default sample count for Monte Carlo fallbacks when an analytical evaluator (Expectation, future hybrid evaluator, ...) cannot decompose a sub-circuit structurally.

Definition at line 124 of file provsql.c.

◆ provsql_simplify_on_load

bool provsql_simplify_on_load

extern

When true (default), every GenericCircuit returned by getGenericCircuit is run through the universal cmp-resolution passes (RangeCheck for now, plus any future passes that decide comparators to certain Boolean values).

Decisions become Bernoulli gate_input gates with probability 0 or 1, transparent to every downstream consumer (semiring evaluators, MC, view_circuit, PROV export, etc.). Set provsql.simplify_on_load to off when inspecting a circuit's raw structure (e.g. debugging gate-creation code paths).

When true (default), every GenericCircuit returned by getGenericCircuit is run through the universal cmp-resolution passes (RangeCheck for now, plus any future passes that decide comparators to certain Boolean values).

Definition at line 134 of file provsql.c.

◆ provsql_stmt_serial

unsigned provsql_stmt_serial

extern

Serial of the user's current statement (provsql.c), read by the agg_token conversions to warn once for a statement, not once per row.

Definition at line 224 of file provsql.c.

◆ provsql_synchronous_commit

bool provsql_synchronous_commit

extern

Global variable set by the provsql.synchronous_commit run-time configuration parameter: when true, a transaction that has written to the circuit store forces the store to stable storage before it commits.

Definition at line 202 of file provsql_mmap.c.

◆ provsql_tool_search_path

char* provsql_tool_search_path

extern

Colon-separated list of directories prepended to PATH when ProvSQL spawns external tools (d4, c2d, minic2d, dsharp, weightmc, graph-easy), set by the provsql.tool_search_path run-time configuration parameter.

NULL or empty means rely on the server's PATH alone.

Colon-separated list of directories prepended to PATH when ProvSQL spawns external tools (d4, c2d, minic2d, dsharp, weightmc, graph-easy), set by the provsql.tool_search_path run-time configuration parameter.

Definition at line 120 of file provsql.c.

◆ provsql_transaction_token

char* provsql_transaction_token

extern

Global variable backing the provsql.transaction_token run-time configuration parameter: the textual UUID of the update gate standing for the current transaction, or empty when it has none yet.

Definition at line 118 of file provsql.c.

◆ provsql_verbose

int provsql_verbose

extern

Global variable that indicates the verbosity level set by the provsql.verbose_level run-time configuration parameter was set.

Definition at line 113 of file provsql.c.

◆ provsql_where_provenance

bool provsql_where_provenance

extern

Global variable that indicates if where-provenance support has been activated through the provsql.where_provenance run-time configuration parameter.

Definition at line 111 of file provsql.c.

Classes

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ PROVSQL_AGG_SCALAR_FLAG

◆ PROVSQL_AGG_TYPE_MASK

◆ PROVSQL_COLUMN_NAME

◆ PROVSQL_GATE_NULL_UUID

◆ PROVSQL_GATE_ONE_UUID

◆ PROVSQL_GATE_ZERO_UUID

◆ PROVSQL_KEY_CACHE_MAX_KEY_COLS

◆ PROVSQL_KEY_CACHE_MAX_KEYS

Enumeration Type Documentation

◆ gate_type

◆ provsql_arith_op

◆ provsql_route

Function Documentation

◆ find_equality_operator()

◆ get_constants()

◆ provsql_fetch_ancestry()

◆ provsql_fetch_table_info()

◆ provsql_gate_builders_forget()

◆ provsql_kcmcp_managed_endpoint()

◆ provsql_lookup_ancestry()

◆ provsql_lookup_relation_keys()

◆ provsql_lookup_table_info()

◆ provsql_plant_canonical()

◆ provsql_route_name()

◆ provsql_sha1()

◆ RegisterProvSQLKCMCPWorker()

Variable Documentation

◆ gate_type_name

◆ provsql_absorptive_provenance

◆ provsql_aggtoken_text_as_uuid

◆ provsql_boolean_provenance

◆ provsql_cmp_probability_evaluation

◆ provsql_dtree_max_subproblems

◆ provsql_ess_warn_fraction

◆ provsql_fallback_compiler

◆ provsql_gate_cache_size

◆ provsql_hybrid_evaluation

◆ provsql_interrupted

◆ provsql_inversion_free

◆ provsql_joint_max_states

◆ provsql_joint_max_treewidth

◆ provsql_joint_width

◆ provsql_kcmcp_server

◆ provsql_last_eval_method

◆ provsql_mobius

◆ provsql_mobius_max_cnf

◆ provsql_mobius_max_gates

◆ provsql_monte_carlo_seed

◆ provsql_rv_mc_samples

◆ provsql_simplify_on_load

◆ provsql_stmt_serial

◆ provsql_synchronous_commit

◆ provsql_tool_search_path

◆ provsql_transaction_token

◆ provsql_verbose

◆ provsql_where_provenance