 |
ProvSQL SQL API
Adding support for provenance and uncertainty management to PostgreSQL databases
|
|
ProvSQL SQL API
Adding support for provenance and uncertainty management to PostgreSQL databases
|
Per-row helper: wrap an RV in mixture(prov, rv, as_random(0)).
More...
Topics | |
| Probability and Shapley values | |
| Create a δ-semiring gate wrapping a provenance token. | |
Functions | |
| UUID | provenance_delta (UUID token) |
| Create a δ-semiring gate wrapping a provenance token. | |
| AGG_TOKEN | provenance_aggregate (INTEGER aggfnoid, INTEGER aggtype, ANYELEMENT val, UUID[] tokens, BOOLEAN is_scalar=false) |
| Build an aggregate provenance gate from grouped tokens. | |
| UUID | provenance_semimod (ANYELEMENT val, UUID token) |
| Create a semimodule scalar multiplication gate. | |
Per-row helper: wrap an RV in mixture(prov, rv, as_random(0)).
Functions for building and evaluating aggregate (GROUP BY) provenance, including the δ-semiring operator and semimodule multiplication.
Internal helper used by the planner-hook rewriter to lift a sum(random_variable) argument into its provenance-aware form. Encodes one row's contribution to the SUM as a Bernoulli mixture over the row's provenance: with probability P(prov) the mixture samples rv, otherwise it samples the additive identity as_random(0). Exposed as a regular SQL function so the planner can construct a FuncExpr by name without needing to disambiguate mixture / as_random overloads at OID-lookup time.
State-transition function for sum(random_variable).
Appends the input RV's UUID to the running array. NULL inputs are skipped (matching standard SUM semantics). The aggregate's INITCOND is '{}' so the FINALFUNC always runs even on an empty group, which is what lets us return as_random(0) (the additive identity) for an empty SUM rather than NULL.
Final function for sum(random_variable): build a gate_arith PLUS root.
Empty group (state = '{}'): return as_random(0), the additive identity, so SUM over zero rows is the deterministic scalar 0 – matches the AGG_TOKEN convention in agg_raw_moment.
Singleton group: return the single child directly without minting a useless single-child gate_arith.
Otherwise: build gate_arith(PLUS, state) via provenance_arith.
Final function for avg(random_variable).
Builds the natural lift of "AVG = SUM / COUNT" into the random_variable algebra:
\[ \mathrm{AVG}(x) \;=\; \frac{\sum_i \mathbf{1}\{\varphi_i\} \cdot X_i} {\sum_i \mathbf{1}\{\varphi_i\}} \]
realised as gate_arith(DIV, num, denom) where num is the sum(random_variable) gate over the per-row mixtures and denom is the sum(random_variable) gate over the same provenance gates weighted by a per-row as_random(1) – exactly the SQL pattern "@c sum(x) @c / @c sum(as_random(1))" emitted as a single random_variable token.
Reuses sum_rv_sfunc as the state-transition function so the array of per-row UUIDs is collected identically to sum(random_variable). In a provenance-tracked query the planner-hook rewriter routes RV-returning aggregates through make_rv_aggregate_expression, which wraps each per-row argument in mixture(prov_i, x_i, as_random(0)); the FFUNC then recovers prov_i from each mixture's first child to construct the matching mixture(prov_i, as_random(1), as_random(0)) for the denominator. Outside a tracked query the per-row UUIDs are plain RV roots, in which case each row contributes an unconditional as_random(1) to the denominator – the natural extension of "no provenance =
every row counts" used elsewhere in the extension.
Empty group: returns NULL, matching the standard SQL AVG convention. This differs from sum(random_variable), which returns the additive identity as_random(0) for an empty group; for AVG the multiplicative identity is not the right answer and the caller has no way to disambiguate "0 rows" from "rows that
sum to 0".
Final function for product(random_variable).
Multiplicative analogue of sum(random_variable):
\[ \mathrm{PRODUCT}(x) \;=\; \prod_i \big(\mathbf{1}\{\varphi_i\} \cdot X_i + \mathbf{1}\{\neg\varphi_i\} \cdot 1\big) \;=\; \prod_{i : \varphi_i} X_i \]
realised as gate_arith(TIMES, mixtures) over per-row contributions whose else-branch is as_random(1) (the multiplicative identity), so rows whose provenance is false contribute 1 to the product instead of 0.
The C-side wrap shared with sum / avg always builds mixture(prov_i, X_i, as_random(0)); the PRODUCT FFUNC patches each mixture's else-branch to as_random(1) by reconstructing the mixture with the corrected else-arg. Going through provsql.mixture (rather than create_gate directly) keeps the gate v5-hash consistent with any other mixture sharing the same (prov_i, X_i, as_random(1)) triple.
Reuses sum_rv_sfunc as the state-transition function. Empty group: returns the multiplicative identity as_random(1) – the natural counterpart to sum(random_variable)'s empty-group as_random(0).
Singleton group: returns the single patched child directly without minting a useless single-child gate_arith TIMES root.
Direct (untracked) call: state entries are raw RV uuids rather than mixtures; pass them through unchanged so PRODUCT degenerates to the straight RV product over all rows, the natural "no provenance = every row counts" behaviour.
Functions for building and evaluating aggregate (GROUP BY) provenance, including the δ-semiring operator and semimodule multiplication.
| AGG_TOKEN update_provenance::provenance_aggregate | ( | INTEGER | aggfnoid, |
| INTEGER | aggtype, | ||
| ANYELEMENT | val, | ||
| UUID[] | tokens, | ||
| BOOLEAN | is_scalar = false ) |
Build an aggregate provenance gate from grouped tokens.
Called internally by the query rewriter for GROUP BY queries. Creates an agg gate linking all contributing tokens and records the aggregate function OID and the computed scalar value.
| aggfnoid | OID of the SQL aggregate function |
| aggtype | OID of the aggregate result type |
| val | computed aggregate value |
| tokens | array of provenance tokens being aggregated |
| is_scalar | true for a scalar (no GROUP BY) aggregation, whose output row exists even when no tuple is present; stored in the high bit of info2 |
| UUID update_provenance::provenance_delta | ( | UUID | token | ) |
Create a δ-semiring gate wrapping a provenance token.
Used internally for aggregate provenance. Returns the token unchanged if it is gate_zero() or gate_one(), and gate_one() if the token is NULL.
| UUID update_provenance::provenance_semimod | ( | ANYELEMENT | val, |
| UUID | token ) |
Create a semimodule scalar multiplication gate.
Pairs a scalar value with a provenance token, used internally by the query rewriter for aggregate provenance.
| val | the scalar value |
| token | the provenance token to multiply |