 |
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
|
Low-level functions for creating and querying provenance circuit gates. More...
Functions | |
| VOID | provsql.create_gate (UUID token, PROVENANCE_GATE type, UUID[] children=NULL) |
| Create a new gate in the provenance circuit. | |
| PROVENANCE_GATE | provsql.get_gate_type (UUID token) |
| Return the gate type of a provenance token. | |
| UUID[] | provsql.get_children (UUID token) |
| Return the children of a provenance gate. | |
| VOID | provsql.set_prob (UUID token, DOUBLE PRECISION p) |
| Set the probability of an input gate. | |
| DOUBLE PRECISION | provsql.get_prob (UUID token) |
| Get the probability associated with an input gate. | |
| VOID | provsql.set_infos (UUID token, INT info1, INT info2=NULL) |
| Set additional INTEGER values on provenance circuit gate. | |
| RECORD | provsql.get_infos (UUID token, OUT INT info1, OUT INT info2) |
| Get the INTEGER info values associated with a circuit gate. | |
| UUID | provsql.provenance_assume (UUID token, TEXT assumption) |
Wrap token in a fresh gate_assumed carrying assumption as its label, and return the wrapper's UUID. | |
| UUID | provsql.assume_boolean (UUID token) |
Wrap token in a Boolean-assumption marker (compatibility name; see provenance_assume). | |
| UUID | provsql.annotate (UUID token, TEXT extra) |
Wrap token in a fresh transparent gate_annotation carrying extra, and return the wrapper's UUID. | |
| UUID | provsql.strip_annotations (UUID token) |
Peel every transparent gate_annotation wrapper off token, returning the first non-annotation gate underneath. | |
| UUID | provsql.cond (UUID target, UUID evidence) |
| Condition a provenance token (a Boolean event) on another. | |
| BOOLEAN | provsql.UUID_op_UUID (UUID left, UUID right) |
Binary "target | evidence". | |
| UUID | provsql.cond_predicate (UUID target, BOOLEAN predicate) |
Placeholder for "X | (predicate)" on a UUID event. | |
| BOOLEAN | provsql.UUID_op_boolean (UUID left, BOOLEAN right) |
| UUID | provsql.predicate_cond_predicate (BOOLEAN target, BOOLEAN evidence) |
Placeholder for "(predicate) | (predicate)" on two events. | |
| BOOLEAN | provsql.boolean_op_boolean (BOOLEAN left, BOOLEAN right) |
| UUID | provsql.regular_indicator (BOOLEAN cond) |
| Deterministic indicator gate for an ordinary (regular) comparison. | |
| UUID | provsql.given (UUID evidence) |
Whole-tuple output conditioning directive: "given(evidence)". | |
| UUID | provsql.given (BOOLEAN predicate) |
Prefix unary given, "| evidence". | |
| UUID | provsql.provenance_not (UUID event) |
Event negation: "! event" / "provenance_not(event)". | |
| TEXT | provsql.inversion_free_key (TEXT root, TEXT sec, INT factor) |
Prefix unary ! | |
| VOID | provsql.set_extra (UUID token, TEXT data) |
| Set extra TEXT information on provenance circuit gate. | |
| TEXT | provsql.get_extra (UUID token) |
| Get the TEXT-encoded extra data associated with a circuit gate. | |
| BIGINT | provsql.get_nb_gates () |
| Return the total number of materialized gates in the provenance circuit. | |
Low-level functions for creating and querying provenance circuit gates.
| UUID provsql.annotate | ( | UUID | token, |
| TEXT | extra ) |
Wrap token in a fresh transparent gate_annotation carrying extra, and return the wrapper's UUID.
Unlike every other gate, the annotation wrapper's UUID folds in extra (not just the child): uuid_generate_v5 over concat('annotation', token, extra). This is deliberate – two annotations over the same child with different extra must be distinct gates (e.g. the same input tuple carrying different per-occurrence order keys, or two queries attaching different certificates to a shared root). The wrapper is transparent (identity) for EVERY evaluator; extra is inert metadata read only by the code that placed it. No-op (returns NULL) on a NULL input.
| UUID provsql.assume_boolean | ( | UUID | token | ) |
Wrap token in a Boolean-assumption marker (compatibility name; see provenance_assume).
| BOOLEAN provsql.boolean_op_boolean | ( | BOOLEAN | left, |
| BOOLEAN | right ) |
| UUID provsql.cond | ( | UUID | target, |
| UUID | evidence ) |
Condition a provenance token (a Boolean event) on another.
Builds the terminal gate_conditioned that the measure evaluators read as "P(target ∧ evidence) / P(evidence)". This is the backing function of the binary | operator ("target | evidence", value-level conditioning of the UUID carrier).
The gate stores three children [target, evidence, joint] with joint = times(target, evidence); evaluation is then the plain ratio P(joint)/P(evidence), and content-addressing makes a base tuple shared by target and evidence the same input gate in both circuits, so the conditional is exact and correlation-aware.
Conventions:
evidence NULL or gate_one() returns target unchanged ("P(X|true)=P(X)").target with no provenance defaults to the certain event 1, so "1 | c" is the well-defined certain-row posterior."(X | A) | B = X | (A ∧ B)" – the gate never nests, it stays one level deep with the evidence accumulated by times.The result is TERMINAL: a conditioned token may not become a child of a plus / times / monus / agg gate (those constructors refuse it); the only operation it admits is more conditioning.
| UUID provsql.cond_predicate | ( | UUID | target, |
| BOOLEAN | predicate ) |
Placeholder for "X | (predicate)" on a UUID event.
Lets the conditioning event be written as a natural Boolean combination of random_variable / aggregate comparisons (e.g. "event | (sensor > 3)") instead of a hand-built gate. Never executes: the ProvSQL planner hook converts the Boolean operand into a condition gate and emits cond.
| VOID provsql.create_gate | ( | UUID | token, |
| PROVENANCE_GATE | type, | ||
| UUID[] | children = NULL ) |
Create a new gate in the provenance circuit.
| token | UUID identifying the new gate |
| type | gate type (see PROVENANCE_GATE) |
| children | optional array of child gate UUIDs |
| UUID[] provsql.get_children | ( | UUID | token | ) |
Return the children of a provenance gate.
| TEXT provsql.get_extra | ( | UUID | token | ) |
Get the TEXT-encoded extra data associated with a circuit gate.
| PROVENANCE_GATE provsql.get_gate_type | ( | UUID | token | ) |
Return the gate type of a provenance token.
Returns 'input' for any token not yet materialized in the circuit, since input is the default semantics of an unmaterialized provenance token.
| RECORD provsql.get_infos | ( | UUID | token, |
| OUT INT | info1, | ||
| OUT INT | info2 ) |
Get the INTEGER info values associated with a circuit gate.
| BIGINT provsql.get_nb_gates | ( | ) |
Return the total number of materialized gates in the provenance circuit.
Input gates for provenance-tracked table rows are created lazily on first reference; rows that have never appeared in a query result are not counted.
| DOUBLE PRECISION provsql.get_prob | ( | UUID | token | ) |
Get the probability associated with an input gate.
| UUID provsql.given | ( | BOOLEAN | predicate | ) |
Prefix unary | : alias for given, "| evidence".
Disambiguated from the binary | by the absence of a left operand ("a, | c" parses "| c" as the prefix form). PostgreSQL keeps prefix operators on every supported version (postfix operators were removed in PG14), so "| c" is safe across the CI matrix.
Conditioning-evidence from a predicate: "given(predicate)" (also the prefix "| (predicate)").
Two uses of the same marker:
given ("SELECT a, given(sensor > 3)");and_agg – "and_agg(given(normal(mu,1) = x))" turns each row's observation into likelihood-weighting evidence.Never executes: the planner converts the Boolean operand into a condition gate and emits given(gate); a point-equality "Y = d" on a bare random-variable leaf then becomes an observation (see given(UUID) / evidence_as_observation).
| UUID provsql.given | ( | UUID | evidence | ) |
Whole-tuple output conditioning directive: "given(evidence)".
Written as a term in the select list, given(c) conditions the OUTPUT provenance of the current query's rows on c:
The query rewriter recognises the marker, STRIPS it from the visible projection, and wraps each output row's provenance expression in cond(row_provenance, c) – deriving a new conditioned relation, never mutating any stored provenance. c is evaluated per output row and may correlate with the row's columns, so each tuple is conditioned on its own evidence. When the rewriter is inactive the call is a harmless identity (it returns evidence as an ordinary column).
When executed rather than stripped – i.e. nested inside an expression, the idiom "and_agg(given(Y = d))" that folds one observation per row into a latent-variable evidence circuit -- a point-equality "Y = d" on a bare random-variable leaf is turned into likelihood-weighting evidence (evidence_as_observation); any other evidence passes through unchanged.
| TEXT provsql.inversion_free_key | ( | TEXT | root, |
| TEXT | sec, | ||
| INT | factor ) |
Prefix unary !
: alias for provenance_not, "! event".
Prefix operators are kept on every supported PostgreSQL version (postfix operators were removed in PG14), and core PG defines no prefix ! on UUID, so "! event" is safe across the CI matrix.
Build a per-input order-key string for the inversion-free path.
Emitted by the planner per certified atom: K-prefixed, length-prefixed "K<factor> <octet_length(root)>:<root><octet_length(sec)>:<sec>", parsed back at evaluation by safe_cert_key_parse. root / sec are the tuple's root- and secondary-class column values (TEXT-cast by the caller); the byte-length prefixes keep the values unambiguous for any column type, including TEXT containing spaces, colons or digits. factor is the atom's factor id (or -1 for the shared self-join guard). IMMUTABLE so the planner can fold it and the marker dedups by content-addressing.
| UUID provsql.predicate_cond_predicate | ( | BOOLEAN | target, |
| BOOLEAN | evidence ) |
Placeholder for "(predicate) | (predicate)" on two events.
Conditions one comparison event on another when both operands are written as comparisons rather than pre-built tokens (e.g. "probability((x >= 2000) | (x >= 1000))"): an random_variable / AGG_TOKEN comparison is statically BOOLEAN-typed, so neither the "UUID | UUID" (cond) nor the "UUID | BOOLEAN" (cond_predicate) operator resolves. Never executes: the ProvSQL planner hook lowers each Boolean operand to its event gate and emits cond(target, evidence), so the result carries the correlation-aware Pr(A ∧ B) / Pr(B). Returns UUID, so "A | B" is a first-class event token in every position (a probability(UUID) argument, a projected column, a further "|").
| UUID provsql.provenance_assume | ( | UUID | token, |
| TEXT | assumption ) |
Wrap token in a fresh gate_assumed carrying assumption as its label, and return the wrapper's UUID.
Public primitive callable from any rewrite or driver that needs to flag a sub-circuit as sound only under an evaluation assumption:
'BOOLEAN' – the sub-circuit only preserves the Boolean function of the lineage (e.g. the safe-query rewrite collapses derivation multiplicities); transparent for semirings admitting a homomorphism from Boolean functions.'absorptive' – the sub-circuit was truncated at the absorptive value fixpoint (cyclic recursive query); transparent for absorptive semirings (probability, BOOLEAN, min-plus over nonnegative costs...), fatal for the rest (counting, why-provenance).Incompatible evaluators raise a CircuitException. Always kept as an explicit node in PROV-XML export.
The wrapper UUID is content-derived via uuid_generate_v5 on the assumption and the child, so identical children always wrap to the same outer UUID per assumption. No-op (returns NULL) on a NULL input.
| UUID provsql.provenance_not | ( | UUID | event | ) |
Event negation: "! event" / "provenance_not(event)".
The complement of a Boolean provenance event: "!x" holds in exactly the worlds where x does not. It is sugar for "monus(one, x)" -- an ordinary m-semiring expression (Boolean NOT, probability "1 - P(x)"), NOT a measure-only marker – so it composes like any monus, and a conditioned / terminal token is refused as its child (so "!(x | c)" errors, as conditioning cannot be buried under further algebra).
The motivating use is conditioning on the NON-occurrence of an arbitrary violation query W (a denial constraint), where W itself is built with ordinary idioms and needs no hand-rolled gates:
Named provenance_not, after the "provenance_times / _plus / _monus" family; the prefix ! operator is the ergonomic form (SQL's reserved NOT keyword cannot serve as a function name).
| UUID provsql.regular_indicator | ( | BOOLEAN | cond | ) |
Deterministic indicator gate for an ordinary (regular) comparison.
The predicate-provenance of an ordinary comparison (both sides of regular type, e.g. "region = 'north'") is the deterministic indicator "χ(cond)": gate_one() when the comparison holds on the row, gate_zero() otherwise (Definition in the HAVING-provenance semantics). The planner emits this for a regular comparison appearing inside a MIXED conditioning predicate (one that also has a random_variable / aggregate comparison); cond is evaluated per row, so the indicator is the row's own truth value, combined by ⊗ / ⊕ with the probabilistic gates.
| VOID provsql.set_extra | ( | UUID | token, |
| TEXT | data ) |
Set extra TEXT information on provenance circuit gate.
This function sets TEXT-encoded data associated to a circuit gate, used in different ways by different gate types:
| token | UUID of the circuit gate |
| data | TEXT-encoded information |
| VOID provsql.set_infos | ( | UUID | token, |
| INT | info1, | ||
| INT | info2 = NULL ) |
Set additional INTEGER values on provenance circuit gate.
This function sets two INTEGER values associated to a circuit gate, used in different ways by different gate types:
| token | UUID of the circuit gate |
| info1 | first INTEGER value |
| info2 | second INTEGER value |
| VOID provsql.set_prob | ( | UUID | token, |
| DOUBLE PRECISION | p ) |
Set the probability of an input gate.
| token | UUID of the input gate |
| p | probability value in [0,1] |
| UUID provsql.strip_annotations | ( | UUID | token | ) |
Peel every transparent gate_annotation wrapper off token, returning the first non-annotation gate underneath.
The dual of annotate, for consumers keyed to gate identity rather than gate value: a provenance mapping matches input-gate UUIDs, and the reachability edge classifier matches token shapes, so both must see the wrapped gate, not the wrapper (e.g. the inversion-free certificate / order marker the planner attaches to a certified query's row roots). Identity on a token with no annotation wrapper; NULL on NULL.
| BOOLEAN provsql.UUID_op_boolean | ( | UUID | left, |
| BOOLEAN | right ) |
| BOOLEAN provsql.UUID_op_UUID | ( | UUID | left, |
| UUID | right ) |
Binary | : value-level conditioning, "target | evidence".
Carrier-parametric in its left operand; the UUID form builds the terminal gate_conditioned via cond. Does not collide with core PostgreSQL's INTEGER bitwise | (different argument types).