 |
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
|
Functions for examining the structure of provenance circuits, used by visualization and where-provenance features. More...
Types | |
| TYPE | provsql.GATE_WITH_DESC |
| Row type for sub_circuit_with_desc results. More... | |
Functions | |
| SETOF GATE_WITH_DESC | provsql.sub_circuit_with_desc (UUID token, REGCLASS token2desc) |
| Return the sub-circuit reachable from a token, with descriptions. | |
| VOID | provsql.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 | provsql.sub_circuit_for_where (UUID token) |
| Return the sub-circuit for where-provenance computation. | |
| TABLE | provsql.circuit_subgraph (UUID root, INT max_depth=8) |
BFS expansion of a provenance circuit, capped at max_depth. | |
| jsonb | provsql.simplified_circuit_subgraph (UUID root, INT max_depth=8) |
BFS subgraph of the IN-MEMORY simplified circuit rooted at root. | |
| jsonb | provsql.rv_histogram (UUID token, INT bins=30, UUID prov=gate_one()) |
| Empirical histogram of a scalar sub-circuit. | |
| jsonb | provsql.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 | provsql.rv_sample (UUID token, INTEGER n, UUID prov=gate_one()) |
| Draw conditional Monte Carlo samples from a scalar gate. | |
| TABLE | provsql.resolve_input (UUID UUID) |
| Resolve an input gate UUID back to its source row. | |
Functions for examining the structure of provenance circuits, used by visualization and where-provenance features.
| TABLE provsql.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 provsql.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 provsql.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 provsql.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 provsql.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 provsql.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 provsql.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 provsql.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 provsql.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 |