 |
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 building and evaluating aggregate (GROUP BY) provenance, including the δ-semiring operator and semimodule multiplication. More...
Functions | |
| UUID | provsql.provenance_delta (UUID token) |
| Create a δ-semiring gate wrapping a provenance token. | |
| AGG_TOKEN | provsql.provenance_aggregate (INTEGER aggfnoid, INTEGER aggtype, ANYELEMENT val, UUID[] tokens, BOOLEAN is_scalar=false) |
| Build an aggregate provenance gate from grouped tokens. | |
| UUID | provsql.provenance_semimod (ANYELEMENT val, UUID token) |
| Create a semimodule scalar multiplication gate. | |
| UUID | provsql.provenance_semimod_nested (AGG_TOKEN val, UUID token) |
| The contribution of an aggregate result to an aggregate of another kind over it (internal). | |
| UUID[] | provsql.provenance_semimod_flat (AGG_TOKEN val, UUID token) |
| The contributions of an aggregate result to an aggregate of the same kind over it (internal). | |
| VOID | provsql.provenance_contributions_cat (UUID[]) |
Concatenation of the arrays of contributions of provenance_semimod_flat (internal). | |
| UUID | provsql.provenance_semimod_nullable (ANYELEMENT val, UUID token) |
| Semimodule gate for an aggregate that sees its NULL inputs. | |
| AGG_TOKEN | provsql.row_number_as_rank (AGG_TOKEN rank, bigint row_number) |
| The rank of a row standing for its row number (internal). | |
| UUID[] | provsql.window_distinct_tokens (anyarray vals, UUID[] tokens) |
| The contributions of the distinct values of a window frame (internal). | |
| ANYELEMENT | provsql.plain (ANYELEMENT value) |
| Mark a part of a query to be evaluated as plain SQL, not tracked. | |
Functions for building and evaluating aggregate (GROUP BY) provenance, including the δ-semiring operator and semimodule multiplication.
| ANYELEMENT provsql.plain | ( | ANYELEMENT | value | ) |
Mark a part of a query to be evaluated as plain SQL, not tracked.
Over provenance-tracked relations, ORDER BY … LIMIT k keeps, in each possible world, the rows that fewer than k present rows precede: every row that may be among them is output, annotated with that condition. LIMIT plain(k) (FETCH FIRST plain(k) ROWS, OFFSET plain(m)) instead truncates the result as computed on the actual data, and each row kept carries its provenance in the full result. The function returns its argument.
| value | the marked value |
| AGG_TOKEN provsql.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. The gate's address hashes everything it records, result type and value included: what is recorded is written once, and two aggregations that differ only there (a polymorphic aggregate over two types with the same texts, a floating-point sum rounded differently by two plans) must be two gates.
| 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 |
Implemented in C (gate_builders.c), with the declared cost of the PL/pgSQL function it was, so that plans stay the same.
| VOID provsql.provenance_contributions_cat | ( | UUID[] | ) |
Concatenation of the arrays of contributions of provenance_semimod_flat (internal).
| UUID provsql.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.
Implemented in C (gate_builders.c), with the declared cost of the PL/pgSQL function it was, so that plans stay the same.
| UUID provsql.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 |
Implemented in C (gate_builders.c), with the declared cost of the PL/pgSQL function it was, so that plans stay the same.
| UUID[] provsql.provenance_semimod_flat | ( | AGG_TOKEN | val, |
| UUID | token ) |
The contributions of an aggregate result to an aggregate of the same kind over it (internal).
For a row of token token whose value val is the result of sum / count / max / min over a group, aggregated again by sum / max / min: the contributions semimod(v_i, token ⊗ k_i) of the group's own contributions semimod(v_i, k_i), so that sum(sum(x)) is sum(x) over the rows of the groups – semimodule scalar multiplication, in every semiring. Collected by provenance_contributions_cat.
| UUID provsql.provenance_semimod_nested | ( | AGG_TOKEN | val, |
| UUID | token ) |
The contribution of an aggregate result to an aggregate of another kind over it (internal).
For a row of token token whose value val is the result of an aggregate of another kind than the one aggregating it (an avg of a count, a max of a sum, an aggregate of an arithmetic expression over aggregates): semimod(g, token), where g is the inner aggregate's own gate. Its value is one per possible world, not one value of the database, so the evaluators that read a value per world resolve it and the closed forms decline it.
| UUID provsql.provenance_semimod_nullable | ( | ANYELEMENT | val, |
| UUID | token ) |
Semimodule gate for an aggregate that sees its NULL inputs.
Variant of provenance_semimod() used by the query rewriter for array_agg, json_agg and the like, whose result lists every input, NULLs included: a NULL value still yields a semimod gate, over the constant value gate gate_null().
| val | the scalar value, possibly NULL |
| token | the provenance token to multiply |
Implemented in C (gate_builders.c), with the declared cost of the PL/pgSQL function it was, so that plans stay the same.
| AGG_TOKEN provsql.row_number_as_rank | ( | AGG_TOKEN | rank, |
| bigint | row_number ) |
The rank of a row standing for its row number (internal).
Called by the query rewriter for row_number() OVER (…) over provenance-tracked relations, which is tracked as rank(): the two are equal when the ORDER BY of the window leaves no ties. Returns rank, with a warning, once per statement, when row_number differs from it.
| rank | the AGG_TOKEN of the rank of the row |
| row_number | the row number PostgreSQL gave the row |
| UUID[] provsql.window_distinct_tokens | ( | anyarray | vals, |
| UUID[] | tokens ) |
The contributions of the distinct values of a window frame (internal).
Called by the query rewriter for dense_rank() OVER (…) over provenance-tracked relations, which counts the distinct ordering values before the current row: one provenance_semimod(1, ⊕ tokens) per distinct value of vals, the ⊕ of the tokens of the rows that have it, which is present when one of them is. Values are compared with the equality of their type, as the peers of a window are, NULLs being equal.
| vals | the ordering values of the rows of the frame |
| tokens | the provenance tokens of these rows, in the same order |