 |
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
|
Evaluate provenance using a compiled (built-in) semiring. More...
Topics | |
| Type for the result of aggregate queries | |
| Row type for sub_circuit_with_desc results. | |
Types | |
| TYPE | GATE_WITH_DESC |
| Row type for sub_circuit_with_desc results. More... | |
Functions | |
| SETOF GATE_WITH_DESC | sub_circuit_with_desc (UUID token, REGCLASS token2desc) |
| Return the sub-circuit reachable from a token, with descriptions. | |
| VOID | identify_token (UUID token, OUT REGCLASS table_name, OUT INTEGER nb_columns) |
| Identify which table and how many columns a provenance token belongs to. | |
| TABLE | sub_circuit_for_where (UUID token) |
| Return the sub-circuit for where-provenance computation. | |
| TABLE | circuit_subgraph (UUID root, INT max_depth=8) |
BFS expansion of a provenance circuit, capped at max_depth. | |
| jsonb | simplified_circuit_subgraph (UUID root, INT max_depth=8) |
BFS subgraph of the IN-MEMORY simplified circuit rooted at root. | |
| jsonb | rv_histogram (UUID token, INT bins=30, UUID prov=gate_one()) |
| Empirical histogram of a scalar sub-circuit. | |
| jsonb | rv_analytical_curves (UUID token, INT samples=100, UUID prov=gate_one()) |
| Sample the closed-form PDF and CDF of a (possibly truncated) scalar distribution. | |
| SETOF float8 | rv_sample (UUID token, INTEGER n, UUID prov=gate_one()) |
| Draw conditional Monte Carlo samples from a scalar gate. | |
| TABLE | resolve_input (UUID UUID) |
| Resolve an input gate UUID back to its source row. | |
Evaluate provenance using a compiled (built-in) semiring.
Functions for examining the structure of provenance circuits, used by visualization and where-provenance features.
This C function handles semiring evaluation entirely in C++ for better performance. The semiring is specified by name.
| token | provenance token to evaluate |
| token2value | mapping table from tokens to semiring values |
| semiring | name of the compiled semiring (e.g., "formula", "counting") |
| element_one | identity element of the semiring |
Evaluate provenance over a user-defined semiring (PL/pgSQL version)
Recursively walks the provenance circuit and evaluates each gate using the provided semiring operations. This is the generic version that accepts semiring operations as function references.
| token | provenance token to evaluate |
| token2value | mapping table from tokens to semiring values |
| element_one | identity element of the semiring |
| value_type | OID of the semiring value type |
| plus_function | semiring addition (aggregate) |
| times_function | semiring multiplication (aggregate) |
| monus_function | semiring monus (binary), or NULL |
| delta_function | δ-semiring operator, or NULL |
Evaluate aggregate provenance over a user-defined semiring (PL/pgSQL version)
Handles agg and semimod gates produced by GROUP BY queries.
| token | provenance token to evaluate |
| token2value | mapping table from tokens to semiring values |
| agg_function_final | finalization function for the aggregate |
| agg_function | aggregate combination function |
| semimod_function | semimodule scalar multiplication function |
| element_one | identity element of the semiring |
| value_type | OID of the semiring value type |
| plus_function | semiring addition |
| times_function | semiring multiplication |
| monus_function | semiring monus, or NULL |
| delta_function | δ-semiring operator, or NULL |
Evaluate provenance over a user-defined semiring (C version)
Optimized C implementation of provenance_evaluate. Infers the value type from element_one. Monus and delta functions are optional.
| token | provenance token to evaluate |
| token2value | mapping table from tokens to semiring values |
| element_one | identity element of the semiring |
| plus_function | semiring addition (aggregate) |
| times_function | semiring multiplication (aggregate) |
| monus_function | semiring monus, or NULL if not needed |
| delta_function | δ-semiring operator, or NULL if not needed |
Evaluate aggregate provenance over a user-defined semiring (C version)
Functions for examining the structure of provenance circuits, used by visualization and where-provenance features.
| TABLE update_provenance::circuit_subgraph | ( | UUID | root, |
| INT | max_depth = 8 ) |
BFS expansion of a provenance circuit, capped at max_depth.
Returns one row per (parent, child) edge in the BFS-bounded subgraph rooted at root, plus one row for the root with parent and child_pos NULL. Provenance circuits are DAGs, so a child gate may have several parents within the bound; each such edge is reported as a separate row, so callers must deduplicate on node if they need a one-row-per-node view.
depth is the node's BFS depth (its shortest distance from root), so for an edge (parent, child) it is always the case that parent.depth + 1 >= child.depth; equality holds only on shortest-path edges. A node at depth = max_depth is not expanded; callers can detect a partial expansion by comparing provsql.get_children length against the number of outgoing edges reported.
info1 and info2 are the INTEGER values stored on the gate by provsql.set_infos, formatted as TEXT; their meaning is gate-type-specific (see provsql.set_infos).
| root | root provenance token |
| max_depth | maximum BFS depth (default 8) |
| VOID update_provenance::identify_token | ( | UUID | token, |
| OUT REGCLASS | table_name, | ||
| OUT INTEGER | nb_columns ) |
Identify which table and how many columns a provenance token belongs to.
Searches all provenance-tracked tables for a row matching the given token and returns the table name and column count.
| token | provenance token to look up |
| table_name | (OUT) the table containing this token |
| nb_columns | (OUT) number of non-provenance columns in that table |
| TABLE update_provenance::resolve_input | ( | UUID | UUID | ) |
Resolve an input gate UUID back to its source row.
Searches every provenance-tracked relation for a row whose provsql column equals UUID and returns the relation's REGCLASS together with the row encoded as JSONB. Returns zero rows when UUID is not the provenance token of any tracked row, including when it identifies an internal gate (plus, times, ...) rather than an input.
Ordinarily exactly one row is returned, but if the same UUID happens to appear as a provsql value in several tracked tables, all matches are returned.
| UUID | token to resolve |
| jsonb update_provenance::rv_analytical_curves | ( | UUID | token, |
| INT | samples = 100, | ||
| UUID | prov = gate_one() ) |
Sample the closed-form PDF and CDF of a (possibly truncated) scalar distribution.
Returns {"pdf": [{x, p}, ...], "cdf": [{x, p}, ...]} with samples evenly-spaced points spanning the distribution's natural display range (intersected with the conditioning event's interval when prov is non-trivial). Used by ProvSQL Studio's Distribution profile panel to overlay the analytical curve on the empirical histogram from :sqlfunc:rv_histogram – the simplifier's analytical wins (e.g. c·Exp(λ) folding to Exp(λ/c)) become visible as a smooth curve riding over the MC-sampled bars.
Returns NULL when the root sub-circuit is not a closed-form shape (V1: only bare gate_rv of Normal / Uniform / Exponential / INTEGER-Erlang). The frontend reads NULL as "skip overlay" without erroring, so the caller can dispatch this in parallel with rv_histogram regardless of the underlying shape.
| token | Scalar gate token (random_variable's UUID). |
| samples | Number of (x, p) points; must be >= 2. |
| prov | Conditioning event (defaults to gate_one() = no conditioning). When non-trivial, the curves are over the truncated distribution. |
| jsonb update_provenance::rv_histogram | ( | UUID | token, |
| INT | bins = 30, | ||
| UUID | prov = gate_one() ) |
Empirical histogram of a scalar sub-circuit.
Returns a jsonb array of {bin_lo, bin_hi, count} objects covering the observed [min, max] range of bins equal-width samples from the sub-circuit rooted at token. Sample count is taken from provsql.rv_mc_samples; pinning provsql.monte_carlo_seed makes the result reproducible.
Accepted root gate types are the scalar ones: gate_value (Dirac at the constant, single bin), gate_rv (sampled from the leaf's distribution), and gate_arith (sampled by recursing through the arithmetic DAG, with shared gate_rv leaves correctly correlated within an iteration). Any other gate type raises.
| token | Root provenance token of a scalar sub-circuit. |
| bins | Number of equal-width histogram bins (default 30). |
| prov | Conditioning event (defaults to gate_one() = no conditioning). When non-trivial, the histogram is over the conditional distribution recovered by rejection sampling on the joint circuit with token. |
| SETOF float8 update_provenance::rv_sample | ( | UUID | token, |
| INTEGER | n, | ||
| UUID | prov = gate_one() ) |
Draw conditional Monte Carlo samples from a scalar gate.
Returns up to n samples of the scalar value at token; when prov is not the trivial gate_one() event, draws are accepted only on iterations where prov evaluates true (rejection sampling). Shared gate_rv leaves between token and prov are loaded into a single joint circuit so the indicator's draw and the value's draw share their per-iteration state.
| token | Scalar sub-circuit root. |
| n | Number of accepted samples to attempt. |
| prov | Conditioning event (defaults to gate_one() = no conditioning). |
Emits a NOTICE when the conditional acceptance rate yields fewer than n samples within the provsql.rv_mc_samples budget so the caller can choose to widen the budget.
| jsonb update_provenance::simplified_circuit_subgraph | ( | UUID | root, |
| INT | max_depth = 8 ) |
BFS subgraph of the IN-MEMORY simplified circuit rooted at root.
Same row shape as circuit_subgraph plus an inline extra column, but built from the GenericCircuit returned by getGenericCircuit – i.e. AFTER provsql.simplify_on_load passes (RangeCheck, ...) have rewritten any decidable gate_cmp into Bernoulli gate_input / gate_zero / gate_one leaves. Lets a renderer show the user what the evaluator actually sees, without mutating the persisted DAG.
Returns jsonb (an array of objects) rather than SETOF RECORD
to keep the C++ implementation free of SRF / FuncCallContext boilerplate; callers either consume the array directly or expand it via jsonb_array_elements.
| root | Root provenance token. |
| max_depth | Maximum BFS depth (default 8). |
| TABLE update_provenance::sub_circuit_for_where | ( | UUID | token | ) |
Return the sub-circuit for where-provenance computation.
Similar to sub_circuit_with_desc but resolves input gates to their source table and column count for where-provenance evaluation.
| SETOF GATE_WITH_DESC update_provenance::sub_circuit_with_desc | ( | UUID | token, |
| REGCLASS | token2desc ) |
Return the sub-circuit reachable from a token, with descriptions.
Recursively traverses the provenance circuit from the given token and returns all edges together with input gate descriptions from the mapping table.
| token | root provenance token |
| token2desc | mapping table providing descriptions for input gates |