 |
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
|
Custom type AGG_TOKEN for a provenance semimodule value, to be used in attributes that are computed as a result of aggregation. More...
Functions | |
| AGG_TOKEN | provsql.agg_token_in (CSTRING) |
| Input function for the AGG_TOKEN type (parses TEXT representation). | |
| CSTRING | provsql.agg_token_out (AGG_TOKEN) |
| Output function for the AGG_TOKEN type. | |
| TEXT | provsql.agg_token_cast (AGG_TOKEN) |
| Cast an AGG_TOKEN to its TEXT representation. | |
| UUID | provsql.agg_token_uuid (AGG_TOKEN aggtok) |
| Extract the UUID from an AGG_TOKEN (implicit cast to UUID). | |
| UUID | provsql.CAST(AGG_TOKEN AS UUID) (AGG_TOKEN) |
| Implicit PostgreSQL cast from AGG_TOKEN to UUID (delegates to agg_token_uuid()). | |
| BOOLEAN | provsql.agg_gate_value_missing (UUID token) |
Whether token carries a value but records none in the actual data: an aggregate over no row there, a value gate without a constant. | |
| TEXT | provsql.agg_gate_value_text (UUID token) |
| The TEXT a value-carrying gate records in the actual data, whatever type it is of. | |
| BOOLEAN | provsql.agg_guard_holds (UUID token) |
| Deterministic truth of a Boolean guard sub-circuit over aggregate comparisons, evaluated in the actual world (all input tuples present). | |
| NUMERIC | provsql.agg_gate_value (UUID token) |
| Deterministic (actual-world) scalar value of an aggregate-carrying gate. | |
| TEXT | provsql.agg_token_value_text (UUID token) |
Recover the "value (*)" display string for an aggregation gate. | |
| NUMERIC | provsql.agg_token_to_numeric (AGG_TOKEN) |
| Cast an AGG_TOKEN to NUMERIC (extracts the aggregate value, loses provenance). | |
| DOUBLE PRECISION | provsql.agg_token_to_float8 (AGG_TOKEN) |
| Cast an AGG_TOKEN to DOUBLE PRECISION (extracts the aggregate value, loses provenance). | |
| INTEGER | provsql.agg_token_to_int4 (AGG_TOKEN) |
| Cast an AGG_TOKEN to INTEGER (extracts the aggregate value, loses provenance). | |
| bigint | provsql.agg_token_to_int8 (AGG_TOKEN) |
| Cast an AGG_TOKEN to bigint (extracts the aggregate value, loses provenance). | |
| BOOLEAN | provsql.agg_token_to_bool (AGG_TOKEN) |
| Cast an AGG_TOKEN to BOOLEAN (extracts the aggregate value, loses provenance). | |
| TEXT | provsql.agg_token_to_text (AGG_TOKEN) |
| Cast an AGG_TOKEN to TEXT (extracts the aggregate value, loses provenance). | |
| CREATE | provsql.CAST (AGG_TOKEN AS NUMERIC) WITH FUNCTION agg_token_to_numeric(AGG_TOKEN) AS ASSIGNMENT |
| Assignment cast from AGG_TOKEN to NUMERIC (extracts the scalar value, dropping provenance). | |
| NUMERIC | provsql.agg_token_value (AGG_TOKEN) |
| Arithmetic on aggregates (AGG_TOKEN) Mirrors the random_variable arithmetic surface: the operators build a gate_arith over the operand provenance UUIDs (via provenance_arith, info1 = PROVSQL_ARITH_*), so the arithmetic is recorded symbolically in the circuit and can be resolved when a comparison (gate_cmp) over the result is evaluated. | |
| TEXT | provsql.agg_token_plain_text (AGG_TOKEN) |
| Value of an AGG_TOKEN as TEXT, NULL for a NULL value, without the provenance-loss warning the public cast emits: the sort key of an ORDER BY on an aggregate result (internal use). | |
| UUID[] | provsql.agg_token_explode_children (UUID token) |
The children of the aggregation gate token, one per contribution, to explode an aggregate result into rows (a join on it, explode_table). | |
| TEXT[] | provsql.agg_possible_values (ANYELEMENT input, BOOLEAN with_null=false) |
The values the aggregate result token takes over the possible worlds, as TEXT, to explode that result into one row per value: the value of an aggregate read as data (a GROUP BY key, a DISTINCT, an arm of a set operation). | |
| TEXT | provsql.agg_token_frozen_value (AGG_TOKEN) |
| Value of an AGG_TOKEN as TEXT, NULL for a NULL value, without the provenance-loss warning of the public casts: the value of an aggregate result read as a plain value where ProvSQL casts it (in a function, an operator, a comparison), which the planner reports once as evaluated as plain SQL (internal use). | |
| AGG_TOKEN | provsql.agg_token_make (UUID tok, NUMERIC val) |
| Bundle a provenance gate UUID with a running value into an AGG_TOKEN (inverse of the agg_token_uuid / agg_token_value accessors). | |
| UUID | provsql.agg_value_gate (NUMERIC v) |
| Lift a scalar NUMERIC constant into a gate_value leaf and return its UUID, so it can be a child of a gate_arith (the agg-side analogue of as_random for random_variable). | |
| oid | provsql.agg_token_value_type (UUID token) |
| Mint (or reuse) the gate_arith for an AGG_TOKEN arithmetic result and return the AGG_TOKEN carrying it. | |
| oid | provsql.agg_arith_result_type (INT op, UUID[] children) |
The type the operation op over children answers in, by SQL's own NUMERIC tower. | |
| AGG_TOKEN | provsql.agg_arith_make (INT op, UUID[] children, NUMERIC val) |
| AGG_TOKEN | provsql.agg_token_plus (AGG_TOKEN a, AGG_TOKEN b) |
| AGG_TOKEN <op> AGG_TOKEN | |
| AGG_TOKEN | provsql.agg_token_minus (AGG_TOKEN a, AGG_TOKEN b) |
| AGG_TOKEN - AGG_TOKEN (gate_arith MINUS). | |
| AGG_TOKEN | provsql.agg_token_times (AGG_TOKEN a, AGG_TOKEN b) |
| AGG_TOKEN * AGG_TOKEN (gate_arith TIMES). | |
| AGG_TOKEN | provsql.agg_token_div (AGG_TOKEN a, AGG_TOKEN b) |
| AGG_TOKEN / AGG_TOKEN (gate_arith DIV). | |
| AGG_TOKEN | provsql.agg_token_neg (AGG_TOKEN a) |
| Unary -AGG_TOKEN (gate_arith NEG). | |
| AGG_TOKEN | provsql.provsql_round (AGG_TOKEN a) |
| round / floor / ceil / abs of an AGG_TOKEN Named as the SQL functions they stand for, so that the rewriter's re-resolution of a call whose argument became an AGG_TOKEN finds them (try_swap_agg_func), exactly as the operators above are found. | |
| AGG_TOKEN | provsql.provsql_round (AGG_TOKEN a, INTEGER d) |
round(AGG_TOKEN, INTEGER): to d decimal digits. | |
| AGG_TOKEN | provsql.provsql_floor (AGG_TOKEN a) |
| floor(AGG_TOKEN) (gate_arith FLOOR). | |
| AGG_TOKEN | provsql.provsql_ceil (AGG_TOKEN a) |
| ceil(AGG_TOKEN) (gate_arith CEIL). | |
| AGG_TOKEN | provsql.provsql_ceiling (AGG_TOKEN a) |
| ceiling(AGG_TOKEN), the SQL synonym of ceil. | |
| AGG_TOKEN | provsql.provsql_abs (AGG_TOKEN a) |
| abs(AGG_TOKEN) (gate_arith ABS). | |
| AGG_TOKEN | provsql.agg_token_plus_numeric (AGG_TOKEN a, NUMERIC b) |
| AGG_TOKEN <op> NUMERIC | |
| AGG_TOKEN | provsql.agg_token_minus_numeric (AGG_TOKEN a, NUMERIC b) |
| AGG_TOKEN - NUMERIC. | |
| AGG_TOKEN | provsql.agg_token_times_numeric (AGG_TOKEN a, NUMERIC b) |
| AGG_TOKEN * NUMERIC. | |
| AGG_TOKEN | provsql.agg_token_div_numeric (AGG_TOKEN a, NUMERIC b) |
| AGG_TOKEN / NUMERIC. | |
| AGG_TOKEN | provsql.numeric_plus_agg_token (NUMERIC a, AGG_TOKEN b) |
| NUMERIC <op> AGG_TOKEN | |
| AGG_TOKEN | provsql.numeric_minus_agg_token (NUMERIC a, AGG_TOKEN b) |
| NUMERIC - AGG_TOKEN. | |
| AGG_TOKEN | provsql.numeric_times_agg_token (NUMERIC a, AGG_TOKEN b) |
| NUMERIC * AGG_TOKEN. | |
| AGG_TOKEN | provsql.numeric_div_agg_token (NUMERIC a, AGG_TOKEN b) |
| NUMERIC / AGG_TOKEN. | |
| AGG_TOKEN | provsql.agg_token_intdiv (AGG_TOKEN a, AGG_TOKEN b) |
| AGG_TOKEN / AGG_TOKEN, in INTEGER division (internal) | |
| AGG_TOKEN | provsql.agg_token_intdiv_numeric (AGG_TOKEN a, NUMERIC b) |
| AGG_TOKEN / NUMERIC, in INTEGER division (internal; see agg_token_intdiv). | |
| AGG_TOKEN | provsql.numeric_intdiv_agg_token (NUMERIC a, AGG_TOKEN b) |
| NUMERIC / AGG_TOKEN, in INTEGER division (internal; see agg_token_intdiv). | |
| BOOLEAN | provsql.agg_token_op_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| Operator declarations. | |
| NUMERIC | provsql.agg_transcendental (TEXT fn, AGG_TOKEN a) |
| ln(AGG_TOKEN) (gate_arith LN): the logarithm of the value the aggregate takes, in every world, rather than of the one it takes in the database as it is. | |
| AGG_TOKEN | provsql.provsql_ln (AGG_TOKEN a) |
| AGG_TOKEN | provsql.provsql_exp (AGG_TOKEN a) |
| exp(AGG_TOKEN) (gate_arith EXP). | |
| AGG_TOKEN | provsql.provsql_sqrt (AGG_TOKEN a) |
| sqrt(AGG_TOKEN): the square root is the power of one half (gate_arith POW, whose exponent is a value gate). | |
| AGG_TOKEN | provsql.agg_token_pow_numeric (AGG_TOKEN a, NUMERIC b) |
| AGG_TOKEN ^ NUMERIC (gate_arith POW, constant lifted to a value gate). | |
| BOOLEAN | provsql.agg_token_op_numeric (AGG_TOKEN left, NUMERIC right) |
| AGG_TOKEN | provsql.provsql_power (AGG_TOKEN a, NUMERIC b) |
power(AGG_TOKEN, NUMERIC) (gate_arith POW, the exponent lifted to a value gate): what power(sum(x), 2) is carried as, the way sum(x) ^ 2 already is. | |
| AGG_TOKEN | provsql.provsql_power (AGG_TOKEN a, DOUBLE PRECISION b) |
power(AGG_TOKEN, DOUBLE PRECISION): computed in DOUBLE PRECISION, as SQL computes it, and the exponent stored through its own TEXT, which keeps every digit the float has (see agg_transcendental). | |
| AGG_TOKEN | provsql.provsql_pow (AGG_TOKEN a, NUMERIC b) |
pow(AGG_TOKEN, NUMERIC): pow is power's other name. | |
| AGG_TOKEN | provsql.provsql_pow (AGG_TOKEN a, DOUBLE PRECISION b) |
| pow(AGG_TOKEN, DOUBLE PRECISION). | |
| BOOLEAN | provsql.numeric_op_agg_token (NUMERIC left, AGG_TOKEN right) |
| AGG_TOKEN | provsql.agg_token_cond (AGG_TOKEN a, UUID cond) |
Condition a discrete aggregate's distribution on an event: "SUM(x) | C". | |
| BOOLEAN | provsql.agg_token_op_uuid (AGG_TOKEN left, UUID right) |
| AGG_TOKEN | provsql.agg_token_cond_predicate (AGG_TOKEN a, BOOLEAN predicate) |
Placeholder for "SUM(x) | (predicate)" on an AGG_TOKEN. | |
| BOOLEAN | provsql.agg_token_op_boolean (AGG_TOKEN left, BOOLEAN right) |
| AGG_TOKEN | provsql.agg_conditioned_target (AGG_TOKEN a) |
Unpack the target of a conditioned AGG_TOKEN. | |
| BOOLEAN | provsql.agg_token_comp_numeric (AGG_TOKEN a, NUMERIC b) |
| Placeholder comparison of AGG_TOKEN with NUMERIC. | |
| BOOLEAN | provsql.numeric_comp_agg_token (NUMERIC a, AGG_TOKEN b) |
| Placeholder comparison of NUMERIC with AGG_TOKEN. | |
| BOOLEAN | provsql.agg_token_lt_numeric (AGG_TOKEN left, NUMERIC right) |
| SQL operator AGG_TOKEN < NUMERIC (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.numeric_lt_agg_token (NUMERIC left, AGG_TOKEN right) |
| SQL operator NUMERIC < AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_le_numeric (AGG_TOKEN left, NUMERIC right) |
| SQL operator AGG_TOKEN <= NUMERIC (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.numeric_le_agg_token (NUMERIC left, AGG_TOKEN right) |
| SQL operator NUMERIC <= AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_eq_numeric (AGG_TOKEN left, NUMERIC right) |
| SQL operator AGG_TOKEN = NUMERIC (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.numeric_eq_agg_token (NUMERIC left, AGG_TOKEN right) |
| SQL operator NUMERIC = AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_ne_numeric (AGG_TOKEN left, NUMERIC right) |
| SQL operator AGG_TOKEN <> NUMERIC (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.numeric_ne_agg_token (NUMERIC left, AGG_TOKEN right) |
| SQL operator NUMERIC <> AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_ge_numeric (AGG_TOKEN left, NUMERIC right) |
| SQL operator AGG_TOKEN >= NUMERIC (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.numeric_ge_agg_token (NUMERIC left, AGG_TOKEN right) |
| SQL operator NUMERIC >= AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_gt_numeric (AGG_TOKEN left, NUMERIC right) |
| SQL operator AGG_TOKEN > NUMERIC (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.numeric_gt_agg_token (NUMERIC left, AGG_TOKEN right) |
| SQL operator NUMERIC > AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_comp_agg_token (AGG_TOKEN a, AGG_TOKEN b) |
| Placeholder comparison of two AGG_TOKEN values (the diagonal). | |
| BOOLEAN | provsql.agg_token_lt_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| SQL operator AGG_TOKEN < AGG_TOKEN (placeholder rewritten at plan time). | |
| BOOLEAN | provsql.agg_token_le_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| SQL operator AGG_TOKEN <= AGG_TOKEN (placeholder rewritten at plan time). | |
| BOOLEAN | provsql.agg_token_gt_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| SQL operator AGG_TOKEN > AGG_TOKEN (placeholder rewritten at plan time). | |
| BOOLEAN | provsql.agg_token_ge_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| SQL operator AGG_TOKEN >= AGG_TOKEN (placeholder rewritten at plan time). | |
| BOOLEAN | provsql.agg_token_eq_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| SQL operator AGG_TOKEN = AGG_TOKEN (placeholder rewritten at plan time). | |
| BOOLEAN | provsql.agg_token_ne_agg_token (AGG_TOKEN left, AGG_TOKEN right) |
| SQL operator AGG_TOKEN <> AGG_TOKEN (placeholder rewritten at plan time). | |
| BOOLEAN | provsql.agg_token_comp_text (AGG_TOKEN a, TEXT b) |
| Placeholder comparison of AGG_TOKEN with TEXT. | |
| BOOLEAN | provsql.text_comp_agg_token (TEXT a, AGG_TOKEN b) |
| Placeholder comparison of TEXT with AGG_TOKEN. | |
| BOOLEAN | provsql.agg_token_eq_text (AGG_TOKEN left, TEXT right) |
| SQL operator AGG_TOKEN = TEXT (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.text_eq_agg_token (TEXT left, AGG_TOKEN right) |
| SQL operator TEXT = AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.agg_token_ne_text (AGG_TOKEN left, TEXT right) |
| SQL operator AGG_TOKEN <> TEXT (placeholder rewritten by ProvSQL at plan time). | |
| BOOLEAN | provsql.text_ne_agg_token (TEXT left, AGG_TOKEN right) |
| SQL operator TEXT <> AGG_TOKEN (placeholder rewritten by ProvSQL at plan time). | |
Custom type AGG_TOKEN for a provenance semimodule value, to be used in attributes that are computed as a result of aggregation.
As for provenance tokens, this is simply a UUID, but this UUID is displayed in a specific way (as the result of the aggregation followed by a "(*)") to help with readability.
The TEXT output is controlled by the provsql.aggtoken_text_as_uuid GUC. By default it is off and the cell renders as "value (*)". When set to on (typical for UI layers such as ProvSQL Studio), the cell renders as the underlying UUID instead, so the caller can click through to the provenance circuit; the value side is then recovered via provsql.agg_token_value_text(UUID).
| AGG_TOKEN provsql.agg_arith_make | ( | INT | op, |
| UUID[] | children, | ||
| NUMERIC | val ) |
| oid provsql.agg_arith_result_type | ( | INT | op, |
| UUID[] | children ) |
The type the operation op over children answers in, by SQL's own NUMERIC tower.
The gate computes in NUMERIC whatever the types are – it is the value that is stored, and a wider one loses nothing – but the value is READ in the type the query's expression has, and double precision prints 16 digits where NUMERIC prints every one it holds. Recording the type is what lets the reading round as SQL does; deriving it from the children makes it a function of the gate, so two statements building the same expression still agree on its token.
Two operations are not the tower: the INTEGER division SQL writes as "/" over integers (the INTDIV gate) answers in the INTEGER type, and round(v, d) exists only over NUMERIC, so it answers in NUMERIC.
| AGG_TOKEN provsql.agg_conditioned_target | ( | AGG_TOKEN | a | ) |
Unpack the target of a conditioned AGG_TOKEN.
For a "SUM(x) | C" whose provenance token is the two-child gate_conditioned [agg_target, condition] returns the AGG_TOKEN over agg_target (same running value); for any other AGG_TOKEN returns it unchanged. The conditioning event itself is recovered separately via rv_conditioned_prov on the token's UUID.
| NUMERIC provsql.agg_gate_value | ( | UUID | token | ) |
Deterministic (actual-world) scalar value of an aggregate-carrying gate.
Resolves the value an aggregate expression takes on the actual data – the value an AGG_TOKEN display cell carries: agg / arith gates RECORD it in extra (set by aggregate evaluation and agg_arith_make), a value gate carries its constant, a semimod wraps a value gate, a conditioned gate has its target's value, and a case gate selects the first branch whose guard holds in the actual world (per agg_guard_holds), else the default. Returns NULL when the gate is not aggregate-carrying or the value cannot be resolved (e.g. a non-NUMERIC aggregate).
| BOOLEAN provsql.agg_gate_value_missing | ( | UUID | token | ) |
Whether token carries a value but records none in the actual data: an aggregate over no row there, a value gate without a constant.
Told apart from a value this reading does not take – a TIMESTAMP, which agg_gate_value gives up on because it reads numbers, or a random variable, which has no value in the actual data at all – because the two call for opposite answers in agg_guard_holds: a comparison with a side that HAS no value there does not hold, while one whose value is simply not read leaves the truth undecided (internal use).
| TEXT provsql.agg_gate_value_text | ( | UUID | token | ) |
The TEXT a value-carrying gate records in the actual data, whatever type it is of.
agg_gate_value reads that TEXT as a number and gives up on anything else. A Boolean aggregate's value is one of those: "true" is no number, and yet = and <> compare it, which is what the guards of a "bool_or(flag)::INT" need. Descends the value-carrying gates as agg_gate_value does, and answers NULL for a gate that records no value of its own (internal use).
| BOOLEAN provsql.agg_guard_holds | ( | UUID | token | ) |
Deterministic truth of a Boolean guard sub-circuit over aggregate comparisons, evaluated in the actual world (all input tuples present).
Guards are the shapes having_Expr_to_provenance_cmp mints: cmp gates over aggregate-valued children (comparison-operator OID in info1), times / plus combinations (AND / OR, with negation pushed into the comparison operators), and the one / zero indicators of regular (aggregate-free) conditions. Uses Kleene three-valued logic: returns NULL on any other gate shape, or when an operand's deterministic value cannot be resolved.
| TEXT[] provsql.agg_possible_values | ( | ANYELEMENT | input, |
| BOOLEAN | with_null = false ) |
The values the aggregate result token takes over the possible worlds, as TEXT, to explode that result into one row per value: the value of an aggregate read as data (a GROUP BY key, a DISTINCT, an arm of a set operation).
The planner annotates the row of a value v with the comparison gate [token = v], so that the rows of one group are pairwise exclusive and exactly one of them is in each world where the group is.
A count() takes every number of its contributions, a min(), a max() and a choose() one of their contributed values. Any other aggregate is refused (SQLSTATE 0A000): the values of a sum() are its subset sums, those of a string_agg() one per ordering, and reading them off the contributions one by one would be wrong. A NULL contribution is refused as well: whether the result is NULL is then a value of its own, which a comparison cannot express (internal use).
| TEXT provsql.agg_token_cast | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to its TEXT representation.
| BOOLEAN provsql.agg_token_comp_agg_token | ( | AGG_TOKEN | a, |
| AGG_TOKEN | b ) |
Placeholder comparison of two AGG_TOKEN values (the diagonal).
Never actually called; lets the parser accept AGG_TOKEN <op> AGG_TOKEN (e.g. sum(x) > sum(y) on materialised tokens), which the ProvSQL rewriter lowers to a gate_cmp at plan time. Declaring this diagonal also disambiguates s = s2 (otherwise "operator is not unique", because both AGG_TOKEN -> UUID and AGG_TOKEN -> NUMERIC casts apply).
| BOOLEAN provsql.agg_token_comp_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
Placeholder comparison of AGG_TOKEN with NUMERIC.
This function is never actually called; it exists so the SQL parser accepts comparison operators between AGG_TOKEN and NUMERIC values. The ProvSQL query rewriter replaces these comparisons at plan time.
| BOOLEAN provsql.agg_token_comp_text | ( | AGG_TOKEN | a, |
| TEXT | b ) |
Placeholder comparison of AGG_TOKEN with TEXT.
This function is never actually called; it exists so the SQL parser accepts comparison operators between AGG_TOKEN and TEXT values. The ProvSQL query rewriter replaces these comparisons at plan time.
| AGG_TOKEN provsql.agg_token_cond | ( | AGG_TOKEN | a, |
| UUID | cond ) |
Condition a discrete aggregate's distribution on an event: "SUM(x) | C".
Mirrors random_variable_cond for the AGG_TOKEN carrier: returns a conditioned AGG_TOKEN that flows onward, its provenance token wrapped in the composable two-child gate_conditioned [agg_target, condition] while its running value is preserved. The moment / support dispatchers unpack it (agg_conditioned_target + rv_conditioned_prov) and route through the existing agg_raw_moment with the condition conjoined into the prov argument, so expected(SUM(x)|C) / variance(SUM(x)|C) report the conditional aggregate distribution. Nested conditioning folds.
| AGG_TOKEN provsql.agg_token_cond_predicate | ( | AGG_TOKEN | a, |
| BOOLEAN | predicate ) |
Placeholder for "SUM(x) | (predicate)" on an AGG_TOKEN.
Lets the conditioning event be a natural Boolean predicate (e.g. "SUM(x) | (SUM(x) > 5)") instead of a hand-built gate. Never executes: the planner converts the Boolean operand into a condition gate and emits agg_token_cond.
| AGG_TOKEN provsql.agg_token_div | ( | AGG_TOKEN | a, |
| AGG_TOKEN | b ) |
AGG_TOKEN / AGG_TOKEN (gate_arith DIV).
| AGG_TOKEN provsql.agg_token_div_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
AGG_TOKEN / NUMERIC.
| BOOLEAN provsql.agg_token_eq_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
SQL operator AGG_TOKEN = AGG_TOKEN (placeholder rewritten at plan time).
| BOOLEAN provsql.agg_token_eq_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
SQL operator AGG_TOKEN = NUMERIC (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.agg_token_eq_text | ( | AGG_TOKEN | left, |
| TEXT | right ) |
SQL operator AGG_TOKEN = TEXT (placeholder rewritten by ProvSQL at plan time).
| UUID[] provsql.agg_token_explode_children | ( | UUID | token | ) |
The children of the aggregation gate token, one per contribution, to explode an aggregate result into rows (a join on it, explode_table).
Only for choose(), whose value is one of its contributions; any other aggregate is refused, its value being none of them (count(*) contributes a 1 per row) (internal use).
| TEXT provsql.agg_token_frozen_value | ( | AGG_TOKEN | ) |
Value of an AGG_TOKEN as TEXT, NULL for a NULL value, without the provenance-loss warning of the public casts: the value of an aggregate result read as a plain value where ProvSQL casts it (in a function, an operator, a comparison), which the planner reports once as evaluated as plain SQL (internal use).
| BOOLEAN provsql.agg_token_ge_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
SQL operator AGG_TOKEN >= AGG_TOKEN (placeholder rewritten at plan time).
| BOOLEAN provsql.agg_token_ge_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
SQL operator AGG_TOKEN >= NUMERIC (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.agg_token_gt_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
SQL operator AGG_TOKEN > AGG_TOKEN (placeholder rewritten at plan time).
| BOOLEAN provsql.agg_token_gt_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
SQL operator AGG_TOKEN > NUMERIC (placeholder rewritten by ProvSQL at plan time).
| AGG_TOKEN provsql.agg_token_in | ( | CSTRING | ) |
Input function for the AGG_TOKEN type (parses TEXT representation).
| AGG_TOKEN provsql.agg_token_intdiv | ( | AGG_TOKEN | a, |
| AGG_TOKEN | b ) |
AGG_TOKEN / AGG_TOKEN, in INTEGER division (internal)
The rewriter calls it instead of agg_token_div when both operands were integers in the query, as for count(*) / count(x): SQL divides them with truncation toward zero, and the displayed value does too. The gate is an arith gate of its own operator (11, PROVSQL_ARITH_INTDIV), which the evaluators truncate in every world.
| AGG_TOKEN provsql.agg_token_intdiv_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
AGG_TOKEN / NUMERIC, in INTEGER division (internal; see agg_token_intdiv).
| BOOLEAN provsql.agg_token_le_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
SQL operator AGG_TOKEN <= AGG_TOKEN (placeholder rewritten at plan time).
| BOOLEAN provsql.agg_token_le_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
SQL operator AGG_TOKEN <= NUMERIC (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.agg_token_lt_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
SQL operator AGG_TOKEN < AGG_TOKEN (placeholder rewritten at plan time).
| BOOLEAN provsql.agg_token_lt_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
SQL operator AGG_TOKEN < NUMERIC (placeholder rewritten by ProvSQL at plan time).
| AGG_TOKEN provsql.agg_token_make | ( | UUID | tok, |
| NUMERIC | val ) |
Bundle a provenance gate UUID with a running value into an AGG_TOKEN (inverse of the agg_token_uuid / agg_token_value accessors).
| AGG_TOKEN provsql.agg_token_minus | ( | AGG_TOKEN | a, |
| AGG_TOKEN | b ) |
AGG_TOKEN - AGG_TOKEN (gate_arith MINUS).
| AGG_TOKEN provsql.agg_token_minus_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
AGG_TOKEN - NUMERIC.
| BOOLEAN provsql.agg_token_ne_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
SQL operator AGG_TOKEN <> AGG_TOKEN (placeholder rewritten at plan time).
| BOOLEAN provsql.agg_token_ne_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
SQL operator AGG_TOKEN <> NUMERIC (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.agg_token_ne_text | ( | AGG_TOKEN | left, |
| TEXT | right ) |
SQL operator AGG_TOKEN <> TEXT (placeholder rewritten by ProvSQL at plan time).
| AGG_TOKEN provsql.agg_token_neg | ( | AGG_TOKEN | a | ) |
Unary -AGG_TOKEN (gate_arith NEG).
| BOOLEAN provsql.agg_token_op_agg_token | ( | AGG_TOKEN | left, |
| AGG_TOKEN | right ) |
Operator declarations.
| BOOLEAN provsql.agg_token_op_boolean | ( | AGG_TOKEN | left, |
| BOOLEAN | right ) |
| BOOLEAN provsql.agg_token_op_numeric | ( | AGG_TOKEN | left, |
| NUMERIC | right ) |
| BOOLEAN provsql.agg_token_op_uuid | ( | AGG_TOKEN | left, |
| UUID | right ) |
| CSTRING provsql.agg_token_out | ( | AGG_TOKEN | ) |
Output function for the AGG_TOKEN type.
Default: produces the human-friendly "value (*)" form, where value is the running aggregate state.
When the provsql.aggtoken_text_as_uuid GUC is on, returns the underlying provenance UUID instead. UI layers (notably ProvSQL Studio) flip this on per session so aggregate cells expose the circuit root UUID for click-through; the "value (*)" display string is recovered via provsql.agg_token_value_text(UUID).
Marked STABLE rather than IMMUTABLE because the chosen output shape now depends on a GUC that the same session can flip at runtime.
| TEXT provsql.agg_token_plain_text | ( | AGG_TOKEN | ) |
Value of an AGG_TOKEN as TEXT, NULL for a NULL value, without the provenance-loss warning the public cast emits: the sort key of an ORDER BY on an aggregate result (internal use).
| AGG_TOKEN provsql.agg_token_plus | ( | AGG_TOKEN | a, |
| AGG_TOKEN | b ) |
| AGG_TOKEN provsql.agg_token_plus_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
AGG_TOKEN <op> NUMERIC
AGG_TOKEN + NUMERIC (gate_arith PLUS, constant lifted to a value gate).
| AGG_TOKEN provsql.agg_token_pow_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
AGG_TOKEN ^ NUMERIC (gate_arith POW, constant lifted to a value gate).
| AGG_TOKEN provsql.agg_token_times | ( | AGG_TOKEN | a, |
| AGG_TOKEN | b ) |
AGG_TOKEN * AGG_TOKEN (gate_arith TIMES).
| AGG_TOKEN provsql.agg_token_times_numeric | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
AGG_TOKEN * NUMERIC.
| BOOLEAN provsql.agg_token_to_bool | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to BOOLEAN (extracts the aggregate value, loses provenance).
| DOUBLE PRECISION provsql.agg_token_to_float8 | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to DOUBLE PRECISION (extracts the aggregate value, loses provenance).
| INTEGER provsql.agg_token_to_int4 | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to INTEGER (extracts the aggregate value, loses provenance).
| bigint provsql.agg_token_to_int8 | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to bigint (extracts the aggregate value, loses provenance).
| NUMERIC provsql.agg_token_to_numeric | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to NUMERIC (extracts the aggregate value, loses provenance).
| TEXT provsql.agg_token_to_text | ( | AGG_TOKEN | ) |
Cast an AGG_TOKEN to TEXT (extracts the aggregate value, loses provenance).
| UUID provsql.agg_token_uuid | ( | AGG_TOKEN | aggtok | ) |
Extract the UUID from an AGG_TOKEN (implicit cast to UUID).
| NUMERIC provsql.agg_token_value | ( | AGG_TOKEN | ) |
Arithmetic on aggregates (AGG_TOKEN) Mirrors the random_variable arithmetic surface: the operators build a gate_arith over the operand provenance UUIDs (via provenance_arith, info1 = PROVSQL_ARITH_*), so the arithmetic is recorded symbolically in the circuit and can be resolved when a comparison (gate_cmp) over the result is evaluated.
Unlike random_variable (a bare UUID), an AGG_TOKEN also carries a running scalar value, so each operator additionally computes the resulting value and bundles it back with the new gate.
Running value of an AGG_TOKEN as NUMERIC, without the provenance-loss warning the public cast emits (internal use).
| TEXT provsql.agg_token_value_text | ( | UUID | token | ) |
Recover the "value (*)" display string for an aggregation gate.
Companion helper to the provsql.aggtoken_text_as_uuid GUC. With the GUC on, an AGG_TOKEN cell prints as the underlying provenance UUID, which is convenient for tooling that wants to click through to the circuit but loses the human-readable aggregate value. This function takes such a UUID and returns the original "value (*)" string by reading the gate's extra (set by aggregate evaluation for agg gates, and by agg_arith_make for the arith gates that AGG_TOKEN arithmetic mints); for the other aggregate-carrying gates (case, conditioned, semimod, value) the value is resolved through the circuit by agg_gate_value. Returns NULL if token does not resolve to an aggregate-carrying gate.
| token | UUID of an agg gate (typically obtained from an AGG_TOKEN cell when aggtoken_text_as_uuid is on, or via a manual UUID cast otherwise). |
| oid provsql.agg_token_value_type | ( | UUID | token | ) |
Mint (or reuse) the gate_arith for an AGG_TOKEN arithmetic result and return the AGG_TOKEN carrying it.
Also records the computed scalar in the gate's extra – exactly what aggregate evaluation does for agg gates – so agg_token_value_text can recover the "value (*)" display from the bare UUID (as ProvSQL Studio does for result cells under provsql.aggtoken_text_as_uuid). The gate UUID is deterministic in (op, children), so re-recording the (identical) value is idempotent.
The SQL type of the value an AGG_TOKEN carries.
An agg gate holds the aggregate's own result type in info2, next to the scalar flag in its top bit; an arith gate holds the result type of the operation it stands for, put there by agg_arith_make. Every other aggregate-carrying gate holds a value the rewriting computed in NUMERIC, which is what it answers for them.
| NUMERIC provsql.agg_transcendental | ( | TEXT | fn, |
| AGG_TOKEN | a ) |
ln(AGG_TOKEN) (gate_arith LN): the logarithm of the value the aggregate takes, in every world, rather than of the one it takes in the database as it is.
fn of the value of a, computed in the type the value is read in.
The gates compute in NUMERIC, which loses nothing for the four basic operations: computing exactly and reading the result as double precision gives what floating-point arithmetic gives, since IEEE requires each of them to be correctly rounded. sqrt, ln and exp are not like that – NUMERIC computes them to a fixed scale, so sqrt(3) comes out to fifteen decimals and the value read back differs from SQL's in its last digit – so where the expression is a float, they are computed as SQL computes them, in that type, and the NUMERIC the gate stores is that value.
| UUID provsql.agg_value_gate | ( | NUMERIC | v | ) |
Lift a scalar NUMERIC constant into a gate_value leaf and return its UUID, so it can be a child of a gate_arith (the agg-side analogue of as_random for random_variable).
| CREATE provsql.CAST | ( | AGG_TOKEN AS | NUMERIC | ) |
Assignment cast from AGG_TOKEN to NUMERIC (extracts the scalar value, dropping provenance).
Assignment cast from AGG_TOKEN to BOOLEAN (bool_and, bool_or, every).
Assignment cast from AGG_TOKEN to TEXT (extracts value, not UUID).
Assignment cast from AGG_TOKEN to bigint.
Assignment cast from AGG_TOKEN to INTEGER.
Assignment cast from AGG_TOKEN to DOUBLE PRECISION.
ASSIGNMENT, not IMPLICIT: provenance- preserving arithmetic on aggregates is provided by the native AGG_TOKEN operators below, so an implicit NUMERIC coercion would only silently steal s + 1 away from them (and reroute it differently depending on whether provsql is in search_path). Write s::NUMERIC to opt into the lossy scalar.
| UUID provsql.CAST(AGG_TOKEN AS UUID) | ( | AGG_TOKEN | ) |
Implicit PostgreSQL cast from AGG_TOKEN to UUID (delegates to agg_token_uuid()).
| BOOLEAN provsql.numeric_comp_agg_token | ( | NUMERIC | a, |
| AGG_TOKEN | b ) |
Placeholder comparison of NUMERIC with AGG_TOKEN.
Symmetric to agg_token_comp_numeric; never actually called. The ProvSQL query rewriter replaces these comparisons at plan time.
| AGG_TOKEN provsql.numeric_div_agg_token | ( | NUMERIC | a, |
| AGG_TOKEN | b ) |
NUMERIC / AGG_TOKEN.
| BOOLEAN provsql.numeric_eq_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
SQL operator NUMERIC = AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.numeric_ge_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
SQL operator NUMERIC >= AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.numeric_gt_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
SQL operator NUMERIC > AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| AGG_TOKEN provsql.numeric_intdiv_agg_token | ( | NUMERIC | a, |
| AGG_TOKEN | b ) |
NUMERIC / AGG_TOKEN, in INTEGER division (internal; see agg_token_intdiv).
| BOOLEAN provsql.numeric_le_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
SQL operator NUMERIC <= AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.numeric_lt_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
SQL operator NUMERIC < AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| AGG_TOKEN provsql.numeric_minus_agg_token | ( | NUMERIC | a, |
| AGG_TOKEN | b ) |
NUMERIC - AGG_TOKEN.
| BOOLEAN provsql.numeric_ne_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
SQL operator NUMERIC <> AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.numeric_op_agg_token | ( | NUMERIC | left, |
| AGG_TOKEN | right ) |
| AGG_TOKEN provsql.numeric_plus_agg_token | ( | NUMERIC | a, |
| AGG_TOKEN | b ) |
| AGG_TOKEN provsql.numeric_times_agg_token | ( | NUMERIC | a, |
| AGG_TOKEN | b ) |
NUMERIC * AGG_TOKEN.
| AGG_TOKEN provsql.provsql_abs | ( | AGG_TOKEN | a | ) |
abs(AGG_TOKEN) (gate_arith ABS).
| AGG_TOKEN provsql.provsql_ceil | ( | AGG_TOKEN | a | ) |
ceil(AGG_TOKEN) (gate_arith CEIL).
| AGG_TOKEN provsql.provsql_ceiling | ( | AGG_TOKEN | a | ) |
ceiling(AGG_TOKEN), the SQL synonym of ceil.
| AGG_TOKEN provsql.provsql_exp | ( | AGG_TOKEN | a | ) |
exp(AGG_TOKEN) (gate_arith EXP).
| AGG_TOKEN provsql.provsql_floor | ( | AGG_TOKEN | a | ) |
floor(AGG_TOKEN) (gate_arith FLOOR).
| AGG_TOKEN provsql.provsql_ln | ( | AGG_TOKEN | a | ) |
| AGG_TOKEN provsql.provsql_pow | ( | AGG_TOKEN | a, |
| DOUBLE PRECISION | b ) |
pow(AGG_TOKEN, DOUBLE PRECISION).
| AGG_TOKEN provsql.provsql_pow | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
pow(AGG_TOKEN, NUMERIC): pow is power's other name.
| AGG_TOKEN provsql.provsql_power | ( | AGG_TOKEN | a, |
| DOUBLE PRECISION | b ) |
power(AGG_TOKEN, DOUBLE PRECISION): computed in DOUBLE PRECISION, as SQL computes it, and the exponent stored through its own TEXT, which keeps every digit the float has (see agg_transcendental).
| AGG_TOKEN provsql.provsql_power | ( | AGG_TOKEN | a, |
| NUMERIC | b ) |
power(AGG_TOKEN, NUMERIC) (gate_arith POW, the exponent lifted to a value gate): what power(sum(x), 2) is carried as, the way sum(x) ^ 2 already is.
| AGG_TOKEN provsql.provsql_round | ( | AGG_TOKEN | a | ) |
round / floor / ceil / abs of an AGG_TOKEN Named as the SQL functions they stand for, so that the rewriter's re-resolution of a call whose argument became an AGG_TOKEN finds them (try_swap_agg_func), exactly as the operators above are found.
They compute in NUMERIC, as the operators do, and the gate records the operation so the value is read per possible world; the moment evaluators sample them, since rounding does not commute with expectation.
round(AGG_TOKEN) (gate_arith ROUND).
| AGG_TOKEN provsql.provsql_round | ( | AGG_TOKEN | a, |
| INTEGER | d ) |
round(AGG_TOKEN, INTEGER): to d decimal digits.
| AGG_TOKEN provsql.provsql_sqrt | ( | AGG_TOKEN | a | ) |
sqrt(AGG_TOKEN): the square root is the power of one half (gate_arith POW, whose exponent is a value gate).
| BOOLEAN provsql.text_comp_agg_token | ( | TEXT | a, |
| AGG_TOKEN | b ) |
Placeholder comparison of TEXT with AGG_TOKEN.
Symmetric to agg_token_comp_text; never actually called. The ProvSQL query rewriter replaces these comparisons at plan time.
| BOOLEAN provsql.text_eq_agg_token | ( | TEXT | left, |
| AGG_TOKEN | right ) |
SQL operator TEXT = AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).
| BOOLEAN provsql.text_ne_agg_token | ( | TEXT | left, |
| AGG_TOKEN | right ) |
SQL operator TEXT <> AGG_TOKEN (placeholder rewritten by ProvSQL at plan time).