ProvSQL SQL API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
provsql.sql
Go to the documentation of this file.
1/**
2 * @file
3 * @brief ProvSQL PL/pgSQL extension code
4 *
5 * This file contains the PL/pgSQL code of the ProvSQL extension. This
6 * extension requires the standard UUID-ossp extension.
7 */
8
9/**
10 * @brief <tt>provsql</tt> schema
11 *
12 * All types and functions introduced by ProvSQL are defined in the
13 * provsql schema, requiring prefixing them by <tt>provsql.</tt> or
14 * using PostgreSQL's <tt>search_path</tt> variable with a command such
15 * as \code{.sql}SET search_path TO public, provsql;\endcode
16 */
17CREATE SCHEMA provsql;
18
19SET search_path TO provsql;
20
21/**
22 * @brief Provenance circuit gate types
23 *
24 * Each gate in the provenance circuit has a type that determines
25 * its semantics during semiring evaluation.
26 */
27CREATE TYPE PROVENANCE_GATE AS
28 ENUM(
29 'input', -- Input (variable) gate of the circuit
30 'plus', -- Semiring plus
31 'times', -- Semiring times
32 'monus', -- M-Semiring monus
33 'project', -- Project gate (for where provenance)
34 'zero', -- Semiring zero
35 'one', -- Semiring one
36 'eq', -- Equijoin gate (for where provenance)
37 'agg', -- Aggregation operator (for aggregate provenance)
38 'semimod', -- Semimodule scalar multiplication (for aggregate provenance)
39 'cmp', -- Comparison of aggregate values (HAVING-clause provenance)
40 'delta', -- δ-semiring operator (see Amsterdamer, Deutch, Tannen, PODS 2011)
41 'value', -- Scalar value (for aggregate provenance)
42 'mulinput',-- Multivalued input (for Boolean provenance)
43 'update', -- Update operation
44 'rv', -- Continuous random-variable leaf
45 'arith', -- n-ary arithmetic gate over scalar-valued children
46 'mixture', -- Probabilistic mixture of two scalar RV roots with a Bernoulli weight
47 'assumed', -- Structural assumption marker over a single child: the
48 -- wrapped sub-circuit was computed under the
49 -- assumption named by the gate's extra label --
50 -- 'BOOLEAN' (e.g. the safe-query rewrite; the
51 -- default when the label is absent) or
52 -- 'absorptive' (the bounded-treewidth
53 -- reachability route). Transparent for
54 -- evaluation semirings satisfying the assumption,
55 -- fatal error for the rest, rendered as an
56 -- explicit element in PROV-XML export.
57 'annotation', -- Transparent single-child wrapper carrying a
58 -- query-level annotation string in @c extra
59 -- (e.g. the inversion-free tractability
60 -- certificate / per-input order key). Identity
61 -- for EVERY evaluator; its UUID folds in @c extra
62 -- so distinct annotations over the same child are
63 -- distinct gates.
64 'conditioned', -- Conditioning marker: two children
65 -- [target, evidence]. Evaluated only in the
66 -- measure interpretation: probability_evaluate
67 -- returns P(target ∧ evidence) / P(evidence); the
68 -- RV / AGG_TOKEN evaluators return the restricted
69 -- distribution. For the UUID carrier it is a
70 -- TERMINAL gate (never a child of a semiring gate);
71 -- nested conditioning folds into a conjunction of
72 -- evidence. Refused by every general sr_* semiring
73 -- (normalization is not a semiring operation).
74 'mobius', -- Signed Möbius combination over child islands: one
75 -- INTEGER coefficient per child in @c extra (the
76 -- gate_arith precedent), probability_evaluate returns
77 -- Σ_i coeff_i · P(child_i). The one new primitive of
78 -- the safe-UCQ Möbius-inversion route, evaluated only
79 -- in the measure interpretation; refused by every
80 -- general sr_* semiring (a signed combination is not a
81 -- semiring operation).
82 'case', -- N-ary guarded selection over scalar (RV) children:
83 -- wires [guard_1, value_1, ..., guard_k, value_k,
84 -- default], first-match semantics (the value of the
85 -- first guard event that holds, else the default).
86 -- Backs a CASE expression over random variables (and
87 -- abs / clamp / ReLU as sugar). RV/measure-carrier;
88 -- refused by every general sr_* semiring.
89 'observe', -- Latent-variable observation (likelihood-weighting
90 -- evidence): one wire -> an observed bare gate_rv
91 -- leaf, the datum in extra. Contributes a
92 -- continuous density factor (the leaf's pdf at the
93 -- datum) rather than a Boolean truth value,
94 -- composing into an evidence circuit by gate_times
95 -- exactly like a conditioning event. Evaluated only
96 -- by the importance-sampling weight walk; refused by
97 -- every Boolean / semiring evaluator.
98 'fixvar', -- Unknown of an equation system: a leaf standing for
99 -- the solution of one equation, meaningful only
100 -- inside the 'fixsystem' gate that lists it.
101 'fixsystem', -- Linear equation system x_i = f_i(x) of a recursive
102 -- query, one equation per derived tuple: wires
103 -- [x_1, ..., x_n, f_1, ..., f_n]. Read through
104 -- 'fixpoint'.
105 'fixpoint' -- Component of the least solution of an equation
106 -- system: one wire to a 'fixsystem', the 1-based
107 -- index in info1; solved per semiring at evaluation.
108 );
109
110/** @defgroup gate_manipulation Circuit gate manipulation
111 * Low-level functions for creating and querying provenance circuit gates.
112 * @{
113 */
114
115/**
116 * @brief Create a new gate in the provenance circuit
117 *
118 * @param token UUID identifying the new gate
119 * @param type gate type (see PROVENANCE_GATE)
120 * @param children optional array of child gate UUIDs
121 */
122CREATE OR REPLACE FUNCTION create_gate(
123 token UUID,
124 type PROVENANCE_GATE,
125 children UUID[] DEFAULT NULL)
126 RETURNS VOID AS
127 'provsql','create_gate' LANGUAGE C PARALLEL SAFE;
128
129/**
130 * @brief Create a gate together with what it records (internal)
131 *
132 * One unanswered message to the worker, where create_gate() followed by
133 * set_infos() or set_extra() would wait for the worker's verdict on each.
134 * For the callers that know what the gate records when they create it: a
135 * gate whose address hashes its infos and TEXT, or a fresh token nobody else
136 * can have written to. Infos and TEXT are still written once: should
137 * something else be recorded at that address, the first value stays and the
138 * worker logs it.
139 *
140 * @param token UUID identifying the new gate
141 * @param type gate type (see PROVENANCE_GATE)
142 * @param children optional array of child gate UUIDs
143 * The infos are used in different ways by different gate types: for
144 * mulinput, info1 is the value of the multivalued variable; for eq, info1
145 * and info2 are the attribute positions equated; for agg, info1 is the OID
146 * of the aggregate function and info2 that of its result type; for cmp,
147 * info1 is the OID of the comparison operator; for arith, info1 is the
148 * operator. The TEXT is used in different ways too: for project,
149 * a TEXT-encoded array of two-element arrays mapping input attributes to
150 * output attributes; for value and agg, the TEXT-encoded scalar value; for
151 * rv, the distribution family and its parameters; for assumed, the
152 * assumption kind; for annotation, inert metadata read only by the code
153 * that placed it.
154 *
155 * @param info1 first info, or NULL
156 * @param info2 second info, or NULL
157 * @param extra TEXT of the gate, or NULL
158 */
159CREATE OR REPLACE FUNCTION create_gate(
160 token UUID,
161 type PROVENANCE_GATE,
162 children UUID[],
163 info1 INT,
164 info2 INT,
165 extra TEXT)
166 RETURNS VOID AS
167 'provsql','create_gate' LANGUAGE C PARALLEL SAFE;
168/**
169 * @brief Return the gate type of a provenance token
170 *
171 * Returns @c 'input' for any token not yet materialized in the circuit,
172 * since input is the default semantics of an unmaterialized provenance token.
173 */
174CREATE OR REPLACE FUNCTION get_gate_type(
175 token UUID)
176 RETURNS PROVENANCE_GATE AS
177 'provsql','get_gate_type' LANGUAGE C IMMUTABLE PARALLEL SAFE;
178/** @brief Return the children of a provenance gate */
179CREATE OR REPLACE FUNCTION get_children(
180 token UUID)
181 RETURNS UUID[] AS
182 'provsql','get_children' LANGUAGE C IMMUTABLE PARALLEL SAFE;
183/**
184 * @brief Write the probability of an input gate, once
185 *
186 * A probability is a fact appended to the circuit, like the gate it
187 * belongs to: it can be written on a gate that has none, written again
188 * with the identical value (so setup scripts and notebook cells stay
189 * re-runnable), and is otherwise refused. A write made by a
190 * transaction that rolls back is cleared, leaving the circuit as the
191 * transaction found it.
192 *
193 * To give a tuple a *different* probability, mint a fresh input gate
194 * with @c provsql.replace_input and store it in the row's @c provsql
195 * column. The base table's token column is the place of truth, the
196 * same rule the data-modification triggers already follow, and the
197 * circuit keeps the old gate and everything derived from it.
198 *
199 * @param token UUID of the input gate
200 * @param p probability value in [0,1]
201 */
202CREATE OR REPLACE FUNCTION set_prob(
203 token UUID, p DOUBLE PRECISION)
204 RETURNS VOID AS
205 'provsql','set_prob' LANGUAGE C PARALLEL RESTRICTED;
206
207/**
208 * @brief Report whether a probability has been written on a gate
209 *
210 * @c get_prob returns the value an evaluation would use, so it answers
211 * 1 both for a gate written as certain and for one nobody has given a
212 * probability. This distinguishes them, which is what a client needs
213 * in order to offer "set" on the one and "replace" on the other.
214 */
215CREATE OR REPLACE FUNCTION probability_is_set(token UUID)
216 RETURNS BOOLEAN AS
217 'provsql','probability_is_set' LANGUAGE C STABLE PARALLEL SAFE;
218
219/**
220 * @brief Declare a just-minted leaf gate a replacement for a tracked row
221 *
222 * Internal. @c provsql.replace_input and @c provsql.replace_block call
223 * this so the @c UPDATE that stores the new token does not look, to
224 * @c provenance_guard, like a user pasting in an arbitrary UUID -- which
225 * would flip the table to @c OPAQUE. The declaration lasts for the
226 * transaction.
227 */
228CREATE OR REPLACE FUNCTION note_fresh_leaf(token UUID)
229 RETURNS VOID AS
230 'provsql','note_fresh_leaf' LANGUAGE C;
231
232/** @brief Whether @c token was minted as a replacement leaf by this
233 * transaction (see @c note_fresh_leaf). Internal. */
234CREATE OR REPLACE FUNCTION is_fresh_leaf(token UUID)
235 RETURNS BOOLEAN AS
236 'provsql','is_fresh_leaf' LANGUAGE C VOLATILE;
237
238/**
239 * @brief Mint a replacement input gate carrying a different probability
240 *
241 * Probabilities are written once, so a tuple's probability is changed
242 * the way its data is: by rewriting the row. This mints a fresh input
243 * gate with probability @c p and returns it, for the row's @c provsql
244 * column to carry:
245 *
246 * @code
247 * UPDATE s SET provsql = provsql.replace_input(provsql, 0.3) WHERE id = 42;
248 * @endcode
250 * The update is an ordinary heap write, so it has MVCC isolation, WAL,
251 * replication and @c pg_dump behind it, and the new gate and its
252 * probability roll back with it. The old gate and everything derived
253 * from it stay as they were: re-running a query over the base table
254 * builds new derived gates over the new token and so sees the new
255 * probability, while a table materialised earlier keeps the old tokens
256 * and the old probability -- a derived table reflects the base tables
257 * as they were when it was built, the same rule a @c DELETE under
258 * @c provsql.update_provenance already follows.
259 *
260 * @param old the token being replaced; must name an input gate
261 * @param p the new probability, in [0,1]
262 */
263CREATE OR REPLACE FUNCTION replace_input(old UUID, p DOUBLE PRECISION)
264 RETURNS UUID AS
265$$
266DECLARE
267 t UUID;
268 tp provsql.PROVENANCE_GATE;
269BEGIN
270 IF old IS NULL OR p IS NULL THEN
271 RAISE EXCEPTION 'replace_input: neither argument may be NULL';
272 END IF;
273 tp := provsql.get_gate_type(old);
274 IF tp = 'mulinput' THEN
275 RAISE EXCEPTION 'replace_input: % belongs to a repair_key block', old
276 USING HINT = 'A block''s values share one key gate and their masses '
277 'are meaningful together, so they are replaced together: '
278 'use provsql.replace_block().';
279 ELSIF tp = 'update' THEN
280 RAISE EXCEPTION 'replace_input: % is an update gate', old
281 USING HINT = 'Use provsql.replace_update() to give a recorded data '
282 'modification a different probability.';
283 ELSIF tp <> 'input' THEN
284 RAISE EXCEPTION 'replace_input: % is a gate of type %, not an input', old, tp
285 USING HINT = 'Only a leaf carries a probability of its own; a derived '
286 'gate''s is computed from its leaves.';
287 END IF;
288 t := public.uuid_generate_v4();
289 PERFORM provsql.create_gate(t, 'input');
290 PERFORM provsql.set_prob(t, p);
291 PERFORM provsql.note_fresh_leaf(t);
292 RETURN t;
293END
294$$ LANGUAGE plpgsql;
295
296/**
297 * @brief Replace a tracked row's input gate, rewriting the row
298 *
299 * The procedural form of @c replace_input: it mints the new gate and
300 * issues the @c UPDATE itself, which is what a client with only the
301 * token in hand (the Studio inspector, say) needs.
302 *
303 * @param _tbl the tracked table holding the row
304 * @param old the token the row carries
305 * @param p the new probability, in [0,1]
306 * @return the token the row now carries
307 */
308CREATE OR REPLACE FUNCTION replace_input(
309 _tbl REGCLASS, old UUID, p DOUBLE PRECISION)
310 RETURNS UUID AS
311$$
312DECLARE
313 t UUID;
314 n INT;
315BEGIN
316 t := provsql.replace_input(old, p);
317 EXECUTE format('UPDATE %s SET provsql = $1 WHERE provsql = $2', _tbl)
318 USING t, old;
319 GET DIAGNOSTICS n = ROW_COUNT;
320 IF n = 0 THEN
321 RAISE EXCEPTION 'replace_input: no row of % carries the token %', _tbl, old;
322 END IF;
323 RETURN t;
324END
325$$ LANGUAGE plpgsql;
326
327/**
328 * @brief Give a @c repair_key block a new set of probabilities
329 *
330 * The block-level counterpart of @c replace_input. A block's values
331 * share one key gate and their masses are meaningful together, so they
332 * are replaced together: this mints a new key gate and one new
333 * @c mulinput per row of the block, writes @c probs to them in the
334 * block's own order (the @c within_group index @c repair_key recorded),
335 * and rewrites the block's rows in @p _tbl to carry the new tokens.
336 *
337 * @param _tbl the tracked table holding the block's rows
338 * @param old_key the block's key gate -- the shared child of its rows'
339 * @c mulinput tokens, as reported by
340 * @c "get_children(provsql)[1]"
341 * @param probs one probability per row of the block, in block order;
342 * @c NULL leaves them unwritten, so the block evaluates
343 * at the uniform weight again
344 */
345CREATE OR REPLACE FUNCTION replace_block(
346 _tbl REGCLASS, old_key UUID, probs DOUBLE PRECISION[] DEFAULT NULL)
347 RETURNS VOID AS
348$$
349DECLARE
350 r RECORD;
351 n INT;
352 i INT := 0;
353 new_key UUID;
354 new_tok UUID;
355 was_active TEXT;
356BEGIN
357 IF provsql.get_gate_type(old_key) <> 'input' THEN
358 RAISE EXCEPTION 'replace_block: % is not a block key gate', old_key;
359 END IF;
360
361 -- The rewriter has no business in the bookkeeping below: the tokens of
362 -- _tbl are what this function is here to rewrite, not provenance to
363 -- carry into a temporary table. Restored before returning; a failure
364 -- aborts the transaction, which restores it too.
365 was_active := coalesce(current_setting('provsql.active', true), 'on');
366 PERFORM set_config('provsql.active', 'off', true);
367
368 EXECUTE format(
369 'CREATE TEMP TABLE provsql_replace_block_tmp ON COMMIT DROP AS
370 SELECT t.provsql AS old_token,
371 NULL::UUID AS new_token,
372 (provsql.get_infos(t.provsql)).info1 AS ord
373 FROM %s t
374 WHERE provsql.get_gate_type(t.provsql) = ''mulinput''
375 AND (provsql.get_children(t.provsql))[1] = %L', _tbl, old_key);
376
377 SELECT count(*) INTO n FROM provsql_replace_block_tmp;
378 IF n = 0 THEN
379 RAISE EXCEPTION 'replace_block: no row of % belongs to block %', _tbl, old_key;
380 END IF;
381 IF probs IS NOT NULL AND array_length(probs, 1) <> n THEN
382 RAISE EXCEPTION 'replace_block: block % has % rows but % probabilities were given',
383 old_key, n, array_length(probs, 1);
384 END IF;
385
386 new_key := public.uuid_generate_v4();
387 PERFORM provsql.create_gate(new_key, 'input');
388
389 FOR r IN SELECT old_token, ord FROM provsql_replace_block_tmp ORDER BY ord LOOP
390 i := i + 1;
391 new_tok := public.uuid_generate_v4();
392 PERFORM provsql.create_gate(new_tok, 'mulinput', ARRAY[new_key], r.ord, n, NULL);
393 IF probs IS NOT NULL THEN
394 PERFORM provsql.set_prob(new_tok, probs[i]);
395 END IF;
396 PERFORM provsql.note_fresh_leaf(new_tok);
397 UPDATE provsql_replace_block_tmp SET new_token = new_tok
398 WHERE old_token = r.old_token;
399 END LOOP;
400
401 EXECUTE format(
402 'UPDATE %s t SET provsql = b.new_token
403 FROM provsql_replace_block_tmp b WHERE t.provsql = b.old_token', _tbl);
405 DROP TABLE provsql_replace_block_tmp;
406 PERFORM set_config('provsql.active', was_active, true);
407END
408$$ LANGUAGE plpgsql;
409/** @brief Get the probability associated with an input gate */
410CREATE OR REPLACE FUNCTION get_prob(
411 token UUID)
412 RETURNS DOUBLE PRECISION AS
413 'provsql','get_prob' LANGUAGE C STABLE PARALLEL SAFE;
414
415
416/** @brief Get the INTEGER info values associated with a circuit gate */
417CREATE OR REPLACE FUNCTION get_infos(
418 token UUID, OUT info1 INT, OUT info2 INT)
419 RETURNS RECORD AS
420 'provsql','get_infos' LANGUAGE C STABLE PARALLEL SAFE;
421
422/**
423 * @brief Wrap @p token in a fresh @c gate_assumed carrying @p assumption
424 * as its label, and return the wrapper's UUID.
425 *
426 * Public primitive callable from any rewrite or driver that needs to
427 * flag a sub-circuit as sound only under an evaluation assumption:
428 *
429 * - @c 'BOOLEAN' -- the sub-circuit only preserves the Boolean function
430 * of the lineage (e.g. the safe-query rewrite collapses derivation
431 * multiplicities); transparent for semirings admitting a homomorphism
432 * from Boolean functions.
433 * - @c 'absorptive' -- the sub-circuit was truncated at the absorptive
434 * value fixpoint (cyclic recursive query); transparent for absorptive
435 * semirings (probability, BOOLEAN, min-plus over nonnegative
436 * costs...), fatal for the rest (counting, why-provenance).
437 *
438 * Incompatible evaluators raise a @c CircuitException. Always kept as
439 * an explicit node in PROV-XML export.
440 *
441 * The wrapper UUID is content-derived via @c uuid_generate_v5 on the
442 * assumption and the child, so identical children always wrap to the
443 * same outer UUID per assumption. No-op (returns NULL) on a NULL
444 * input.
445 *
446 * Implemented in C (<tt>gate_builders.c</tt>): the gate is created together
447 * with what it records, in one unanswered message.
448 */
449CREATE OR REPLACE FUNCTION provenance_assume(token UUID, assumption TEXT)
450 RETURNS UUID AS
451 'provsql','provenance_assume' LANGUAGE C COST 100 PARALLEL SAFE;
453/**
454 * @brief Wrap @p token in a Boolean-assumption marker (compatibility
455 * name; see @c provenance_assume).
456 *
457 * This is the entry point the safe-query (read-once) rewriter calls on
458 * every per-row root it produces, so the wrapper additionally carries
459 * @c PROVSQL_ROUTE_SQ_REWRITE in @c info1: the assumption kind alone does
460 * not identify the route (@c provenance_assume(t, 'BOOLEAN') is public),
461 * and the probability dispatcher reads the tag back to report
462 * @c sq-rewrite rather than the generic @c independent. Build an untagged
463 * Boolean-assumption wrapper with @c provenance_assume directly.
464 *
465 * Implemented in C (<tt>gate_builders.c</tt>): the gate is created together
466 * with what it records, in one unanswered message.
467 */
468CREATE OR REPLACE FUNCTION assume_boolean(token UUID) RETURNS UUID AS
469 'provsql','assume_boolean' LANGUAGE C COST 100 PARALLEL SAFE;
470
471/**
472 * @brief Wrap @p token in a fresh transparent @c gate_annotation carrying
473 * @p extra, and return the wrapper's UUID.
474 *
475 * Unlike every other gate, the annotation wrapper's UUID folds in @p extra
476 * (not just the child): @c uuid_generate_v5 over @c concat('annotation',
477 * token, extra). This is deliberate -- two annotations over the same child
478 * with different @p extra must be distinct gates (e.g. the same input tuple
479 * carrying different per-occurrence order keys, or two queries attaching
480 * different certificates to a shared root). The wrapper is transparent
481 * (identity) for EVERY evaluator; @p extra is inert metadata read only by the
482 * code that placed it. No-op (returns NULL) on a NULL input.
483 *
484 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
485 * function it replaces, so that plans stay the same.
486 */
487CREATE OR REPLACE FUNCTION annotate(token UUID, extra TEXT) RETURNS UUID AS
488 'provsql','annotate' LANGUAGE C COST 100 PARALLEL SAFE;
489
490/**
491 * @brief Peel every transparent @c gate_annotation wrapper off @p token,
492 * returning the first non-annotation gate underneath.
493 *
494 * The dual of @c annotate, for consumers keyed to gate *identity* rather
495 * than gate value: a provenance mapping matches input-gate UUIDs, and the
496 * reachability edge classifier matches token shapes, so both must see the
497 * wrapped gate, not the wrapper (e.g. the inversion-free certificate /
498 * order marker the planner attaches to a certified query's row roots).
499 * Identity on a token with no annotation wrapper; NULL on NULL.
500 */
501CREATE OR REPLACE FUNCTION strip_annotations(token UUID) RETURNS UUID AS
502$$
503WITH RECURSIVE peel(g) AS (
504 SELECT token
505 UNION ALL
506 SELECT (provsql.get_children(p.g))[1] FROM peel p
507 WHERE provsql.get_gate_type(p.g) = 'annotation'
508)
509SELECT g FROM peel WHERE provsql.get_gate_type(g) <> 'annotation' LIMIT 1;
510$$ LANGUAGE sql STABLE PARALLEL SAFE;
511
512/**
513 * @brief Condition a provenance token (a Boolean event) on another.
514 *
515 * Builds the terminal @c gate_conditioned that the measure evaluators read
516 * as @c "P(target ∧ evidence) / P(evidence)". This is the backing function
517 * of the binary @c | operator (@c "target | evidence", value-level
518 * conditioning of the UUID carrier).
520 * The gate stores three children @c [target, evidence, joint] with
521 * @c joint @c = @c times(target, @c evidence); evaluation is then the plain
522 * ratio @c P(joint)/P(evidence), and content-addressing makes a base tuple
523 * shared by @p target and @p evidence the same input gate in both circuits,
524 * so the conditional is exact and correlation-aware.
525 *
526 * Conventions:
527 * - Conditioning on a certain or absent event is a no-op: @c evidence NULL
528 * or @c gate_one() returns @p target unchanged (@c "P(X|true)=P(X)").
529 * - A @p target with no provenance defaults to the certain event 1, so
530 * @c "1 | c" is the well-defined certain-row posterior.
531 * - Nested conditioning folds (sequential Bayesian update):
532 * @c "(X | A) | B = X | (A ∧ B)" -- the gate never nests, it stays one
533 * level deep with the evidence accumulated by @c times.
534 *
535 * The result is TERMINAL: a conditioned token may not become a child of a
536 * @c plus / @c times / @c monus / @c agg gate (those constructors refuse
537 * it); the only operation it admits is more conditioning.
538 */
539CREATE OR REPLACE FUNCTION cond(target UUID, evidence UUID) RETURNS UUID AS
540$$
541DECLARE
542 tgt UUID;
543 ev UUID;
544 jnt UUID;
545 result UUID;
546 ch UUID[];
547BEGIN
548 -- P(X | true) = P(X): conditioning on a certain / absent event is inert.
549 IF evidence IS NULL OR evidence = gate_one() THEN
550 RETURN target;
551 END IF;
552
553 -- A row with no provenance defaults to the certain event 1.
554 tgt := coalesce(target, gate_one());
555
556 IF get_gate_type(tgt) = 'conditioned' THEN
557 -- Sequential update (X | A) | B = X | (A ∧ B): fold B into both the
558 -- evidence and the joint of the inner gate so the result stays a single
559 -- gate_conditioned over the ORIGINAL target.
560 ch := get_children(tgt);
561 tgt := ch[1]; -- original target X
562 ev := provenance_times(ch[2], evidence); -- A ∧ B
563 jnt := provenance_times(ch[3], evidence); -- (X ∧ A) ∧ B
564 ELSE
565 ev := evidence;
566 jnt := provenance_times(tgt, evidence); -- X ∧ C
567 END IF;
568
569 result := public.uuid_generate_v5(uuid_ns_provsql(),
570 concat('conditioned', tgt, ev, jnt));
571 PERFORM create_gate(result, 'conditioned', ARRAY[tgt, ev, jnt]);
572 RETURN result;
573END
574$$ LANGUAGE plpgsql IMMUTABLE SET search_path=provsql,pg_temp,public
575 SECURITY DEFINER PARALLEL SAFE;
576
577/**
578 * @brief Binary @c | : value-level conditioning, @c "target | evidence".
579 *
580 * Carrier-parametric in its left operand; the UUID form builds the terminal
581 * @c gate_conditioned via @c cond. Does not collide with core PostgreSQL's
582 * INTEGER bitwise @c | (different argument types).
583 */
584CREATE OPERATOR | (LEFTARG=UUID, RIGHTARG=UUID, PROCEDURE=cond);
586/**
587 * @brief Placeholder for @c "X | (predicate)" on a UUID event.
588 *
589 * Lets the conditioning event be written as a natural Boolean combination of
590 * random_variable / aggregate comparisons (e.g. @c "event | (sensor > 3)")
591 * instead of a hand-built gate. Never executes: the ProvSQL planner hook
592 * converts the Boolean operand into a condition gate and emits @c cond.
593 */
594CREATE OR REPLACE FUNCTION cond_predicate(target UUID, predicate BOOLEAN)
595 RETURNS UUID AS
596$$
597BEGIN
598 RAISE EXCEPTION 'UUID | (predicate) must be rewritten by the ProvSQL '
599 'planner hook: the right operand must be a Boolean combination of '
600 'random_variable / aggregate comparisons (is provsql.active off?)'
601 USING ERRCODE = 'feature_not_supported',
602 DETAIL = 'provsql-reason: operator-not-rewritten; scope: gap';
603END
604$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
605
606CREATE OPERATOR | (LEFTARG=UUID, RIGHTARG=BOOLEAN, PROCEDURE=cond_predicate);
607
608/**
609 * @brief Placeholder for @c "(predicate) | (predicate)" on two events.
610 *
611 * Conditions one comparison event on another when both operands are written
612 * as comparisons rather than pre-built tokens (e.g.
613 * @c "probability((x >= 2000) | (x >= 1000))"): an @c random_variable /
614 * @c AGG_TOKEN comparison is statically @c BOOLEAN-typed, so neither the
615 * @c "UUID | UUID" (@c cond) nor the @c "UUID | BOOLEAN" (@c cond_predicate)
616 * operator resolves. Never executes: the ProvSQL planner hook lowers each
617 * Boolean operand to its event gate and emits @c cond(target, evidence), so
618 * the result carries the correlation-aware @c Pr(A ∧ B) / Pr(B). Returns
619 * @c UUID, so @c "A | B" is a first-class event token in every position
620 * (a @c probability(UUID) argument, a projected column, a further @c "|").
621 */
622CREATE OR REPLACE FUNCTION predicate_cond_predicate(target BOOLEAN, evidence BOOLEAN)
623 RETURNS UUID AS
624$$
625BEGIN
626 RAISE EXCEPTION '(predicate) | (predicate) must be rewritten by the ProvSQL '
627 'planner hook: both operands must be Boolean combinations of '
628 'random_variable / aggregate comparisons (is provsql.active off?)'
629 USING ERRCODE = 'feature_not_supported',
630 DETAIL = 'provsql-reason: operator-not-rewritten; scope: gap';
631END
632$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
633
634CREATE OPERATOR | (LEFTARG=BOOLEAN, RIGHTARG=BOOLEAN, PROCEDURE=predicate_cond_predicate);
635
636/**
637 * @brief Deterministic indicator gate for an ordinary (regular) comparison.
638 *
639 * The predicate-provenance of an ordinary comparison (both sides of regular
640 * type, e.g. @c "region = 'north'") is the deterministic indicator
641 * @c "χ(cond)": @c gate_one() when the comparison holds on the row,
642 * @c gate_zero() otherwise (Definition in the HAVING-provenance semantics).
643 * The planner emits this for a regular comparison appearing inside a MIXED
644 * conditioning predicate (one that also has a random_variable / aggregate
645 * comparison); @c cond is evaluated per row, so the indicator is the row's
646 * own truth value, combined by @c ⊗ / @c ⊕ with the probabilistic gates.
647 */
648CREATE OR REPLACE FUNCTION regular_indicator(cond BOOLEAN) RETURNS UUID AS
649$$
650 SELECT CASE WHEN cond THEN provsql.gate_one() ELSE provsql.gate_zero() END;
651$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
652
653/**
654 * @brief Whole-tuple output conditioning directive: @c "given(evidence)".
655 *
656 * Written as a term in the select list, @c given(c) conditions the OUTPUT
657 * provenance of the current query's rows on @p c:
658 *
659 * @code
660 * SELECT a, b, given((SELECT provenance() FROM tests
661 * WHERE patient_id = s.id AND result = 'positive'))
662 * FROM source s;
663 * -- visible columns: a, b (the given(...) term is stripped)
664 * -- per-row output provenance: provenance() | <that row's evidence>
665 * @endcode
666 *
667 * The query rewriter recognises the marker, STRIPS it from the visible
668 * projection, and wraps each output row's provenance expression in
669 * @c cond(row_provenance, c) -- deriving a new conditioned relation, never
670 * mutating any stored provenance. @p c is evaluated per output row and may
671 * correlate with the row's columns, so each tuple is conditioned on its own
672 * evidence. When the rewriter is inactive the call is a harmless identity
673 * (it returns @p evidence as an ordinary column).
674 *
675 * When @b executed rather than stripped -- i.e. nested inside an expression,
676 * the idiom @c "and_agg(given(Y = d))" that folds one observation per row
677 * into a latent-variable evidence circuit -- a point-equality @c "Y = d" on
678 * a bare random-variable leaf is turned into likelihood-weighting evidence
679 * (@c evidence_as_observation); any other evidence passes through unchanged.
680 */
681CREATE OR REPLACE FUNCTION given(evidence UUID) RETURNS UUID AS
682$$
683BEGIN
684 RETURN provsql.evidence_as_observation(evidence);
685END
686$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE
687 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
688
689/**
690 * @brief Prefix unary @c | : alias for @c given, @c "| evidence".
691 *
692 * Disambiguated from the binary @c | by the absence of a left operand
693 * (@c "a, | c" parses @c "| c" as the prefix form). PostgreSQL keeps
694 * prefix operators on every supported version (postfix operators were
695 * removed in PG14), so @c "| c" is safe across the CI matrix.
696 */
697CREATE OPERATOR | (RIGHTARG=UUID, PROCEDURE=given);
698
699/**
700 * @brief Conditioning-evidence from a predicate: @c "given(predicate)"
701 * (also the prefix @c "| (predicate)").
702 *
703 * Two uses of the same marker:
704 * - whole-tuple output conditioning written as a select-list term, the
705 * natural-predicate spelling of @c given (@c "SELECT a, given(sensor > 3)");
706 * - per-row evidence for a latent-variable posterior, folded with
707 * @c and_agg -- @c "and_agg(given(normal(mu,1) = x))" turns each row's
708 * observation into likelihood-weighting evidence.
709 *
710 * Never executes: the planner converts the Boolean operand into a condition
711 * gate and emits @c given(gate); a point-equality @c "Y = d" on a bare
712 * random-variable leaf then becomes an observation (see @c given(UUID) /
713 * @c evidence_as_observation).
714 */
715CREATE OR REPLACE FUNCTION given(predicate BOOLEAN) RETURNS UUID AS
716$$
717BEGIN
718 RAISE EXCEPTION 'given(predicate) / prefix | (predicate) must be rewritten '
719 'by the ProvSQL planner hook: the operand must be a Boolean combination '
720 'of random_variable / aggregate comparisons (is provsql.active off?)'
721 USING ERRCODE = 'feature_not_supported',
722 DETAIL = 'provsql-reason: operator-not-rewritten; scope: gap';
723END
724$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
725
726CREATE OPERATOR | (RIGHTARG=BOOLEAN, PROCEDURE=given);
727
728/**
729 * @brief Event negation: @c "! event" / @c "provenance_not(event)".
730 *
731 * The complement of a Boolean provenance event: @c "!x" holds in exactly the
732 * worlds where @p x does not. It is sugar for @c "monus(one, x)" -- an
733 * ordinary m-semiring expression (Boolean @c NOT, probability @c "1 - P(x)"),
734 * NOT a measure-only marker -- so it composes like any @c monus, and a
735 * conditioned / terminal token is refused as its child (so @c "!(x | c)"
736 * errors, as conditioning cannot be buried under further algebra).
737 *
738 * The motivating use is conditioning on the NON-occurrence of an arbitrary
739 * violation query @p W (a denial constraint), where @p W itself is built with
740 * ordinary idioms and needs no hand-rolled gates:
741 *
742 * @code
743 * -- W = "some pair of overlapping same-room bookings is present"
744 * WITH w AS (SELECT provenance() AS tok
745 * FROM bookings a JOIN bookings b
746 * ON a.id < b.id AND a.room = b.room
747 * AND a.lo < b.hi AND b.lo < a.hi
748 * GROUP BY ())
749 * SELECT probability_evaluate((SELECT provenance() FROM bookings WHERE id=1)
750 * | !w.tok) -- P(booking 1 | no overlap)
751 * FROM w;
752 * @endcode
753 *
754 * Named @c provenance_not, after the @c "provenance_times / _plus / _monus"
755 * family; the prefix @c ! operator is the ergonomic form (SQL's reserved
756 * @c NOT keyword cannot serve as a function name).
757 */
758CREATE OR REPLACE FUNCTION provenance_not(event UUID) RETURNS UUID AS
760 SELECT provsql.provenance_monus(provsql.gate_one(), event);
761$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE
762 SET search_path=provsql,pg_temp,public;
763
764/**
765 * @brief Prefix unary @c ! : alias for @c provenance_not, @c "! event".
766 *
767 * Prefix operators are kept on every supported PostgreSQL version (postfix
768 * operators were removed in PG14), and core PG defines no prefix @c ! on
769 * @c UUID, so @c "! event" is safe across the CI matrix.
770 */
771CREATE OPERATOR ! (RIGHTARG=UUID, PROCEDURE=provenance_not);
772
773/**
774 * @brief Build a per-input order-key string for the inversion-free path.
775 *
776 * Emitted by the planner per certified atom: @c K-prefixed, length-prefixed
777 * @c "K<factor> <octet_length(root)>:<root><octet_length(sec)>:<sec>", parsed
778 * back at evaluation by @c safe_cert_key_parse. @p root / @p sec are the
779 * tuple's root- and secondary-class column values (TEXT-cast by the caller);
780 * the byte-length prefixes keep the values unambiguous for @em any column type,
781 * including TEXT containing spaces, colons or digits. @p factor is the atom's
782 * factor id (or -1 for the shared self-join guard). @c IMMUTABLE so the planner
783 * can fold it and the marker dedups by content-addressing.
784 *
785 * Implemented in C (<tt>gate_builders.c</tt>); it was an inlined SQL function,
786 * hence the default cost.
787 */
788CREATE OR REPLACE FUNCTION inversion_free_key(root TEXT, sec TEXT, factor INT)
789 RETURNS TEXT AS
790 'provsql','inversion_free_key' LANGUAGE C STRICT IMMUTABLE PARALLEL SAFE;
791
792/** @brief Get the TEXT-encoded extra data associated with a circuit gate */
793CREATE OR REPLACE FUNCTION get_extra(token UUID)
794 RETURNS TEXT AS
795 'provsql','get_extra' LANGUAGE C STABLE PARALLEL SAFE RETURNS NULL ON NULL INPUT;
796
797/**
798 * @brief Return the total number of materialized gates in the provenance circuit
799 *
800 * Input gates for provenance-tracked table rows are created lazily on
801 * first reference; rows that have never appeared in a query result are
802 * not counted.
803 */
804CREATE OR REPLACE FUNCTION get_nb_gates() RETURNS BIGINT AS
805 'provsql', 'get_nb_gates' LANGUAGE C PARALLEL SAFE;
806
807/**
808 * @brief Report what does not add up in this database's circuit store
809 *
810 * The store lives in four files under the database's directory, outside
811 * PostgreSQL's WAL and buffer manager, so PostgreSQL's own crash recovery
812 * says nothing about it. Writes are ordered so that an interrupted one
813 * leaves a RECORD nothing points at rather than a pointer to a RECORD
814 * that is not there, and the rehash of the token table is done by
815 * renaming a complete new file over the old one; this function checks
816 * that those invariants hold.
817 *
818 * Every count is 0 for a healthy store. @c unclean_shutdown is true when
819 * a file was still marked open-for-writing when it was opened, which an
820 * immediate shutdown or a crash of the server leaves behind and is not by
821 * itself a problem. A non-zero @c dangling_indices, @c bad_wires or
822 * @c bad_extra means the files do not agree with each other -- typically
823 * a file-level backup taken while the server was running, or a base
824 * backup; @c provsql.circuit_cleanup() rebuilds the store from what is
825 * still reachable. @c unreferenced counts gate records the token table
826 * does not point at: a handful is normal (an interrupted write), a large
827 * number means the token table is missing entries.
828 */
829CREATE OR REPLACE FUNCTION check_store(
830 OUT unclean_shutdown BOOLEAN,
831 OUT nb_gates BIGINT,
832 OUT nb_tokens BIGINT,
833 OUT next_index BIGINT,
834 OUT dangling_indices BIGINT,
835 OUT unreferenced BIGINT,
836 OUT bad_wires BIGINT,
837 OUT bad_extra BIGINT)
838 RETURNS RECORD AS
839 'provsql', 'check_store' LANGUAGE C;
840
841/**
842 * @brief Rebuild this database's circuit store, keeping only what the
843 * tokens stored in the database reach
844 *
845 * The store only grows: a gate is never removed, because a rolled-back
846 * transaction leaves an orphan rather than an inconsistency, and because
847 * the same expression recomputed lands on the same content-addressed
848 * gate. This is the complement of that -- the one operation allowed to
849 * remove gates, run explicitly, the way @c VACUUM @c FULL is the
850 * complement of MVCC. It is also the repair tool for a store an
851 * interrupted write left inconsistent (see @c provsql.check_store).
852 *
853 * It takes the database exclusively: it holds the lock @c DROP
854 * @c DATABASE holds, so sessions connecting from then on wait, and it
855 * refuses to run while another session is already connected. That is
856 * unavoidable -- a query running alongside can adopt an orphan gate a
857 * moment before the sweep removes it, since gates are re-created
858 * idempotently and a backend's own cache answers "it exists" without
859 * asking the store at all.
860 *
861 * A root is every value of a @c UUID, @c AGG_TOKEN or @c random_variable
862 * column, and of arrays of those, in every table and materialised view of
863 * the database -- not only columns named @c provsql -- plus the constants
864 * @c gate_zero, @c gate_one and @c gate_null. A token that lives only
865 * outside the database is **not** a root: one kept in a notebook cell, a
866 * deep link, a file, or a @c TEXT / @c jsonb column. Content-addressed
867 * gates come back by re-running the query that built them; freshly minted
868 * ones do not.
869 *
870 * @param dry_run report what would be kept without writing anything; the
871 * wire and byte totals are then NULL, since the size of
872 * the rewrite is not known without doing it
873 * @param[out] gates_before gate records in the store beforehand
874 * @param[out] gates_after gate records the roots reach, and so kept
875 * @param[out] wires_before child wires beforehand
876 * @param[out] wires_after child wires kept (NULL on a dry run)
877 * @param[out] extra_bytes_before bytes of gate annotations beforehand
878 * @param[out] extra_bytes_after bytes of gate annotations kept (NULL on a
879 * dry run)
880 */
881CREATE OR REPLACE FUNCTION circuit_cleanup(
882 dry_run BOOLEAN DEFAULT false,
883 OUT gates_before BIGINT,
884 OUT gates_after BIGINT,
885 OUT wires_before BIGINT,
886 OUT wires_after BIGINT,
887 OUT extra_bytes_before BIGINT,
888 OUT extra_bytes_after BIGINT)
889 RETURNS RECORD AS
890 'provsql', 'circuit_cleanup' LANGUAGE C;
891
892/** @} */
893
894/** @defgroup table_management Provenance table management
895 * Functions for enabling, disabling, and configuring provenance
896 * tracking on user tables.
897 * @{
898 */
899
900
901/**
902 * @brief Trigger function for DELETE statement provenance tracking
903 *
904 * Records the deletion and applies monus to provenance tokens of
905 * deleted rows. This is the version for PostgreSQL < 14.
906 */
907CREATE OR REPLACE FUNCTION delete_statement_trigger()
908 RETURNS TRIGGER AS
910DECLARE
911 query_text TEXT;
912 delete_token UUID;
913 old_token UUID;
914 new_token UUID;
915 r RECORD;
916BEGIN
917 delete_token := public.uuid_generate_v4();
918
919 PERFORM create_gate(delete_token, 'input');
920
921 SELECT query
922 INTO query_text
923 FROM pg_stat_activity
924 WHERE pid = pg_backend_pid();
925
926 INSERT INTO delete_provenance (delete_token, query, deleted_by, deleted_at)
927 VALUES (delete_token, query_text, current_user, CURRENT_TIMESTAMP);
928
929 EXECUTE format('INSERT INTO %I.%I SELECT * FROM OLD_TABLE;', TG_TABLE_SCHEMA, TG_TABLE_NAME);
930
931 FOR r IN (SELECT * FROM OLD_TABLE) LOOP
932 old_token := r.provsql;
933 new_token := provenance_monus(old_token, delete_token);
934
935 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2;', TG_TABLE_SCHEMA, TG_TABLE_NAME)
936 USING new_token, old_token;
937 END LOOP;
938
939 RETURN NULL;
940END
941$$ LANGUAGE plpgsql SET search_path=provsql,pg_temp SECURITY DEFINER;
942
943
944/**
945 * @brief Per-relation provenance metadata used by the safe-query
946 * optimisation.
947 *
948 * One row per relation ProvSQL tracks. @c relid is stored as
949 * @c REGCLASS so a dump carries the relation's *name*: OIDs are not
950 * stable across databases, and @c pg_dump / @c pg_restore resolve a
951 * @c REGCLASS value back to whatever OID the relation has in the
952 * target database. @c kind is one of @c 'tid' / @c 'bid' /
953 * @c 'opaque' (see @c set_table_info); @c block_key lists the
954 * block-key column numbers of a BID relation; @c ancestors lists the
955 * base relations this one's atoms ultimately come from.
956 *
957 * Being a heap table, every change follows the transaction that made
958 * it: a rolled-back @c add_provenance leaves no RECORD, a rolled-back
959 * @c DROP @c TABLE keeps one, and a concurrent session sees a change
960 * only once it commits. Marked as a configuration table so
961 * @c pg_dump carries it.
962 */
963CREATE TABLE IF NOT EXISTS table_info(
964 relid REGCLASS PRIMARY KEY,
965 kind TEXT NOT NULL,
966 block_key int2[] NOT NULL DEFAULT ARRAY[]::int2[],
967 ancestors oid[] NOT NULL DEFAULT ARRAY[]::oid[]
968);
969SELECT pg_catalog.pg_extension_config_dump('table_info', '');
970
971/**
972 * @brief Row trigger keeping every backend's metadata cache honest.
973 *
974 * Each backend caches the metadata of the relations its queries touch
975 * and drops an entry when PostgreSQL invalidates that relation's
976 * relcache entry. This trigger issues that invalidation for the
977 * relation named by every inserted, updated, or deleted row, so a
978 * hand-written @c UPDATE on the table and the @c COPY a @c pg_restore
979 * performs are as visible to the caches as the setter functions are.
980 */
981CREATE OR REPLACE FUNCTION table_info_invalidate()
982 RETURNS trigger AS
983 'provsql','provsql_table_info_invalidate' LANGUAGE C;
984
985DROP TRIGGER IF EXISTS table_info_invalidate ON table_info;
986CREATE TRIGGER table_info_invalidate
987 AFTER INSERT OR UPDATE OR DELETE ON table_info
988 FOR EACH ROW EXECUTE FUNCTION provsql.table_info_invalidate();
989
990/**
991 * @brief Record per-relation provenance metadata used by the
992 * safe-query optimisation.
993 *
994 * Upserts the @c (relid, kind, block_key) half of the relation's row
995 * in @c provsql.table_info, preserving its @c ancestors. @p kind is
996 * one of:
997 * - @c 'tid' -- independent input leaves (post-@c add_provenance default)
998 * - @c 'bid' -- block-correlated leaves; rows sharing the same value
999 * of @p block_key are mutually exclusive. An empty
1000 * @p block_key means the whole table is one block.
1001 * - @c 'opaque' -- arbitrary correlations from a derived source
1002 * (CREATE TABLE AS SELECT, INSERT INTO SELECT,
1003 * UPDATE under provsql.update_provenance); the
1004 * safe-query rewriter must bail on these.
1006 * @param relid pg_class OID of the relation.
1007 * @param kind One of @c 'tid' / @c 'bid' / @c 'opaque'.
1008 * @param block_key Block-key column numbers (only meaningful for
1009 * @c 'bid'; ignored otherwise but conventionally
1010 * passed empty).
1011 */
1012CREATE OR REPLACE FUNCTION set_table_info(
1013 relid OID, kind TEXT, block_key INT2[] DEFAULT ARRAY[]::INT2[])
1014 RETURNS VOID AS
1015 'provsql','set_table_info' LANGUAGE C SECURITY DEFINER;
1016
1017/** @brief Remove a relation's row from @c provsql.table_info.
1018 * No-op when missing. */
1019CREATE OR REPLACE FUNCTION remove_table_info(relid OID)
1020 RETURNS VOID AS
1021 'provsql','remove_table_info' LANGUAGE C SECURITY DEFINER;
1022
1023/**
1024 * @brief Read per-relation provenance metadata.
1025 *
1026 * Returns NULL if no RECORD exists. @c kind is one of @c 'tid' /
1027 * @c 'bid' / @c 'opaque'; @c block_key is the (possibly empty) array
1028 * of block-key column numbers, only meaningful when @c kind = @c 'bid'.
1029 * Used by the planner-time hierarchy detector to gate the safe-query
1030 * rewrite.
1031 */
1032CREATE OR REPLACE FUNCTION get_table_info(
1033 relid OID, OUT kind TEXT, OUT block_key INT2[])
1034 RETURNS RECORD AS
1035 'provsql','get_table_info' LANGUAGE C STABLE PARALLEL SAFE;
1036
1038 * @brief Record the base-relation ancestor set of a tracked relation.
1040 * Base tables created with @c add_provenance / @c repair_key carry
1041 * @c {self}; CTAS-derived tables inherit the union of their sources'
1042 * ancestor sets. The safe-query rewriter consults the registry to
1043 * enforce that joined FROM entries have disjoint base ancestors
1044 * before firing the read-once factoring.
1045 *
1046 * Preserves the relation's existing @c kind / @c block_key half on
1047 * update, and silently no-ops when no row exists for @p relid
1048 * (callers should run @c add_provenance / @c repair_key first). The
1049 * ancestor list is capped at 64 entries (clear error if exceeded).
1050 *
1051 * @param relid pg_class OID of the relation.
1052 * @param ancestors Sorted, deduplicated base-relation OIDs.
1053 */
1054CREATE OR REPLACE FUNCTION set_ancestors(
1055 relid OID, ancestors OID[] DEFAULT ARRAY[]::OID[])
1056 RETURNS VOID AS
1057 'provsql','set_ancestors' LANGUAGE C SECURITY DEFINER;
1058
1059/** @brief Clear the ancestor half of a per-relation RECORD (keeps kind/block_key).
1060 * No-op when missing. */
1061CREATE OR REPLACE FUNCTION remove_ancestors(relid OID)
1062 RETURNS VOID AS
1063 'provsql','remove_ancestors' LANGUAGE C SECURITY DEFINER;
1065/**
1066 * @brief Copy per-relation metadata out of the legacy
1067 * @c provsql_table_info.mmap file into @c provsql.table_info.
1068 *
1069 * ProvSQL 1.13.0 moved this metadata from a fifth mmap file to a heap
1070 * table, so that it follows the transaction that writes it and is
1071 * carried by @c pg_dump. This function reads the legacy file, if the
1072 * database still has one, and inserts every RECORD it holds that the
1073 * heap table does not already have; it returns the number of rows
1074 * inserted, and 0 when there is no file to read. Idempotent, and a
1075 * no-op on a database that never had one.
1076 */
1077CREATE OR REPLACE FUNCTION migrate_table_info()
1078 RETURNS BIGINT AS
1079 'provsql','migrate_table_info' LANGUAGE C SECURITY DEFINER;
1081/**
1082 * @brief Read the base-relation ancestor set of a tracked relation.
1083 *
1084 * Returns @c NULL when no ancestor RECORD exists for @p relid (or the
1085 * RECORD is empty -- both cases make the safe-query rewriter take
1086 * its conservative refuse path, so they collapse here).
1087 */
1088CREATE OR REPLACE FUNCTION get_ancestors(relid OID)
1089 RETURNS OID[] AS
1090 'provsql','get_ancestors' LANGUAGE C STABLE PARALLEL SAFE;
1091
1092/**
1093 * @brief BEFORE INSERT OR UPDATE OF provsql row trigger installed by
1094 * @c add_provenance.
1095 *
1096 * Two jobs:
1097 *
1098 * 1. Fill @c NEW.provsql with a fresh @c uuid_generate_v4 leaf when
1099 * the user did not supply one (a column DEFAULT would not do here:
1100 * it fires before the trigger sees the row, so we could not tell
1101 * "user omitted the column" from "user supplied a value").
1102 * 2. When the user does supply a non-NULL @c provsql on @c INSERT,
1103 * or changes it on @c UPDATE, flip the table's per-table
1104 * metadata to @c OPAQUE. The user is free to write whatever
1105 * UUIDs they want (cross-table reuse, compound tokens minted
1106 * via @c create_gate, ...); the cost is that the safe-query
1107 * rewriter then refuses to fire on this table, because TID
1108 * independence can no longer be assumed. The exception is a
1109 * leaf @c provsql.replace_input / @c replace_block minted in
1110 * this transaction: that one *is* an independent fresh leaf, so
1111 * the kind survives and the maintained mappings follow the
1112 * token to its replacement.
1113 */
1114CREATE OR REPLACE FUNCTION provenance_guard()
1115 RETURNS TRIGGER AS $$
1116DECLARE
1117 _m RECORD;
1118BEGIN
1119 IF TG_OP = 'INSERT' THEN
1120 IF NEW.provsql IS NULL THEN
1121 -- A genuine insert: mint a fresh atomic input variable. This is the
1122 -- one place a new input token is born, so it is also where any
1123 -- maintained mapping on this table is extended (keyed to that token).
1124 -- Data-modification re-insertions (INSERT ... SELECT * FROM OLD_TABLE)
1125 -- carry a supplied provsql and take the ELSE branch, so they are
1126 -- correctly skipped: the validity stays keyed to the original input,
1127 -- which is exactly the child a later monus/update gate wraps.
1128 NEW.provsql := public.uuid_generate_v4();
1129 FOR _m IN SELECT mapping, attribute
1130 FROM provsql.provenance_mapping_registry
1131 WHERE source = TG_RELID AND maintained
1132 LOOP
1133 EXECUTE format(
1134 'INSERT INTO %s(value, provenance) SELECT ($1).%I, $2',
1135 _m.mapping::REGCLASS, _m.attribute)
1136 USING NEW, NEW.provsql;
1137 END LOOP;
1138 ELSE
1139 PERFORM provsql.set_table_info(TG_RELID, 'opaque');
1140 END IF;
1141 ELSIF TG_OP = 'UPDATE' THEN
1142 IF NEW.provsql IS DISTINCT FROM OLD.provsql THEN
1143 IF provsql.is_fresh_leaf(NEW.provsql) THEN
1144 -- A replacement leaf minted by provsql.replace_input /
1145 -- replace_block in this transaction: an independent fresh leaf by
1146 -- construction, so the table's kind survives. Carry the
1147 -- maintained mappings over from the token it replaces, the same
1148 -- job the INSERT branch does for a new row.
1149 FOR _m IN SELECT mapping, attribute
1150 FROM provsql.provenance_mapping_registry WHERE source = TG_RELID
1151 LOOP
1152 EXECUTE format(
1153 'INSERT INTO %1$s(value, provenance) '
1154 'SELECT value, $2 FROM %1$s WHERE provenance = $1',
1155 _m.mapping::REGCLASS)
1156 USING OLD.provsql, NEW.provsql;
1157 END LOOP;
1158 ELSE
1159 PERFORM provsql.set_table_info(TG_RELID, 'opaque');
1160 END IF;
1161 END IF;
1162 END IF;
1163 RETURN NEW;
1164END;
1165$$ LANGUAGE plpgsql SET search_path=provsql,pg_temp,public
1166 SECURITY DEFINER;
1168/**
1169 * @brief Enable provenance tracking on an existing table
1170 *
1171 * Adds a <tt>provsql</tt> UUID column to the table, an index for
1172 * fast UUID-keyed lookups, and a BEFORE INSERT/UPDATE row trigger
1173 * (@c provenance_guard) that mints a fresh @c uuid_generate_v4
1174 * leaf when the user omits the column on INSERT, or flips the
1175 * table's metadata to @c OPAQUE when the user supplies their own
1176 * value. Input gates for existing rows are created lazily when
1177 * first referenced by a query.
1178 *
1179 * @param _tbl the table to add provenance tracking to
1180 */
1181CREATE OR REPLACE FUNCTION add_provenance(_tbl REGCLASS)
1182 RETURNS VOID AS
1183$$
1184BEGIN
1185 -- Idempotence: a second add_provenance on an already-tracked table is
1186 -- a no-op with a NOTICE, so setup scripts and notebook cells can be
1187 -- re-run freely.
1188 IF EXISTS (
1189 SELECT 1 FROM pg_attribute
1190 WHERE attrelid = _tbl AND attname = 'provsql' AND NOT attisdropped
1191 ) THEN
1192 RAISE NOTICE 'table % already has provenance tracking', _tbl;
1193 RETURN;
1194 END IF;
1195 -- No DEFAULT: the guard trigger mints the UUID, so the trigger can
1196 -- distinguish "user omitted" (NULL) from "user supplied a value".
1197 -- No UNIQUE: we no longer rely on it to keep the table TID -- the
1198 -- guard does that semantically -- and a UNIQUE would reject the
1199 -- legitimate cross-table UUID copy that just flips the table to
1200 -- OPAQUE. We keep a plain index for fast UUID-keyed lookups.
1201 EXECUTE format('ALTER TABLE %s ADD COLUMN provsql UUID', _tbl);
1202 EXECUTE format(
1203 'UPDATE %s SET provsql = public.uuid_generate_v4() WHERE provsql IS NULL',
1204 _tbl);
1205 EXECUTE format('CREATE INDEX ON %s(provsql)', _tbl);
1206 EXECUTE format(
1207 'CREATE TRIGGER provenance_guard BEFORE INSERT OR UPDATE OF provsql '
1208 'ON %s FOR EACH ROW EXECUTE FUNCTION provsql.provenance_guard()',
1209 _tbl);
1210 PERFORM provsql.set_table_info(_tbl::oid, 'tid');
1211 -- Seed the base-ancestor set to {self}: a base TID table's atoms
1212 -- come from itself and no other relation. CTAS-derived tables
1213 -- inherit unions of source ancestor sets; that is handled by the
1214 -- CTAS hook (a separate slice), not here.
1215 PERFORM provsql.set_ancestors(_tbl::oid, ARRAY[_tbl::oid]);
1216END
1217$$ LANGUAGE plpgsql SECURITY DEFINER;
1218
1219/**
1220 * @brief Remove provenance tracking from a table
1221 *
1222 * Drops the <tt>provsql</tt> column and associated triggers.
1223 *
1224 * @param _tbl the table to remove provenance tracking from
1225 */
1226CREATE OR REPLACE FUNCTION remove_provenance(_tbl REGCLASS)
1227 RETURNS VOID AS
1229DECLARE
1230BEGIN
1231 PERFORM provsql.remove_table_info(_tbl::oid);
1232 -- Idempotence, mirroring add_provenance: removing provenance from a
1233 -- table that does not have it is a NOTICE-and-no-op, so setup scripts
1234 -- and notebook cells can be re-run freely. The metadata strip above
1235 -- still runs, so a table left half-tracked is cleaned up.
1236 IF NOT EXISTS (
1237 SELECT 1 FROM pg_attribute
1238 WHERE attrelid = _tbl AND attname = 'provsql' AND NOT attisdropped
1239 ) THEN
1240 RAISE NOTICE 'table % does not have provenance tracking', _tbl;
1241 RETURN;
1242 END IF;
1243 -- Drop the BEFORE INSERT/UPDATE guard first: it has a column
1244 -- dependency on provsql (via the OF provsql clause), so the
1245 -- subsequent DROP COLUMN would otherwise raise.
1246 BEGIN
1247 EXECUTE format('DROP TRIGGER provenance_guard on %s', _tbl);
1248 EXCEPTION WHEN undefined_object THEN
1249 END;
1250 EXECUTE format('ALTER TABLE %s DROP COLUMN provsql', _tbl);
1251 BEGIN
1252 EXECUTE format('DROP TRIGGER add_gate on %s', _tbl);
1253 EXCEPTION WHEN undefined_object THEN
1254 END;
1255 BEGIN
1256 EXECUTE format('DROP TRIGGER insert_statement on %s', _tbl);
1257 EXECUTE format('DROP TRIGGER update_statement on %s', _tbl);
1258 EXECUTE format('DROP TRIGGER delete_statement on %s', _tbl);
1259 EXCEPTION WHEN undefined_object THEN
1260 END;
1261END
1262$$ LANGUAGE plpgsql;
1263
1264/**
1265 * @brief Set up provenance for a table with duplicate key values
1267 * When a table has duplicate rows for a given key, this function
1268 * replaces simple input gates with multivalued input (mulinput) gates
1269 * that model a uniform distribution over duplicates. The uniform
1270 * weight is the default a row evaluates at, not a probability written
1271 * on it, so the usual next step -- @c "SELECT set_prob(provenance(),
1272 * p) FROM t" -- gives each row its real probability as a first write.
1273 *
1274 * @param _tbl the table to repair
1275 * @param key_att the key attribute(s) as a comma-separated string, or
1276 * empty string if the whole table is one group
1277 */
1278CREATE OR REPLACE FUNCTION repair_key(_tbl REGCLASS, key_att TEXT)
1279 RETURNS VOID AS
1280$$
1281DECLARE
1282 r RECORD;
1283 rows_query TEXT;
1284 block_key_cols INT2[];
1285BEGIN
1286 -- Resolve the (possibly comma-separated) key_att TEXT into the
1287 -- corresponding pg_attribute.attnum values for the safe-query
1288 -- metadata. Names are trimmed; quoting is not supported because
1289 -- repair_key has never accepted quoted identifiers in key_att.
1290 IF key_att = '' THEN
1291 block_key_cols := ARRAY[]::INT2[];
1292 ELSE
1293 SELECT array_agg(a.attnum ORDER BY t.ord)::INT2[]
1294 INTO block_key_cols
1295 FROM unnest(string_to[](key_att, ',')) WITH ORDINALITY AS t(name, ord)
1296 JOIN pg_attribute a
1297 ON a.attrelid = _tbl
1298 AND a.attname = trim(t.name)
1299 AND a.attnum > 0
1300 AND NOT a.attisdropped;
1301 IF block_key_cols IS NULL OR array_length(block_key_cols, 1) IS NULL THEN
1302 RAISE EXCEPTION 'repair_key: could not resolve key columns from "%"', key_att
1303 USING ERRCODE = 'feature_not_supported',
1304 DETAIL = 'provsql-reason: repair-key-columns; scope: gap';
1305 END IF;
1306 IF array_length(block_key_cols, 1) > 16 THEN
1307 RAISE EXCEPTION 'repair_key: block key wider than 16 columns is not supported'
1308 USING ERRCODE = 'feature_not_supported',
1309 DETAIL = 'provsql-reason: repair-key-too-wide; scope: gap';
1310 END IF;
1311 END IF;
1312
1313 -- Same column shape as add_provenance: no UNIQUE, no DEFAULT past
1314 -- the initial backfill (the guard trigger added after the rename
1315 -- takes over both jobs once the column has been renamed to its
1316 -- final name). The DEFAULT is kept here only so the second pass
1317 -- below can read provsql_temp from the user-visible rows
1318 -- without a separate UPDATE.
1319 EXECUTE format('ALTER TABLE %s ADD COLUMN provsql_temp UUID DEFAULT public.uuid_generate_v4()', _tbl);
1320
1321 -- Build a per-group mapping (key columns + a fresh key_token + the
1322 -- group size) once, then use it for both the create_gate(key_token,
1323 -- 'input') first pass and the per-row mulinput second pass. Going
1324 -- through a temp table avoids re-running uuid_generate_v4() (which
1325 -- would produce different UUIDs the second time). USING (%1$s) on
1326 -- the second pass handles the multi-column case uniformly.
1327 -- ON COMMIT DROP plus the explicit DROP TABLE at the end of this
1328 -- function leave the temp table cleaned up across transactions and
1329 -- across repeated calls in the same transaction.
1330 IF key_att = '' THEN
1331 EXECUTE format(
1332 'CREATE TEMP TABLE provsql_repair_key_tmp ON COMMIT DROP AS
1333 SELECT public.uuid_generate_v4() AS provsql_key_token,
1334 COUNT(*) AS provsql_group_size
1335 FROM %s', _tbl);
1336 rows_query := format(
1337 'SELECT t.provsql_temp,
1338 k.provsql_key_token AS key_token,
1339 ROW_NUMBER() OVER (ORDER BY t.ctid) AS within_group,
1340 k.provsql_group_size AS group_size
1341 FROM %s t CROSS JOIN provsql_repair_key_tmp k', _tbl);
1342 ELSE
1343 EXECUTE format(
1344 'CREATE TEMP TABLE provsql_repair_key_tmp ON COMMIT DROP AS
1345 SELECT %1$s,
1346 public.uuid_generate_v4() AS provsql_key_token,
1347 COUNT(*) AS provsql_group_size
1348 FROM %2$s
1349 GROUP BY %1$s', key_att, _tbl);
1350 rows_query := format(
1351 'SELECT t.provsql_temp,
1352 k.provsql_key_token AS key_token,
1353 ROW_NUMBER() OVER (PARTITION BY k.provsql_key_token
1354 ORDER BY t.ctid) AS within_group,
1355 k.provsql_group_size AS group_size
1356 FROM %2$s t
1357 JOIN provsql_repair_key_tmp k USING (%1$s)', key_att, _tbl);
1358 END IF;
1359
1360 -- Pass 1: one input gate per group key.
1361 FOR r IN SELECT provsql_key_token FROM provsql_repair_key_tmp LOOP
1362 PERFORM provsql.create_gate(r.provsql_key_token, 'input');
1363 END LOOP;
1364
1365 -- Pass 2: per row, attach a mulinput gate to its group's key token.
1366 -- The block size goes in info2 rather than the uniform 1/size going
1367 -- in the probability: a repaired row's probability is the user's to
1368 -- write (the documented "repair_key then set_prob(provenance(), p)"
1369 -- pattern), and probabilities are written once. A row nobody gives
1370 -- a probability evaluates at 1/size all the same -- see
1371 -- MMappedCircuit::getProb.
1372 FOR r IN EXECUTE rows_query LOOP
1373 PERFORM provsql.create_gate(r.provsql_temp, 'mulinput', ARRAY[r.key_token],
1374 r.within_group::INT, r.group_size::INT, NULL);
1375 END LOOP;
1376
1377 DROP TABLE provsql_repair_key_tmp;
1378
1379 EXECUTE format('ALTER TABLE %s ALTER COLUMN provsql_temp DROP DEFAULT', _tbl);
1380 EXECUTE format('ALTER TABLE %s RENAME COLUMN provsql_temp TO provsql', _tbl);
1381 EXECUTE format('CREATE INDEX ON %s(provsql)', _tbl);
1382 EXECUTE format(
1383 'CREATE TRIGGER provenance_guard BEFORE INSERT OR UPDATE OF provsql '
1384 'ON %s FOR EACH ROW EXECUTE FUNCTION provsql.provenance_guard()',
1385 _tbl);
1386 PERFORM provsql.set_table_info(_tbl::oid, 'bid', block_key_cols);
1387 -- Base BID tables also have themselves as their sole ancestor. Same
1388 -- rationale as the @c add_provenance branch above.
1389 PERFORM provsql.set_ancestors(_tbl::oid, ARRAY[_tbl::oid]);
1390END
1391$$ LANGUAGE plpgsql;
1392
1393/**
1394 * @brief Event trigger that purges per-table provenance metadata when
1395 * a tracked relation is dropped outside of remove_provenance().
1396 *
1397 * Plain DROP TABLE bypasses remove_provenance() and would otherwise
1398 * leave a stale row in provsql.table_info keyed by a now-recycled
1399 * OID, with confusing consequences for the safe-query rewriter the
1400 * next time the OID is reused. This trigger forwards every dropped
1401 * relation OID to provsql.remove_table_info(), which is a no-op for
1402 * relations that were not tracked. Both the deletion and the
1403 * registry cleanup below roll back with the DROP that triggered
1404 * them.
1405 */
1406CREATE OR REPLACE FUNCTION cleanup_table_info()
1407 RETURNS event_trigger AS
1408$$
1409DECLARE
1410 r RECORD;
1411BEGIN
1412 FOR r IN
1413 SELECT objid FROM pg_event_trigger_dropped_objects()
1414 WHERE object_type IN ('table', 'foreign table', 'materialized view')
1415 LOOP
1416 PERFORM provsql.remove_table_info(r.objid);
1417 -- Forget any maintained mapping whose source or mapping table is gone.
1418 DELETE FROM provsql.provenance_mapping_registry
1419 WHERE source = r.objid OR mapping = r.objid;
1420 END LOOP;
1421END
1422$$ LANGUAGE plpgsql;
1423
1424DROP EVENT TRIGGER IF EXISTS provsql_cleanup_table_info;
1425-- @c EXECUTE @c PROCEDURE (rather than the PG 11+ @c EXECUTE
1426-- @c FUNCTION alias) so the extension installs on PG 10 too.
1427CREATE EVENT TRIGGER provsql_cleanup_table_info ON sql_drop
1428 EXECUTE FUNCTION provsql.cleanup_table_info();
1429
1430/**
1431 * @brief Registry of provenance mappings
1432 *
1433 * Each row records that mapping table @c mapping was built from the
1434 * @c attribute column of the provenance-tracked @c source table. When
1435 * @c maintained, every genuine insert into @c source also appends
1436 * @c (value, provenance) to it, so the mapping stays current; otherwise
1437 * the mapping is a snapshot and the row is here only so that a token
1438 * *replacement* carries the mapping over (see @c provenance_guard: a leaf
1439 * minted by @c replace_input names the same tuple, so its value is copied
1440 * to the new token in every mapping of the table, maintained or not).
1441 * Keyed on the mapping table, indexed on the source so the guard can look
1442 * up a table's mappings cheaply. Entries are removed when either table is
1443 * dropped (see @c cleanup_table_info).
1444 */
1445CREATE TABLE IF NOT EXISTS provsql.provenance_mapping_registry(
1446 mapping oid PRIMARY KEY,
1447 source oid NOT NULL,
1448 attribute name NOT NULL,
1449 maintained BOOLEAN NOT NULL DEFAULT false
1450);
1451ALTER TABLE provsql.provenance_mapping_registry
1452 ADD COLUMN IF NOT EXISTS maintained BOOLEAN NOT NULL DEFAULT false;
1453CREATE INDEX IF NOT EXISTS provenance_mapping_registry_source_idx
1454 ON provsql.provenance_mapping_registry(source);
1456/**
1457 * @brief Create a provenance mapping table from an attribute
1458 *
1459 * Creates a new table mapping provenance tokens to values of a given
1460 * attribute, for use with semiring evaluation functions.
1461 * Idempotent: if the mapping table already exists, raises a NOTICE and
1462 * changes nothing (drop it first to rebuild).
1463 *
1464 * @param newtbl name of the mapping table to create
1465 * @param oldtbl source table with provenance tracking
1466 * @param att attribute whose values populate the mapping
1467 * @param preserve_case if true, quote the table name to preserve case
1468 * @param maintained if true, later inserts into @c oldtbl keep the mapping
1469 * current, and it stays correct after data modification
1470 * (deletes/updates rewrite a row's provsql, but the validity stays
1471 * keyed to the original input token). @c att must then be a plain
1472 * column name. When false (the default) the table is a one-off
1473 * snapshot; either way the mapping is recorded in
1474 * @c provenance_mapping_registry, so a row whose input gate is
1475 * replaced by @c provsql.replace_input keeps its value in it.
1476 */
1477CREATE OR REPLACE FUNCTION create_provenance_mapping(
1478 newtbl TEXT,
1479 oldtbl REGCLASS,
1480 att TEXT,
1481 preserve_case BOOL DEFAULT 'f',
1482 maintained BOOL DEFAULT false
1483) RETURNS VOID AS
1484$$
1485DECLARE
1486BEGIN
1487 -- Idempotence: when the mapping table already exists, leave it alone
1488 -- with a NOTICE (re-runnable setup scripts / notebook cells). Drop it
1489 -- first to rebuild a stale mapping.
1490 IF (CASE WHEN preserve_case THEN to_regclass(format('%I', newtbl))
1491 ELSE to_regclass(newtbl) END) IS NOT NULL THEN
1492 RAISE NOTICE 'mapping table % already exists', newtbl;
1493 RETURN;
1494 END IF;
1495 -- ON COMMIT DROP only fires at COMMIT: several mapping creations in
1496 -- one transaction (a notebook cell, a setup script run via psql -1)
1497 -- would otherwise collide on the leftover temp table. The to_regclass
1498 -- probe (rather than DROP IF EXISTS) keeps the first call NOTICE-free.
1499 IF to_regclass('pg_temp.tmp_provsql') IS NOT NULL THEN
1500 DROP TABLE tmp_provsql;
1501 END IF;
1502 EXECUTE format('CREATE TEMP TABLE tmp_provsql ON COMMIT DROP AS TABLE %s', oldtbl);
1503 ALTER TABLE tmp_provsql RENAME provsql TO provenance;
1504 -- The mapping is keyed by gate identity (input-token UUIDs), so peel any
1505 -- transparent annotation wrapper (e.g. the inversion-free certificate a
1506 -- certified query attaches to its row roots) off the captured tokens.
1507 UPDATE tmp_provsql SET provenance = provsql.strip_annotations(provenance)
1508 WHERE provsql.get_gate_type(provenance) = 'annotation';
1509 IF preserve_case THEN
1510 EXECUTE format('CREATE TABLE %I AS SELECT %s AS value, provenance FROM tmp_provsql', newtbl, att);
1511 EXECUTE format('CREATE INDEX ON %I(provenance)', newtbl);
1512 ELSE
1513 EXECUTE format('CREATE TABLE %s AS SELECT %s AS value, provenance FROM tmp_provsql', newtbl, att);
1514 EXECUTE format('CREATE INDEX ON %s(provenance)', newtbl);
1515 END IF;
1516 -- Register the mapping. When maintained, genuine inserts into oldtbl
1517 -- keep it current (see provenance_guard); keyed to the input token, so
1518 -- it survives the provsql rewrites that data modification performs.
1519 -- A snapshot mapping is registered too, so that replacing a row's input
1520 -- gate (provsql.replace_input) carries the row's value over to the new
1521 -- token: the tuple is the same one, only its token moved.
1522 INSERT INTO provsql.provenance_mapping_registry(mapping, source, attribute, maintained)
1523 VALUES (
1524 (CASE WHEN preserve_case THEN to_regclass(format('%I', newtbl))
1525 ELSE to_regclass(newtbl) END)::oid,
1526 oldtbl::oid, att, maintained)
1527 ON CONFLICT (mapping)
1528 DO UPDATE SET source = EXCLUDED.source, attribute = EXCLUDED.attribute,
1529 maintained = EXCLUDED.maintained;
1530END
1531$$ LANGUAGE plpgsql;
1532
1533/** @} */
1534
1535/** @defgroup internal_constants Internal constants
1536 * UUID namespace and identity element functions used for
1537 * deterministic gate generation.
1538 * @{
1539 */
1540
1541/** @brief Return the ProvSQL UUID namespace (used for deterministic gate UUIDs) */
1542CREATE OR REPLACE FUNCTION uuid_ns_provsql() RETURNS UUID AS
1543$$
1544 -- uuid_generate_v5(uuid_ns_url(),'http://pierre.senellart.com/software/provsql/')
1545 SELECT '920d4f02-8718-5319-9532-d4ab83a64489'::UUID
1546$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
1547
1548/** @brief Return the UUID of the semiring zero gate */
1549CREATE OR REPLACE FUNCTION gate_zero() RETURNS UUID AS
1551 SELECT public.uuid_generate_v5(provsql.uuid_ns_provsql(),'zero');
1552$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
1553
1554/** @brief Return the UUID of the semiring one gate */
1555CREATE OR REPLACE FUNCTION gate_one() RETURNS UUID AS
1556$$
1557 SELECT public.uuid_generate_v5(provsql.uuid_ns_provsql(),'one');
1558$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
1559
1560/**
1561 * @brief Return the UUID of the value gate standing for the NULL value
1562 *
1563 * A constant, like gate_zero() and gate_one(); the gate itself is a
1564 * <tt>value</tt> gate that displays as <tt>NULL</tt>. Its UUID is what
1565 * tells it apart from the value gate of the string <tt>'NULL'</tt>; the
1566 * seed <tt>'null'</tt> is no <tt>'value' || TEXT</tt>, so no actual value
1567 * shares it.
1568 */
1569CREATE OR REPLACE FUNCTION gate_null() RETURNS UUID AS
1570$$
1571 SELECT public.uuid_generate_v5(provsql.uuid_ns_provsql(),'null');
1572$$ LANGUAGE SQL IMMUTABLE PARALLEL SAFE;
1573
1574/** @} */
1575
1576/** @defgroup semiring_operations Semiring operations
1577 * Functions that build provenance circuit gates for semiring operations.
1578 * These are called internally by the query rewriter.
1579 *
1580 * They are declared @c IMMUTABLE: each derives its gate UUID
1581 * deterministically from its arguments (a @c uuid5 content address) and
1582 * the @c create_gate write at that address is idempotent, so the token a
1583 * call returns is a pure function of its inputs. The marking matters for
1584 * parallelism: PL/pgSQL runs a non-volatile function's inner SPI
1585 * read-only, so the per-row builders the rewriter injects into a scan do
1586 * not call @c CommandCounterIncrement -- which would raise "cannot start
1587 * commands during a parallel operation" once the enclosing statement has
1588 * gone parallel. A @c VOLATILE builder both blocks that parallel plan and
1589 * loses the query-wide speed-up.
1590 * @{
1591 */
1592
1593/**
1594 * @brief Create a times (product) gate from multiple provenance tokens
1595 *
1596 * Filters out NULL and one-gates; returns gate_one() if all tokens
1597 * are trivial, or a single token if only one remains.
1598 *
1599 * When the surviving multiset is one for which this session planted a
1600 * certified equivalent (see @c plant_canonical; the reachability rewriter
1601 * does so for self-join conjunctions of reachability tokens, see
1602 * @c plant_reach_cover), the planted gate is returned. The ordinary
1603 * order-dependent recipe is used otherwise, so ordinary times gates (and
1604 * their formula rendering) are untouched.
1605 *
1606 * Implemented in C (<tt>gate_builders.c</tt>). The cost is declared as that
1607 * of a PL/pgSQL function, which this function was: the planner then keeps
1608 * evaluating it after the cheaper conditions, and the plans of rewritten
1609 * queries, on which the order of the children of a ⊕ depends, stay the same.
1610 */
1611CREATE OR REPLACE FUNCTION provenance_times(VARIADIC tokens UUID[])
1612 RETURNS UUID AS
1613 'provsql','provenance_times' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
1614
1615/**
1616 * @brief Create a monus (difference) gate from two provenance tokens
1617 *
1618 * Implements m-semiring monus. Returns token1 if token2 is NULL
1619 * (used for LEFT OUTER JOIN semantics in the EXCEPT rewriting).
1620 *
1621 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
1622 * PL/pgSQL function it was, so that plans stay the same.
1623 */
1624CREATE OR REPLACE FUNCTION provenance_monus(token1 UUID, token2 UUID)
1625 RETURNS UUID AS
1626 'provsql','provenance_monus' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
1627
1628/**
1629 * @brief Create a project gate for where-provenance tracking
1630 *
1631 * Records the mapping between input and output attribute positions.
1632 *
1633 * @param token child provenance token
1634 * @param positions array encoding attribute position mappings
1635 *
1636 * Implemented in C (<tt>gate_builders.c</tt>): the gate is created together
1637 * with what it records, in one unanswered message.
1639CREATE OR REPLACE FUNCTION provenance_project(token UUID, VARIADIC positions INT[])
1640 RETURNS UUID AS
1641 'provsql','provenance_project' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
1642
1643/**
1644 * @brief Create an equijoin gate for where-provenance tracking
1645 *
1646 * @param token child provenance token
1647 * @param pos1 attribute index in the first relation
1648 * @param pos2 attribute index in the second relation
1649 *
1650 * Implemented in C (<tt>gate_builders.c</tt>): the gate is created together
1651 * with what it records, in one unanswered message.
1652 */
1653CREATE OR REPLACE FUNCTION provenance_eq(token UUID, pos1 INT, pos2 INT)
1654 RETURNS UUID AS
1655 'provsql','provenance_eq' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
1656
1657/**
1658 * @brief Create a plus (sum) gate from an array of provenance tokens
1659 *
1660 * Filters out NULL and zero-gates; returns gate_zero() if all tokens
1661 * are trivial, or a single token if only one remains. When the
1662 * multiset is one for which this session planted a certified gate
1663 * computing the same sum (see @c plant_canonical), that gate is returned.
1664 * This is how the bounded-hop reachability route keeps the natural
1665 * hop-discarding query on the linear evaluation route: it plants, for a
1666 * vertex's per-length tokens, a certified gate over its native
1667 * within-bound circuit. Otherwise the ordinary order-dependent recipe
1668 * is used, so ordinary plus gates (and their formula rendering) are
1669 * untouched.
1670 */
1671CREATE OR REPLACE FUNCTION provenance_plus(tokens UUID[])
1672 RETURNS UUID AS
1673 'provsql','provenance_plus' LANGUAGE C COST 100 STRICT PARALLEL SAFE IMMUTABLE;
1674
1675/**
1676 * @brief Declare the working table of a recursive CTE, just (re)created
1677 * (internal)
1678 *
1679 * Gates planted from now on belong to it; those planted for the table of
1680 * the same name it replaces, and for working tables that no longer exist,
1681 * are forgotten.
1682 *
1683 * @param work_name name of the temporary working table
1684 */
1685CREATE OR REPLACE FUNCTION planted_scope(work_name TEXT)
1686 RETURNS VOID AS
1687 'provsql','planted_scope' LANGUAGE C STRICT;
1688
1689/**
1690 * @brief Plant a certified gate in place of a sum or a product (internal)
1691 *
1692 * Creates a @p kind gate with the single child @p target at the canonical
1693 * address of the multiset @p tokens -- the v5 UUID of
1694 * @c 'plus-canonical{sorted tokens}' or @c 'times-canonical{…}', a recipe under which nothing else
1695 * creates gates -- and remembers the address in this session: while the
1696 * working table @p work_name exists, @c provenance_plus /
1697 * @c provenance_times given that very multiset return the planted gate.
1698 * The tokens are row tokens of the working table, a temporary table, so
1699 * the sum or product is computed by the session that planted, never by a
1700 * parallel worker; the store is not consulted, and sessions that planted
1701 * nothing pay nothing.
1702 *
1703 * @param work_name working table the tokens belong to
1704 * @param kind 'plus' or 'times'
1705 * @param tokens the multiset the planted gate stands for
1706 * @param target root of the certified circuit
1707 * @param info1 first info of the planted gate
1708 * @param info2 second info of the planted gate
1709 * @return the address of the planted gate
1710 */
1711CREATE OR REPLACE FUNCTION plant_canonical(
1712 work_name TEXT, kind TEXT, tokens UUID[], target UUID,
1713 info1 INT, info2 INT DEFAULT 0)
1714 RETURNS UUID AS
1715 'provsql','plant_canonical' LANGUAGE C STRICT;
1717/**
1718 * @brief Address of the @c fixpoint gate reading component @p i of the
1719 * equation system @p sys (internal)
1720 *
1721 * Content-addressed like every other gate, from the system and the
1722 * index, so that evaluation, having solved a system, can name each of its
1723 * components (see @c provenance_evaluate_compiled's solution cache).
1724 */
1725CREATE OR REPLACE FUNCTION fixpoint_token(sys UUID, i INT) RETURNS UUID AS
1726$$
1727 SELECT public.uuid_generate_v5(provsql.uuid_ns_provsql(),
1728 'fixpoint:' || sys::TEXT || ':' || i::TEXT);
1729$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE;
1730
1731/**
1732 * @brief The token of each tuple of the equation system @p sys (internal)
1733 *
1734 * Tuples outside every cycle of the system get their right-hand side
1735 * rebuilt over the tokens of the tuples they read, as a fixpoint iteration
1736 * would build it; the tuples of each cyclic component a @c fixpoint gate
1737 * over a system of their own. See @c fix_system.cpp.
1738 *
1739 * @param sys a @c fixsystem gate, with one unknown and one right-hand
1740 * side per tuple
1741 * @return the token of each tuple, in the order of the unknowns
1742 */
1743CREATE OR REPLACE FUNCTION resolve_fix_system(sys UUID) RETURNS UUID[] AS
1744 'provsql','resolve_fix_system' LANGUAGE C STRICT VOLATILE;
1745
1746/**
1747 * @brief Driver for provenance over recursive queries (WITH RECURSIVE),
1748 * as an equation system (internal)
1749 *
1750 * Invoked by the planner hook (@c lower_recursive_cte in @c provsql.c) when
1751 * it lowers a recursive CTE with @c UNION whose body touches
1752 * provenance-tracked relations; the hook deparses the CTE body to SQL and
1753 * scans, in place of the CTE, the table this function fills. Instead of
1754 * unrolling the fixpoint round after round, it records the recursion as one
1755 * equation per derived tuple, x_t = f_t(x), and leaves the value of the
1756 * tuples derived through themselves to evaluation time, where the semiring
1757 * is known:
1758 *
1759 * 1. the derived tuples are computed by PostgreSQL's own recursion, with
1760 * provenance tracking off;
1761 * 2. the working table is loaded with them, each carrying a fresh unknown
1762 * (a @c fixvar gate) as its token;
1763 * 3. the CTE body is run once over that table, through ProvSQL's normal
1764 * rewriting: the token it gives a tuple is the right-hand side f_t of
1765 * its equation, an ordinary circuit over the input tokens and the
1766 * unknowns. A row this round derives that plain recursion did not --
1767 * absent from the database as it is, present in other worlds, as the
1768 * null-padded row of an outer join -- is a tuple of the recursion too:
1769 * it is added with an unknown of its own, and the round run again,
1770 * until it derives no new row;
1771 * 4. a @c fixsystem gate gathers the unknowns and the right-hand sides,
1772 * and @c resolve_fix_system gives each tuple its token: the ordinary
1773 * circuit a fixpoint iteration would reach, for a tuple derived
1774 * through no cycle; a @c fixpoint gate over its cyclic component's own
1775 * system otherwise.
1776 *
1777 * The recursion thus costs plain SQL's rounds plus one, and the circuit
1778 * one round of derivations, whatever the data's cycles; whether a cyclic
1779 * component has a value is decided by the semiring evaluating it (see
1780 * @c GenericCircuit::solveFixSystem): every absorptive semiring, and those
1781 * with a star (counting with an infinite count, min-plus with negative
1782 * cycles, why- and which-provenance); @c sr_formula renders the equations.
1783 *
1784 * This function has no @c SET @c search_path on purpose: @p body_sql is
1785 * the caller's deparsed query and must resolve relation names in the
1786 * caller's path.
1787 *
1788 * @param body_sql the recursive CTE body, e.g.
1789 * @c 'SELECT 1 UNION SELECT e.dst FROM edge e JOIN reach r ON e.src=r.node'
1790 * @param work_name the working relation name @p body_sql references
1791 * @param colnames comma-separated user columns
1792 * @param coldef column definitions for the working table
1793 */
1794CREATE OR REPLACE FUNCTION eval_recursive_system(
1795 body_sql TEXT,
1796 work_name TEXT,
1797 colnames TEXT,
1798 coldef TEXT)
1799 RETURNS VOID AS
1800$$
1801DECLARE
1802 seed UUID := public.uuid_generate_v4();
1803 active TEXT := current_setting('provsql.active');
1804 joincond TEXT;
1805 ncols TEXT;
1806 wcols TEXT;
1807 added bigint;
1808 known bigint := 0;
1809 rounds INT := 0;
1810 xs UUID[];
1811 fs UUID[];
1812 sys UUID;
1813BEGIN
1814 EXECUTE format('DROP TABLE IF EXISTS %I', work_name);
1815 DROP TABLE IF EXISTS provsql_rec_new;
1816 DROP TABLE IF EXISTS provsql_rec_eq;
1817
1818 EXECUTE format('CREATE TEMP TABLE %I (%s, provsql UUID) ON COMMIT DROP',
1819 work_name, coldef);
1820 PERFORM provsql.planted_scope(work_name);
1821 EXECUTE format('CREATE TEMP TABLE provsql_rec_new (LIKE %I) ON COMMIT DROP',
1822 work_name);
1823
1824 -- Match two tables on the TEXT form of the user columns: null-safe
1825 -- like IS NOT DISTINCT FROM, but hashable, which a column-wise
1826 -- IS NOT DISTINCT FROM is not (it would make this a nested loop).
1827 SELECT string_agg('n.' || trim(c), ', '), string_agg('w.' || trim(c), ', ')
1828 INTO ncols, wcols
1829 FROM unnest(string_to[](colnames, ',')) AS c;
1830 joincond := format('ROW(%s)::TEXT = ROW(%s)::TEXT', ncols, wcols);
1831 EXECUTE 'CREATE TEMP TABLE provsql_rec_eq (tid tid, i bigint, x UUID) '
1832 'ON COMMIT DROP';
1833
1834 -- 1. The derived tuples, by plain recursion.
1835 PERFORM set_config('provsql.active', 'off', true);
1836 EXECUTE format(
1837 'INSERT INTO %1$I(%2$s) WITH RECURSIVE %1$I(%2$s) AS (%3$s) '
1838 'SELECT %2$s FROM %1$I',
1839 work_name, colnames, body_sql);
1840
1841 LOOP
1842 -- 2. One unknown for each tuple that has none yet.
1843 PERFORM set_config('provsql.active', 'off', true);
1844 EXECUTE format(
1845 'INSERT INTO provsql_rec_eq '
1846 'SELECT ctid, %2$s + i, public.uuid_generate_v5(%1$L, ''x'' || (%2$s + i)) '
1847 'FROM (SELECT ctid, row_number() OVER () AS i FROM %3$I '
1848 ' WHERE provsql IS NULL) t',
1849 seed, known, work_name);
1850 EXECUTE format(
1851 'UPDATE %I w SET provsql = e.x FROM provsql_rec_eq e '
1852 'WHERE w.ctid = e.tid AND w.provsql IS NULL',
1853 work_name);
1854 PERFORM provsql.create_gate(e.x, 'fixvar')
1855 FROM provsql_rec_eq e WHERE e.i > known;
1856 SELECT coalesce(max(i), 0) INTO known FROM provsql_rec_eq;
1857 PERFORM set_config('provsql.active', active, true);
1858
1859 -- 3. One round over the unknowns: each tuple's right-hand side.
1860 EXECUTE 'TRUNCATE provsql_rec_new';
1861 EXECUTE format('INSERT INTO provsql_rec_new(%s) %s', colnames, body_sql);
1862
1863 -- The round may derive rows plain recursion does not: a row that is
1864 -- absent from the database as it is but present in other worlds, which
1865 -- ProvSQL keeps for its provenance (the null-padded row of an outer
1866 -- join, ...). Those are tuples of the recursion too, with equations of
1867 -- their own, and what derives from them as well: add them and run the
1868 -- round again, until it derives no new row. With no such row, which is
1869 -- the usual case, the round runs once.
1870 PERFORM set_config('provsql.active', 'off', true);
1871 EXECUTE format(
1872 'INSERT INTO %1$I(%2$s) SELECT %3$s FROM provsql_rec_new n '
1873 'WHERE NOT EXISTS (SELECT 1 FROM %1$I w WHERE %4$s)',
1874 work_name, colnames, ncols, joincond);
1875 GET DIAGNOSTICS added = ROW_COUNT;
1876 EXIT WHEN added = 0;
1877 rounds := rounds + 1;
1878 IF rounds > 100000 THEN
1879 RAISE EXCEPTION 'ProvSQL: the rows this recursion derives in other '
1880 'worlds than the database as it is do not stop '
1881 'growing';
1882 END IF;
1883 END LOOP;
1884
1885 -- 4. The system, and each tuple's component of its solution.
1886 EXECUTE format(
1887 'SELECT array_agg(e.x ORDER BY e.i), '
1888 'array_agg(coalesce(n.provsql, provsql.gate_zero()) ORDER BY e.i) '
1889 'FROM provsql_rec_eq e JOIN %I w ON w.provsql = e.x '
1890 'LEFT JOIN provsql_rec_new n ON %s',
1891 work_name, joincond) INTO xs, fs;
1892 IF xs IS NOT NULL THEN
1893 sys := public.uuid_generate_v5(seed, 'system');
1894 PERFORM provsql.create_gate(sys, 'fixsystem', xs || fs);
1895 -- Each tuple's token: rebuilt over the others' where it is derived
1896 -- through no cycle, a fixpoint gate over its cyclic component's own
1897 -- system otherwise.
1898 -- Unnested with its index, so that each row reads its own token and
1899 -- not a copy of the whole array.
1900 EXECUTE format(
1901 'UPDATE %I w SET provsql = t.tok '
1902 'FROM provsql_rec_eq e '
1903 'JOIN unnest(provsql.resolve_fix_system(%L)) WITH ORDINALITY AS t(tok, i) '
1904 'ON t.i = e.i '
1905 'WHERE w.provsql = e.x',
1906 work_name, sys);
1907 END IF;
1908 PERFORM set_config('provsql.active', active, true);
1909END
1910$$ LANGUAGE plpgsql SET client_min_messages = warning;
1911
1912/**
1913 * @brief Drive a @c UNION @c ALL recursion, one round per bag of derivations
1914 *
1915 * The bag recursion is not a fixpoint over a set: its rounds are
1916 * @c M0 @c = @c q0 and @c M(i+1) @c = @c q1 over @c Mi -- the PREVIOUS round,
1917 * not what has been derived so far -- and its answer is the bag union of every
1918 * round, which ends when a round derives nothing. Each tuple of it is one
1919 * derivation, annotated by the product along that derivation, and two
1920 * derivations of the same tuple are two rows and are not merged: that is what
1921 * distinguishes it from @c UNION, whose driver (@c eval_recursive_system)
1922 * sums the derivations of a tuple into one row.
1923 *
1924 * @c work_name holds the previous round, which the recursive term reads by the
1925 * name of the CTE; @c all_name accumulates the answer and is what the query
1926 * reads. Ending on an empty round is SQL's own rule, so a recursion PostgreSQL
1927 * runs to completion ends here too, and one it does not is caught by
1928 * @p max_iter as before.
1929 *
1930 * @param q0_sql the non-recursive term, as SQL
1931 * @param q1_sql the recursive term, reading @p work_name
1932 * @param work_name temp table of the previous round (the CTE's name)
1933 * @param all_name temp table accumulating the rounds
1934 * @param colnames comma-separated user column names
1935 * @param coldef column definitions ("name type, ...")
1936 * @param max_iter safety bound on the number of rounds
1938CREATE OR REPLACE FUNCTION eval_recursive_all(
1939 q0_sql TEXT,
1940 q1_sql TEXT,
1941 work_name TEXT,
1942 all_name TEXT,
1943 colnames TEXT,
1944 coldef TEXT,
1945 max_iter INT DEFAULT 1000)
1946 RETURNS VOID AS
1947$$
1948DECLARE
1949 iters INT := 0;
1950 new_count INT;
1951BEGIN
1952 EXECUTE format('DROP TABLE IF EXISTS %I', work_name);
1953 EXECUTE format('DROP TABLE IF EXISTS %I', all_name);
1954 DROP TABLE IF EXISTS provsql_rec_new;
1955
1956 EXECUTE format('CREATE TEMP TABLE %I (%s, provsql UUID) ON COMMIT DROP',
1957 work_name, coldef);
1958 EXECUTE format('CREATE TEMP TABLE %I (LIKE %I) ON COMMIT DROP',
1959 all_name, work_name);
1960 EXECUTE format('CREATE TEMP TABLE provsql_rec_new (LIKE %I) ON COMMIT DROP',
1961 work_name);
1962 PERFORM provsql.planted_scope(all_name);
1963
1964 -- The first round: the non-recursive term. A row it derives from no
1965 -- tracked relation gets no token from the INSERT: it is certain, and is
1966 -- given one, as the UNION driver gives it -- left NULL, a grouping above
1967 -- read it as nothing and the row as absent in every world.
1968 EXECUTE format('INSERT INTO provsql_rec_new(%s) %s', colnames, q0_sql);
1969 GET DIAGNOSTICS new_count = ROW_COUNT;
1970 UPDATE provsql_rec_new SET provsql = provsql.gate_one() WHERE provsql IS NULL;
1971
1972 LOOP
1973 EXIT WHEN new_count = 0; -- a round that derives nothing ends the answer
1974
1975 -- Every row of the round is an answer, kept as it is: a second derivation
1976 -- of a tuple is a second row, which is what UNION ALL says.
1977 EXECUTE format('INSERT INTO %1$I(%2$s) SELECT %2$s FROM provsql_rec_new',
1978 all_name, colnames);
1979
1980 -- The round becomes the relation the recursive term reads.
1981 EXECUTE format('TRUNCATE %I', work_name);
1982 EXECUTE format('INSERT INTO %1$I(%2$s) SELECT %2$s FROM provsql_rec_new',
1983 work_name, colnames);
1984
1985 iters := iters + 1;
1986 IF iters > max_iter THEN
1987 /* A bag recursion is defined when a round derives nothing; one whose
1988 * rounds do not end has no answer to give, in SQL either (PostgreSQL
1989 * runs it forever), so this is what the recursion means and not a limit
1990 * of the driver. */
1991 RAISE EXCEPTION 'ProvSQL: the rounds of this UNION ALL recursion do not '
1992 'end (after % of them): its answer is the rows of every '
1993 'round, which SQL itself does not reach either on such '
1994 'data', max_iter
1995 USING ERRCODE = 'feature_not_supported',
1996 DETAIL = 'provsql-reason: recursion-does-not-end; scope: deliberate';
1997 END IF;
1998
1999 EXECUTE format('TRUNCATE provsql_rec_new');
2000 EXECUTE format('INSERT INTO provsql_rec_new(%s) %s', colnames, q1_sql);
2001 GET DIAGNOSTICS new_count = ROW_COUNT;
2002 UPDATE provsql_rec_new SET provsql = provsql.gate_one() WHERE provsql IS NULL;
2003 END LOOP;
2004END
2005$$ LANGUAGE plpgsql SET client_min_messages = warning;
2006
2007/**
2008 * @brief Create a comparison gate for HAVING clause provenance
2010 * @param left_token provenance token for the left operand
2011 * @param comparison_op OID of the comparison operator
2012 * @param right_token provenance token for the right operand
2013 *
2014 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
2015 * PL/pgSQL function it was, so that plans stay the same.
2016 */
2017CREATE OR REPLACE FUNCTION provenance_cmp(
2018 left_token UUID,
2019 comparison_op OID,
2020 right_token UUID
2022RETURNS UUID AS
2023 'provsql','provenance_cmp' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
2024
2025/**
2026 * @brief The factors of a row annotation an aggregate comparison does not
2027 * subsume.
2028 *
2029 * A lifted comparison entails the existence of the group it ranges over, so it
2030 * supersedes that group's @c gate_delta instead of multiplying with it. This
2031 * reports which factors of @p tokens survive that supersede: a bare δ over the
2032 * compared group disappears, a @c times keeps its other factors, and anything
2033 * else -- an earlier comparison on the same group, an input -- is kept whole.
2034 */
2035CREATE FUNCTION cmp_surviving_factors(tokens UUID[], cmp UUID)
2036 RETURNS UUID[] AS
2037 'provsql', 'cmp_surviving_factors' LANGUAGE C PARALLEL SAFE STABLE;
2038
2040 * @brief Combine a lifted aggregate comparison with the row annotation it
2041 * supersedes only part of.
2042 *
2043 * @param cmp Gate of the lifted comparison.
2044 * @param tokens Row-annotation factors at the level owning the comparison.
2045 * @return @c cmp multiplied with whatever of @p tokens it does not subsume.
2046 */
2047CREATE OR REPLACE FUNCTION provenance_cmp_times(cmp UUID, tokens UUID[])
2048 RETURNS UUID AS
2049$$
2050DECLARE
2051 kept UUID[];
2052BEGIN
2053 kept := provsql.cmp_surviving_factors(tokens, cmp);
2054 IF kept IS NULL OR array_length(kept, 1) IS NULL THEN
2055 RETURN cmp;
2056 END IF;
2057 RETURN provsql.provenance_times(VARIADIC kept || cmp);
2058END
2059$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
2060
2061/**
2062 * @brief Create an arithmetic gate over scalar-valued provenance children
2063 *
2064 * Builds a deterministic @c gate_arith from an operator tag and an
2065 * ordered list of children. The tag is one of the @c provsql_arith_op
2066 * ENUM values declared in @c src/provsql_utils.h
2067 * (@c PLUS=0, @c TIMES=1, @c MINUS=2, @c DIV=3, @c NEG=4) and is
2068 * stored in the gate's @c info1 field. Children must be UUIDs of
2069 * scalar-producing gates (@c gate_rv, @c gate_value, or another
2070 * @c gate_arith). The token UUID is derived deterministically from
2071 * @p op and @p children so identical sub-expressions share their gate.
2072 *
2073 * @param op Operator tag (@c provsql_arith_op).
2074 * @param children Ordered list of child gate UUIDs.
2075 * @return UUID of the (possibly pre-existing) @c gate_arith.
2077 * Implemented in C (<tt>gate_builders.c</tt>): the gate is created together
2078 * with what it records, in one unanswered message.
2079 */
2080CREATE OR REPLACE FUNCTION provenance_arith(
2081 op INTEGER,
2082 children UUID[]
2083)
2084RETURNS UUID AS
2085 'provsql','provenance_arith' LANGUAGE C COST 100 STRICT PARALLEL SAFE IMMUTABLE;
2086
2087/**
2088 * @brief Create a guarded-selection gate over scalar (RV) children.
2089 *
2090 * Builds a deterministic @c gate_case from the flattened wire list
2091 * @c [guard_1, value_1, ..., guard_k, value_k, default] (odd length): the
2092 * value of the first guard event that holds, else the default (first-match
2093 * semantics). Each guard is a Boolean event token (a @c gate_cmp or Boolean
2094 * combination); each value and the default are scalar-producing gates
2095 * (@c gate_rv, @c gate_value, @c gate_arith, another @c gate_case, ...). The
2096 * token UUID is derived deterministically from @p children so identical
2097 * @c CASE expressions share their gate.
2098 *
2099 * @param children Flattened guard/value wires ending with the default
2100 * (@c array_length must be odd and @c >= 1).
2101 * @return UUID of the (possibly pre-existing) @c gate_case.
2102 */
2103CREATE OR REPLACE FUNCTION provenance_case(
2104 children UUID[]
2105)
2106RETURNS UUID AS
2107$$
2108DECLARE
2109 case_token UUID;
2110BEGIN
2111 IF array_length(children, 1) IS NULL OR array_length(children, 1) % 2 = 0 THEN
2112 RAISE EXCEPTION 'provenance_case expects an odd number of children '
2113 '(guard/value pairs followed by a default), got %',
2114 coalesce(array_length(children, 1), 0);
2115 END IF;
2116 case_token := public.uuid_generate_v5(
2117 uuid_ns_provsql(),
2118 concat('case', children::TEXT)
2119 );
2120 PERFORM create_gate(case_token, 'case', children);
2121 RETURN case_token;
2122END
2123$$ LANGUAGE plpgsql
2124 SET search_path=provsql,pg_temp,public
2125 SECURITY DEFINER
2126 IMMUTABLE
2127 PARALLEL SAFE
2128 STRICT;
2129
2130/** @} */
2131
2132/** @defgroup semiring_evaluation Semiring evaluation
2133 * Functions for evaluating provenance circuits over semirings,
2134 * both user-defined (via function references) and compiled (built-in).
2135 * @{
2137
2138/**
2139 * @brief Evaluate provenance using a compiled (built-in) semiring
2140 *
2141 * This C function handles semiring evaluation entirely in C++ for
2142 * better performance. The semiring is specified by name.
2143 *
2144 * @param token provenance token to evaluate
2145 * @param token2value mapping table from tokens to semiring values
2146 * @param semiring name of the compiled semiring (e.g., "formula", "counting")
2147 * @param element_one identity element of the semiring
2148 */
2149CREATE OR REPLACE FUNCTION provenance_evaluate_compiled(
2150 token UUID,
2151 token2value REGCLASS,
2152 semiring TEXT,
2153 element_one ANYELEMENT)
2154RETURNS ANYELEMENT AS
2155 'provsql', 'provenance_evaluate_compiled' LANGUAGE C PARALLEL SAFE STABLE;
2156
2157
2158/**
2159 * @brief Evaluate provenance over a user-defined semiring (PL/pgSQL version)
2160 *
2161 * Recursively walks the provenance circuit and evaluates each gate
2162 * using the provided semiring operations. This is the generic version
2163 * that accepts semiring operations as function references.
2164 *
2165 * @param token provenance token to evaluate
2166 * @param token2value mapping table from tokens to semiring values
2167 * @param element_one identity element of the semiring
2168 * @param value_type OID of the semiring value type
2169 * @param plus_function semiring addition (aggregate)
2170 * @param times_function semiring multiplication (aggregate)
2171 * @param monus_function semiring monus (binary), or NULL
2172 * @param delta_function δ-semiring operator, or NULL
2173 */
2174CREATE OR REPLACE FUNCTION provenance_evaluate(
2175 token UUID,
2176 token2value REGCLASS,
2177 element_one ANYELEMENT,
2178 value_type REGTYPE,
2179 plus_function REGPROC,
2180 times_function REGPROC,
2181 monus_function REGPROC,
2182 delta_function REGPROC)
2183 RETURNS ANYELEMENT AS
2184$$
2185DECLARE
2186 gate_type PROVENANCE_GATE;
2187 result ALIAS FOR $0;
2188 children UUID[];
2189-- cmp_value ANYELEMENT;
2190-- temp_result ANYELEMENT;
2191 value_text TEXT;
2192BEGIN
2193 SELECT get_gate_type(token) INTO gate_type;
2194
2195 IF gate_type IS NULL THEN
2196 RETURN NULL;
2197
2198 ELSIF gate_type = 'input' THEN
2199 EXECUTE format('SELECT value FROM %s WHERE provenance=%L', token2value, token)
2200 INTO result;
2201 IF result IS NULL THEN
2202 result := element_one;
2203 END IF;
2204 ELSIF gate_type = 'mulinput' THEN
2205 SELECT concat('{',(get_children(token))[1]::TEXT,'=',(get_infos(token)).info1,'}')
2206 INTO result;
2207 ELSIF gate_type='update' THEN
2208 EXECUTE format('SELECT value FROM %s WHERE provenance=%L',token2value,token) INTO result;
2209 IF result IS NULL THEN
2210 result:=element_one;
2211 END IF;
2212 ELSIF gate_type = 'plus' THEN
2213 EXECUTE format('SELECT %s(provsql.provenance_evaluate(t,%L,%L::%s,%L,%L,%L,%L,%L)) FROM unnest(get_children(%L)) AS t',
2214 plus_function, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function, token)
2215 INTO result;
2216
2217 ELSIF gate_type = 'times' THEN
2218 EXECUTE format('SELECT %s(provsql.provenance_evaluate(t,%L,%L::%s,%L,%L,%L,%L,%L)) FROM unnest(get_children(%L)) AS t',
2219 times_function, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function, token)
2220 INTO result;
2221
2222 ELSIF gate_type = 'monus' THEN
2223 IF monus_function IS NULL THEN
2224 RAISE EXCEPTION USING MESSAGE='Provenance with negation evaluated over a semiring without monus function',
2225 DETAIL = 'provsql-reason: semiring-no-monus; scope: deliberate';
2226 ELSE
2227 EXECUTE format('SELECT %s(a1,a2) FROM (SELECT provsql.provenance_evaluate(c[1],%L,%L::%s,%L,%L,%L,%L,%L) AS a1, ' ||
2228 'provsql.provenance_evaluate(c[2],%L,%L::%s,%L,%L,%L,%L,%L) AS a2 FROM get_children(%L) c) tmp',
2229 monus_function, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function,
2230 token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function, token)
2231 INTO result;
2232 END IF;
2233
2234 ELSIF gate_type = 'eq' THEN
2235 EXECUTE format('SELECT provsql.provenance_evaluate((get_children(%L))[1],%L,%L::%s,%L,%L,%L,%L,%L)',
2236 token, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function)
2237 INTO result;
2238
2239/* elsif gate_type = 'cmp' then
2241 EXECUTE format('SELECT provsql.provenance_evaluate((get_children(%L))[1],%L,%L::%s,%L,%L,%L,%L,%L)',
2242 token, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function)
2243 INTO temp_result;
2244
2245 EXECUTE format('SELECT get_extra((get_children(%L))[2])', token)
2246 INTO cmp_value;
2247
2248 IF temp_result::TEXT = cmp_value::TEXT THEN
2249 SELECT concat('{',temp_result::TEXT,'=',cmp_value::TEXT,'}')
2250 INTO result;
2251 ELSE
2252 RETURN gate_zero()
2253 */
2254
2255
2257 ELSIF gate_type = 'delta' THEN
2258 IF delta_function IS NULL THEN
2259 RAISE EXCEPTION USING MESSAGE='Provenance with aggregation evaluated over a semiring without delta function',
2260 DETAIL = 'provsql-reason: semiring-no-delta; scope: deliberate';
2261 ELSE
2262 EXECUTE format('SELECT %I(a) FROM (SELECT provsql.provenance_evaluate((get_children(%L))[1],%L,%L::%s,%L,%L,%L,%L,%L) AS a) tmp',
2263 delta_function, token, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function)
2264 INTO result;
2265 END IF;
2266
2267 ELSIF gate_type = 'zero' THEN
2268 EXECUTE format('SELECT %I(a) FROM (SELECT %L::%I AS a WHERE FALSE) temp', plus_function, element_one, value_type)
2269 INTO result;
2270
2271 ELSIF gate_type = 'one' THEN
2272 EXECUTE format('SELECT %L::%I', element_one, value_type)
2273 INTO result;
2274
2275 ELSIF gate_type = 'project' THEN
2276 EXECUTE format('SELECT provsql.provenance_evaluate((get_children(%L))[1],%L,%L::%s,%L,%L,%L,%L,%L)',
2277 token, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function)
2278 INTO result;
2279
2280 ELSIF gate_type = 'annotation' THEN
2281 -- Transparent single-child wrapper (carries the inversion-free certificate
2282 -- / per-input order keys in extra, inert for every semiring): evaluate
2283 -- through to the child, like 'project'.
2284 EXECUTE format('SELECT provsql.provenance_evaluate((get_children(%L))[1],%L,%L::%s,%L,%L,%L,%L,%L)',
2285 token, token2value, element_one, value_type, value_type, plus_function, times_function, monus_function, delta_function)
2286 INTO result;
2287
2288 ELSE
2289 RAISE EXCEPTION USING MESSAGE='provenance_evaluate cannot be called on formulas using ' || gate_type || ' gates; use compiled semirings instead',
2290 DETAIL = 'provsql-reason: evaluate-gate-kind; scope: gap';
2291 END IF;
2292
2293 RETURN result;
2294END
2295$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
2296
2297
2299 * @brief Evaluate provenance over a user-defined semiring (C version)
2300 *
2301 * Optimized C implementation of provenance_evaluate. Infers the
2302 * value type from element_one. Monus and delta functions are optional.
2303 *
2304 * @param token provenance token to evaluate
2305 * @param token2value mapping table from tokens to semiring values
2306 * @param element_one identity element of the semiring
2307 * @param plus_function semiring addition (aggregate)
2308 * @param times_function semiring multiplication (aggregate)
2309 * @param monus_function semiring monus, or NULL if not needed
2310 * @param delta_function δ-semiring operator, or NULL if not needed
2311 */
2312CREATE OR REPLACE FUNCTION provenance_evaluate(
2313 token UUID,
2314 token2value REGCLASS,
2315 element_one ANYELEMENT,
2316 plus_function REGPROC,
2317 times_function REGPROC,
2318 monus_function REGPROC = NULL,
2319 delta_function REGPROC = NULL)
2320 RETURNS ANYELEMENT AS
2321 'provsql','provenance_evaluate' LANGUAGE C STABLE;
2323/** @} */
2324
2325/** @defgroup circuit_introspection Circuit introspection
2326 * Functions for examining the structure of provenance circuits,
2327 * used by visualization and where-provenance features.
2328 * @{
2329 */
2330
2331/** @brief Row type for sub_circuit_with_desc results */
2332CREATE TYPE GATE_WITH_DESC AS (f UUID, t UUID, gate_type PROVENANCE_GATE, desc_str CHARACTER VARYING, infos INTEGER[], extra TEXT);
2333
2334/**
2335 * @brief Return the sub-circuit reachable from a token, with descriptions
2336 *
2337 * Recursively traverses the provenance circuit from the given token and
2338 * returns all edges together with input gate descriptions from the
2339 * mapping table.
2340 *
2341 * @param token root provenance token
2342 * @param token2desc mapping table providing descriptions for input gates
2343 */
2344CREATE OR REPLACE FUNCTION sub_circuit_with_desc(
2345 token UUID,
2346 token2desc REGCLASS) RETURNS SETOF GATE_WITH_DESC AS
2347$$
2348BEGIN
2349 RETURN QUERY EXECUTE
2350 'WITH RECURSIVE transitive_closure(f,t,gate_type) AS (
2351 SELECT $1,t,provsql.get_gate_type($1) FROM unnest(provsql.get_children($1)) AS t
2352 UNION ALL
2353 SELECT p1.t,u,provsql.get_gate_type(p1.t) FROM transitive_closure p1, unnest(provsql.get_children(p1.t)) AS u)
2354 SELECT *, ARRAY[(get_infos(f)).info1, (get_infos(f)).info2], get_extra(f) FROM (
2355 SELECT f::UUID,t::UUID,gate_type,NULL FROM transitive_closure
2356 UNION ALL
2357 SELECT p2.provenance::UUID as f, NULL::UUID, ''input'', CAST (p2.value AS varchar) FROM transitive_closure p1 JOIN ' || token2desc || ' AS p2
2358 ON p2.provenance=t
2359 UNION ALL
2360 SELECT provenance::UUID as f, NULL::UUID, ''input'', CAST (value AS varchar) FROM ' || token2desc || ' WHERE provenance=$1
2361 ) t'
2362 USING token LOOP;
2363 RETURN;
2364END
2365$$ LANGUAGE plpgsql STABLE PARALLEL RESTRICTED;
2366
2367/**
2368 * @brief Identify which table and how many columns a provenance token belongs to
2369 *
2370 * Searches all provenance-tracked tables for a row matching the given
2371 * token and returns the table name and column count.
2372 *
2373 * @param token provenance token to look up
2374 * @param table_name (OUT) the table containing this token
2375 * @param nb_columns (OUT) number of non-provenance columns in that table
2376 */
2377CREATE OR REPLACE FUNCTION identify_token(
2378 token UUID, OUT table_name REGCLASS, OUT nb_columns INTEGER) AS
2379$$
2380DECLARE
2381 t RECORD;
2382 found UUID;
2383BEGIN
2384 table_name:=NULL;
2385 nb_columns:=-1;
2386 FOR t IN
2387 SELECT pg_namespace.nspname, relname, attrelid,
2388 (SELECT count(*) FROM pg_attribute a2 WHERE a2.attrelid=a1.attrelid AND attnum>0 AND atttypid<>0)-1 c
2389 FROM pg_attribute a1 JOIN pg_type ON atttypid=pg_type.oid
2390 JOIN pg_class ON attrelid=pg_class.oid
2391 JOIN pg_namespace ON relnamespace=pg_namespace.oid
2392 WHERE typname='UUID' AND relkind='r'
2393 AND nspname<>'provsql'
2394 AND attname='provsql'
2395 LOOP
2396 -- Qualified by its schema, which need not be on the search_path. A
2397 -- table another session drops, or removes the provenance of, between the
2398 -- catalog read and the query is skipped rather than failing the lookup;
2399 -- so is one another session holds exclusively (a DROP, an ALTER under
2400 -- way): waiting for it, while holding the tables read so far, could
2401 -- deadlock with a statement dropping several of them.
2402 BEGIN
2403 EXECUTE format('LOCK TABLE %I.%I IN ACCESS SHARE MODE NOWAIT',
2404 t.nspname, t.relname);
2405 EXECUTE format('SELECT provsql FROM %I.%I WHERE provsql=%L LIMIT 1',
2406 t.nspname, t.relname, token) INTO found;
2407 EXCEPTION WHEN undefined_table OR undefined_column OR lock_not_available THEN
2408 CONTINUE;
2409 END;
2410 IF found IS NOT NULL THEN
2411 table_name:=t.attrelid::REGCLASS;
2412 nb_columns:=t.c;
2413 EXIT;
2414 END IF;
2415 END LOOP;
2416END
2417$$ LANGUAGE plpgsql STRICT;
2418
2420 * @brief Return the sub-circuit for where-provenance computation
2421 *
2422 * Similar to sub_circuit_with_desc but resolves input gates to their
2423 * source table and column count for where-provenance evaluation.
2424 */
2425CREATE OR REPLACE FUNCTION sub_circuit_for_where(token UUID)
2426 RETURNS TABLE(f UUID, t UUID, gate_type PROVENANCE_GATE, table_name REGCLASS, nb_columns INTEGER, infos INTEGER[], extra TEXT) AS
2427$$
2428 -- A comparison (cmp) is a condition on whether a row is there, which
2429 -- where-provenance ignores: the walk stops at it, leaving it a leaf, and
2430 -- does not enter the aggregates and values it compares.
2431 WITH RECURSIVE transitive_closure(f,t,idx,gate_type) AS (
2432 SELECT $1,t,id,provsql.get_gate_type($1) FROM unnest(provsql.get_children($1)) WITH ORDINALITY AS a(t,id)
2433 WHERE provsql.get_gate_type($1) <> 'cmp'
2434 UNION ALL
2435 SELECT p1.t,u,id,provsql.get_gate_type(p1.t) FROM transitive_closure p1, unnest(provsql.get_children(p1.t)) WITH ORDINALITY AS a(u, id)
2436 WHERE provsql.get_gate_type(p1.t) <> 'cmp'
2437 ) SELECT f, t, gate_type, table_name, nb_columns, ARRAY[(get_infos(f)).info1, (get_infos(f)).info2], get_extra(f) FROM (
2438 -- One row per distinct (parent, child, child-position) edge. The
2439 -- recursive closure (UNION ALL) re-emits a gate's outgoing edges once per
2440 -- path that reaches it, so a *shared* non-input gate would otherwise be
2441 -- reported with duplicate edges; DISTINCT on the (f,t,idx) triple
2442 -- collapses those while keeping genuine repeated children (same f,t,
2443 -- different idx, e.g. a self-product). Without this, a shared
2444 -- single-child gate (notably an inversion-free order-marker annotation)
2445 -- gets its child wired k times in the where-circuit -> the locator sets
2446 -- are duplicated k-fold.
2447 SELECT DISTINCT f, t::UUID, idx, gate_type, NULL::REGCLASS AS table_name, NULL::INTEGER AS nb_columns FROM transitive_closure
2448 UNION ALL
2449 -- The leaves, with their own type: an input is traced back to its
2450 -- relation, any other leaf (an aggregation over no row, a constant)
2451 -- is reported as what it is, for where_provenance to refuse by type.
2452 SELECT DISTINCT leaf, NULL::UUID, NULL::INT, leaf_type, i.table_name, i.nb_columns FROM (SELECT DISTINCT t AS leaf, provsql.get_gate_type(t) AS leaf_type FROM transitive_closure WHERE t NOT IN (SELECT f FROM transitive_closure)) leaves LEFT JOIN LATERAL provsql.identify_token(leaf) i ON leaf_type = 'input'
2453 UNION ALL
2454 SELECT DISTINCT $1, NULL::UUID, NULL::INT, leaf_type, i.table_name, i.nb_columns FROM (SELECT provsql.get_gate_type($1) AS leaf_type WHERE $1 NOT IN (SELECT f FROM transitive_closure)) root LEFT JOIN LATERAL provsql.identify_token($1) i ON leaf_type = 'input'
2455 ) t
2456 -- order each parent's edges by child position so the where-circuit's TIMES
2457 -- concatenation reproduces the column order (input rows have idx NULL).
2458 ORDER BY f, idx
2459$$
2460LANGUAGE sql;
2461
2462/**
2463 * @brief BFS expansion of a provenance circuit, capped at @p max_depth
2464 *
2465 * Returns one row per (parent, child) edge in the BFS-bounded subgraph
2466 * rooted at @p root, plus one row for the root with <tt>parent</tt> and
2467 * <tt>child_pos</tt> NULL. Provenance circuits are DAGs, so a child gate
2468 * may have several parents within the bound; each such edge is reported
2469 * as a separate row, so callers must deduplicate on <tt>node</tt> if they
2470 * need a one-row-per-node view.
2471 *
2472 * <tt>depth</tt> is the node's longest-path distance from @p root
2473 * within the depth bound (the standard circuit-depth notion), so for
2474 * an edge (parent, child) it is the case that
2475 * <tt>child.depth &gt;= parent.depth + 1</tt>, except at the
2476 * <tt>max_depth</tt> truncation frontier. A node at
2477 * <tt>depth = max_depth</tt> is not
2478 * expanded; callers can detect a partial expansion by comparing
2479 * <tt>provsql.get_children</tt> length against the number of outgoing
2480 * edges reported.
2481 *
2482 * <tt>info1</tt> and <tt>info2</tt> are the INTEGER values recorded on
2483 * the gate when it was created, formatted as TEXT; their meaning is
2484 * gate-type-specific.
2485 *
2486 * @param root root provenance token
2487 * @param max_depth maximum BFS depth (default 8)
2488 */
2489CREATE OR REPLACE FUNCTION circuit_subgraph(root UUID, max_depth INT DEFAULT 8)
2490 RETURNS TABLE(node UUID, parent UUID, child_pos INT, gate_type TEXT, info1 TEXT, info2 TEXT, depth INT) AS
2491$$
2492 WITH RECURSIVE bfs(node, parent, child_pos, depth) AS (
2493 SELECT root, NULL::UUID, NULL::INT, 0
2494 UNION ALL
2495 SELECT c.t, b.node, c.idx::INT, b.depth + 1
2496 FROM bfs b
2497 CROSS JOIN LATERAL unnest(provsql.get_children(b.node))
2498 WITH ORDINALITY AS c(t, idx)
2499 WHERE b.depth < max_depth
2500 ),
2501 -- Each node's canonical depth is its longest-path distance from the
2502 -- root (the standard circuit-depth notion: the longest chain of
2503 -- gates separating the node from the output). The recursive CTE
2504 -- enumerates paths up to @c max_depth, so MAX over those is the
2505 -- longest path of length at most @c max_depth.
2506 node_depth AS (
2507 SELECT node, MAX(depth) AS depth FROM bfs GROUP BY node
2508 ),
2509 -- All distinct (parent, child, child_pos) triples seen during the BFS.
2510 -- A child reached from k parents within the bound contributes k rows.
2511 -- Self-joins (times(x, x)) contribute one row per child position.
2512 edges AS (
2513 SELECT DISTINCT parent, node AS child, child_pos
2514 FROM bfs WHERE parent IS NOT NULL
2515 )
2516 SELECT
2517 d.node,
2518 e.parent,
2519 e.child_pos,
2520 provsql.get_gate_type(d.node)::TEXT,
2521 i.info1::TEXT,
2522 i.info2::TEXT,
2523 d.depth
2524 FROM node_depth d
2525 LEFT JOIN edges e ON e.child = d.node
2526 LEFT JOIN LATERAL provsql.get_infos(d.node) i ON TRUE
2527 ORDER BY d.depth, d.node, e.parent;
2528$$ LANGUAGE sql STABLE PARALLEL SAFE;
2529
2531 * @brief BFS subgraph of the IN-MEMORY simplified circuit rooted at @p root.
2532 *
2533 * Same row shape as @ref circuit_subgraph plus an inline @c extra
2534 * column, but built from the @c GenericCircuit returned by
2535 * @c getGenericCircuit -- i.e. AFTER @c provsql.simplify_on_load
2536 * passes (RangeCheck, ...) have rewritten any decidable @c gate_cmp
2537 * into Bernoulli @c gate_input / @c gate_zero / @c gate_one leaves.
2538 * Lets a renderer show the user what the evaluator actually sees,
2539 * without mutating the persisted DAG.
2540 *
2541 * Returns @c jsonb (an array of objects) rather than @c SETOF RECORD
2542 * to keep the C++ implementation free of SRF / @c FuncCallContext
2543 * boilerplate; callers either consume the array directly or expand
2544 * it via @c jsonb_array_elements.
2545 *
2546 * @param root Root provenance token.
2547 * @param max_depth Maximum BFS depth (default 8).
2548 */
2549CREATE OR REPLACE FUNCTION simplified_circuit_subgraph(
2550 root UUID, max_depth INT DEFAULT 8) RETURNS jsonb
2551 AS 'provsql','simplified_circuit_subgraph'
2552 LANGUAGE C STABLE PARALLEL SAFE;
2553
2555 * @brief Empirical histogram of a scalar sub-circuit
2556 *
2557 * Returns a jsonb array of @c {bin_lo, bin_hi, count} objects covering
2558 * the observed @c [min, max] range of @p bins equal-width samples from
2559 * the sub-circuit rooted at @p token. Sample count is taken from
2560 * @c provsql.rv_mc_samples; pinning @c provsql.monte_carlo_seed makes
2561 * the result reproducible.
2562 *
2563 * Accepted root gate types are the scalar ones: @c gate_value (Dirac
2564 * at the constant, single bin), @c gate_rv (sampled from the leaf's
2565 * distribution), and @c gate_arith (sampled by recursing through the
2566 * arithmetic DAG, with shared @c gate_rv leaves correctly correlated
2567 * within an iteration). Any other gate type raises.
2568 *
2569 * @param token Root provenance token of a scalar sub-circuit.
2570 * @param bins Number of equal-width histogram bins (default 30).
2571 * @param prov Conditioning event (defaults to @c gate_one() = no
2572 * conditioning). When non-trivial, the histogram is
2573 * over the conditional distribution recovered by
2574 * rejection sampling on the joint circuit with @p token.
2575 */
2576CREATE OR REPLACE FUNCTION rv_histogram(
2577 token UUID, bins INT DEFAULT 30, prov UUID DEFAULT gate_one())
2578 RETURNS jsonb
2579 AS 'provsql','rv_histogram'
2580 LANGUAGE C VOLATILE PARALLEL SAFE;
2581
2582/**
2583 * @brief Sample the closed-form PDF and CDF of a (possibly truncated)
2584 * scalar distribution.
2585 *
2586 * Returns @c {"pdf": [{x, p}, ...], "cdf": [{x, p}, ...]} with @p samples
2587 * evenly-spaced points spanning the distribution's natural display
2588 * range (intersected with the conditioning event's interval when
2589 * @c prov is non-trivial). Used by ProvSQL Studio's Distribution
2590 * profile panel to overlay the analytical curve on the empirical
2591 * histogram from :sqlfunc:`rv_histogram` -- the simplifier's
2592 * analytical wins (e.g. @c c·Exp(λ) folding to @c Exp(λ/c)) become
2593 * visible as a smooth curve riding over the MC-sampled bars.
2595 * Returns @c NULL when the root sub-circuit is not a closed-form
2596 * shape (V1: only bare @c gate_rv of Normal / Uniform / Exponential
2597 * / INTEGER-Erlang). The frontend reads @c NULL as "skip overlay"
2598 * without erroring, so the caller can dispatch this in parallel with
2599 * @c rv_histogram regardless of the underlying shape.
2600 *
2601 * @param token Scalar gate token (random_variable's UUID).
2602 * @param samples Number of (x, p) points; must be >= 2.
2603 * @param prov Conditioning event (defaults to @c gate_one() = no
2604 * conditioning). When non-trivial, the curves are
2605 * over the truncated distribution.
2606 */
2607CREATE OR REPLACE FUNCTION rv_analytical_curves(
2608 token UUID, samples INT DEFAULT 100, prov UUID DEFAULT gate_one())
2609 RETURNS jsonb
2610 AS 'provsql','rv_analytical_curves'
2611 LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
2612
2613/**
2614 * @brief Draw conditional Monte Carlo samples from a scalar gate.
2615 *
2616 * Returns up to @c n samples of the scalar value at @c token; when
2617 * @c prov is not the trivial @c gate_one() event, draws are accepted
2618 * only on iterations where @c prov evaluates true (rejection
2619 * sampling). Shared @c gate_rv leaves between @c token and @c prov
2620 * are loaded into a single joint circuit so the indicator's draw
2621 * and the value's draw share their per-iteration state.
2622 *
2623 * @param token Scalar sub-circuit root.
2624 * @param n Number of accepted samples to attempt.
2625 * @param prov Conditioning event (defaults to @c gate_one() = no
2626 * conditioning).
2627 *
2628 * Emits a @c NOTICE when the conditional acceptance rate yields fewer
2629 * than @c n samples within the @c provsql.rv_mc_samples budget so the
2630 * caller can choose to widen the budget.
2631 */
2632CREATE OR REPLACE FUNCTION rv_sample(
2633 token UUID, n INTEGER, prov UUID DEFAULT gate_one())
2634 RETURNS SETOF float8
2635 AS 'provsql','rv_sample'
2636 LANGUAGE C VOLATILE PARALLEL SAFE;
2637
2638/**
2639 * @brief Resolve an input gate UUID back to its source row
2640 *
2641 * Searches every provenance-tracked relation for a row whose
2642 * <tt>provsql</tt> column equals @p UUID and returns the relation's
2643 * REGCLASS together with the row encoded as JSONB. Returns zero
2644 * rows when @p UUID is not the provenance token of any tracked row,
2645 * including when it identifies an internal gate (<tt>plus</tt>,
2646 * <tt>times</tt>, ...) rather than an input.
2647 *
2648 * Ordinarily exactly one row is returned, but if the same UUID
2649 * happens to appear as a <tt>provsql</tt> value in several tracked
2650 * tables, all matches are returned.
2652 * @param UUID token to resolve
2653 */
2654CREATE OR REPLACE FUNCTION resolve_input(UUID UUID)
2655 RETURNS TABLE(relation REGCLASS, row_data JSONB) AS
2657DECLARE
2658 t RECORD;
2659 rd JSONB;
2660 -- ProvSQL's rewriter unconditionally appends a provsql column to the
2661 -- targetlist of any SELECT reading from a tracked relation; capture and
2662 -- discard it here rather than disabling the rewriter for the whole call.
2663 ign UUID;
2664BEGIN
2665 FOR t IN
2666 SELECT c.oid::REGCLASS AS regc, ns.nspname, c.relname
2667 FROM pg_attribute a
2668 JOIN pg_class c ON a.attrelid = c.oid
2669 JOIN pg_namespace ns ON c.relnamespace = ns.oid
2670 JOIN pg_type ty ON a.atttypid = ty.oid
2671 WHERE a.attname = 'provsql'
2672 AND ty.typname = 'UUID'
2673 AND c.relkind = 'r'
2674 AND ns.nspname <> 'provsql'
2675 AND a.attnum > 0
2676 LOOP
2677 -- A table another session drops, removes the provenance of, or holds
2678 -- exclusively is skipped (see identify_token).
2679 BEGIN
2680 EXECUTE format('LOCK TABLE %I.%I IN ACCESS SHARE MODE NOWAIT',
2681 t.nspname, t.relname);
2682 FOR rd, ign IN
2683 EXECUTE format(
2684 'SELECT to_jsonb(t) - ''provsql'', t.provsql FROM %I.%I AS t WHERE provsql = $1',
2685 t.nspname, t.relname)
2686 USING UUID
2687 LOOP
2688 relation := t.regc;
2689 row_data := rd;
2690 RETURN NEXT;
2691 END LOOP;
2692 EXCEPTION WHEN undefined_table OR undefined_column OR lock_not_available THEN
2693 CONTINUE;
2694 END;
2695 END LOOP;
2696END
2697$$ LANGUAGE plpgsql VOLATILE;
2698
2699/** @} */
2701/** @defgroup agg_token_type Type for the result of aggregate queries
2702 *
2703 * Custom type <tt>AGG_TOKEN</tt> for a provenance semimodule value, to
2704 * be used in attributes that are computed as a result of aggregation.
2705 * As for provenance tokens, this is simply a UUID, but this UUID is
2706 * displayed in a specific way (as the result of the aggregation
2707 * followed by a "(*)") to help with readability.
2708 *
2709 * The TEXT output is controlled by the
2710 * <tt>provsql.aggtoken_text_as_uuid</tt> GUC. By default it is off and
2711 * the cell renders as <tt>"value (*)"</tt>. When set to on (typical
2712 * for UI layers such as ProvSQL Studio), the cell renders as the
2713 * underlying UUID instead, so the caller can click through to the
2714 * provenance circuit; the value side is then recovered via
2715 * <tt>provsql.agg_token_value_text(UUID)</tt>.
2716 *
2717 * @{
2718 */
2719
2720CREATE TYPE AGG_TOKEN;
2721
2722/** @brief Input function for the AGG_TOKEN type (parses TEXT representation) */
2723CREATE OR REPLACE FUNCTION agg_token_in(CSTRING)
2724 RETURNS AGG_TOKEN
2725 AS 'provsql','agg_token_in' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
2726
2727/**
2728 * @brief Output function for the AGG_TOKEN type
2729 *
2730 * Default: produces the human-friendly @c "value (*)" form, where
2731 * @c value is the running aggregate state.
2732 *
2733 * When the @c provsql.aggtoken_text_as_uuid GUC is on, returns the
2734 * underlying provenance UUID instead. UI layers (notably ProvSQL
2735 * Studio) flip this on per session so aggregate cells expose the
2736 * circuit root UUID for click-through; the @c "value (*)" display
2737 * string is recovered via @c provsql.agg_token_value_text(UUID).
2738 *
2739 * Marked STABLE rather than IMMUTABLE because the chosen output
2740 * shape now depends on a GUC that the same session can flip at
2741 * runtime.
2742 */
2743CREATE OR REPLACE FUNCTION agg_token_out(AGG_TOKEN)
2744 RETURNS CSTRING
2745 AS 'provsql','agg_token_out' LANGUAGE C STABLE STRICT PARALLEL SAFE;
2746
2747/** @brief Cast an AGG_TOKEN to its TEXT representation */
2748CREATE OR REPLACE FUNCTION agg_token_cast(AGG_TOKEN)
2749 RETURNS TEXT
2750 AS 'provsql','agg_token_cast' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
2751
2752CREATE TYPE AGG_TOKEN (
2753 internallength = 117,
2754 input = agg_token_in,
2755 output = agg_token_out,
2756 alignment = char
2757);
2758
2759/** @brief Extract the UUID from an AGG_TOKEN (implicit cast to UUID) */
2760CREATE OR REPLACE FUNCTION agg_token_uuid(aggtok AGG_TOKEN)
2761 RETURNS UUID AS
2762$$
2763BEGIN
2764 RETURN agg_token_cast(aggtok)::UUID;
2765END
2766$$ LANGUAGE plpgsql STRICT SET search_path=provsql,pg_temp,public SECURITY DEFINER IMMUTABLE PARALLEL SAFE;
2767
2768/** @brief Implicit PostgreSQL cast from AGG_TOKEN to UUID (delegates to agg_token_uuid()) */
2769CREATE CAST (AGG_TOKEN AS UUID) WITH FUNCTION agg_token_uuid(AGG_TOKEN) AS IMPLICIT;
2770
2771/** @brief Whether @p token carries a value but records none in the actual
2772 * data: an aggregate over no row there, a value gate without a constant.
2773 *
2774 * Told apart from a value this reading does not take -- a TIMESTAMP, which
2775 * @c agg_gate_value gives up on because it reads numbers, or a random
2776 * variable, which has no value in the actual data at all -- because the two
2777 * call for opposite answers in @c agg_guard_holds: a comparison with a side
2778 * that HAS no value there does not hold, while one whose value is simply not
2779 * read leaves the truth undecided (internal use). */
2780CREATE OR REPLACE FUNCTION agg_gate_value_missing(token UUID)
2781 RETURNS BOOLEAN AS
2783DECLARE
2784 gt provsql.PROVENANCE_GATE := provsql.get_gate_type(token);
2785 ch UUID[];
2786BEGIN
2787 IF gt IN ('agg', 'arith', 'value') THEN
2788 RETURN provsql.get_extra(token) IS NULL;
2789 ELSIF gt = 'semimod' THEN
2790 ch := provsql.get_children(token);
2791 RETURN array_length(ch, 1) = 2
2792 AND provsql.get_extra(ch[2]) IS NULL;
2793 ELSIF gt = 'conditioned' THEN
2794 ch := provsql.get_children(token);
2795 RETURN array_length(ch, 1) >= 1
2796 AND provsql.agg_gate_value_missing(ch[1]);
2797 END IF;
2798 /* Any other gate: nothing is claimed */
2799 RETURN false;
2800END
2801$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE
2802 SET search_path=provsql,pg_temp,public;
2803
2804/**
2805 * @brief The TEXT a value-carrying gate records in the actual data, whatever
2806 * type it is of.
2807 *
2808 * @c agg_gate_value reads that TEXT as a number and gives up on anything else.
2809 * A Boolean aggregate's value is one of those: @c "true" is no number, and yet
2810 * @c = and @c <> compare it, which is what the guards of a
2811 * @c "bool_or(flag)::INT" need. Descends the value-carrying gates as
2812 * @c agg_gate_value does, and answers @c NULL for a gate that records no value
2813 * of its own (internal use).
2815CREATE OR REPLACE FUNCTION agg_gate_value_text(token UUID)
2816 RETURNS TEXT AS
2817$$
2818DECLARE
2819 gt provsql.PROVENANCE_GATE := provsql.get_gate_type(token);
2820BEGIN
2821 IF gt IN ('agg', 'arith', 'value') THEN
2822 RETURN provsql.get_extra(token);
2823 ELSIF gt = 'semimod' THEN
2824 RETURN provsql.agg_gate_value_text((provsql.get_children(token))[2]);
2825 ELSIF gt = 'conditioned' THEN
2826 RETURN provsql.agg_gate_value_text((provsql.get_children(token))[1]);
2827 END IF;
2828 RETURN NULL;
2829END
2830$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE
2831 SET search_path=provsql,pg_temp,public;
2832
2833/**
2834 * @brief Deterministic truth of a Boolean guard sub-circuit over aggregate
2835 * comparisons, evaluated in the actual world (all input tuples present).
2836 *
2837 * Guards are the shapes @c having_Expr_to_provenance_cmp mints: @c cmp gates
2838 * over aggregate-valued children (comparison-operator OID in @c info1),
2839 * @c times / @c plus combinations (AND / OR, with negation pushed into the
2840 * comparison operators), and the @c one / @c zero indicators of regular
2841 * (aggregate-free) conditions. Uses Kleene three-valued logic: returns
2842 * @c NULL on any other gate shape, or when an operand's deterministic value
2843 * cannot be resolved.
2844 */
2845CREATE OR REPLACE FUNCTION agg_guard_holds(token UUID)
2846 RETURNS BOOLEAN AS
2847$$
2848DECLARE
2849 gt PROVENANCE_GATE := get_gate_type(token);
2850 ch UUID[];
2851 opname TEXT;
2852 l NUMERIC;
2853 r NUMERIC;
2854 lt TEXT;
2855 rt TEXT;
2856 all_true BOOLEAN;
2857 any_true BOOLEAN;
2858 any_null BOOLEAN;
2859BEGIN
2860 IF gt = 'one' THEN
2861 RETURN true;
2862 ELSIF gt = 'zero' THEN
2863 RETURN false;
2864 ELSIF gt IN ('times', 'plus') THEN
2865 SELECT bool_and(h), bool_or(h), bool_or(h IS NULL)
2866 INTO all_true, any_true, any_null
2867 FROM (SELECT provsql.agg_guard_holds(c) AS h
2868 FROM unnest(get_children(token)) AS c) AS s;
2869 IF gt = 'times' THEN
2870 -- AND: false dominates unknown (bool_and skips NULL inputs, so it is
2871 -- false exactly when some child is false).
2872 RETURN CASE WHEN NOT all_true THEN false
2873 WHEN any_null THEN NULL
2874 ELSE true END;
2875 ELSE
2876 -- OR: true dominates unknown.
2877 RETURN CASE WHEN any_true THEN true
2878 WHEN any_null THEN NULL
2879 ELSE false END;
2880 END IF;
2881 ELSIF gt = 'cmp' THEN
2882 ch := get_children(token);
2883 l := agg_gate_value(ch[1]);
2884 r := agg_gate_value(ch[2]);
2885 IF l IS NULL OR r IS NULL THEN
2886 /* A side with no value in the actual data -- an aggregate over no row
2887 * there, as a group kept only for other worlds is -- makes the
2888 * comparison unknown there, which is what provenance_cmp annotates
2889 * zero: it does not hold. A side whose value this reading does not
2890 * take, a TIMESTAMP or a random variable, leaves the truth undecided
2891 * instead: the value is there, only not as a number. */
2892 IF agg_gate_value_missing(ch[1]) OR agg_gate_value_missing(ch[2]) THEN
2893 RETURN false;
2894 END IF;
2895 /* A Boolean pair: the value is there, only not as a number, and = / <>
2896 * compare it all the same -- the guards a "bool_or(flag)::INT" lowers to
2897 * are these. The literals are checked against a list rather than cast
2898 * inside an exception block, which a parallel worker cannot afford, for
2899 * the reason agg_gate_value reads its number with a regex. */
2900 lt := lower(agg_gate_value_text(ch[1]));
2901 rt := lower(agg_gate_value_text(ch[2]));
2902 IF lt IN ('true', 'false', 't', 'f') AND
2903 rt IN ('true', 'false', 't', 'f') THEN
2904 SELECT oprname INTO opname
2905 FROM pg_catalog.pg_operator WHERE oid = (get_infos(token)).info1;
2906 IF opname = '=' THEN
2907 RETURN lt::BOOLEAN = rt::BOOLEAN;
2908 ELSIF opname = '<>' THEN
2909 RETURN lt::BOOLEAN <> rt::BOOLEAN;
2910 END IF;
2911 END IF;
2912 RETURN NULL;
2913 END IF;
2914 SELECT oprname INTO opname
2915 FROM pg_catalog.pg_operator WHERE oid = (get_infos(token)).info1;
2916 RETURN CASE opname
2917 WHEN '<' THEN l < r
2918 WHEN '<=' THEN l <= r
2919 WHEN '=' THEN l = r
2920 WHEN '<>' THEN l <> r
2921 WHEN '>=' THEN l >= r
2922 WHEN '>' THEN l > r
2923 END;
2924 ELSIF gt IN ('input', 'delta', 'monus', 'project', 'eq', 'mulinput',
2925 'assumed', 'annotation') THEN
2926 /* An ordinary provenance expression, not a comparison: the guard a
2927 * COALESCE over an aggregate lowers to is the NullTest one,
2928 * delta(+Kn) for IS NOT NULL and 1 - +Kn for IS NULL. Such a guard
2929 * holds in the actual data exactly when its Boolean provenance does
2930 * with every input row present, which is what plain_truth reads. */
2931 RETURN provsql.plain_truth(token);
2932 END IF;
2933 RETURN NULL;
2935$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE
2936 SET search_path=provsql,pg_temp,public;
2937
2939 * @brief Deterministic (actual-world) scalar value of an aggregate-carrying
2940 * gate.
2941 *
2942 * Resolves the value an aggregate expression takes on the actual data -- the
2943 * value an @c AGG_TOKEN display cell carries: @c agg / @c arith gates RECORD
2944 * it in @c extra (set by aggregate evaluation and @c agg_arith_make), a
2945 * @c value gate carries its constant, a @c semimod wraps a value gate, a
2946 * @c conditioned gate has its target's value, and a @c case gate selects the
2947 * first branch whose guard holds in the actual world (per
2948 * @c agg_guard_holds), else the default. Returns @c NULL when the gate is
2949 * not aggregate-carrying or the value cannot be resolved (e.g. a
2950 * non-NUMERIC aggregate).
2951 */
2952CREATE OR REPLACE FUNCTION agg_gate_value(token UUID)
2953 RETURNS NUMERIC AS
2954$$
2955DECLARE
2956 gt PROVENANCE_GATE := get_gate_type(token);
2957 ch UUID[];
2958 n INTEGER;
2959 holds BOOLEAN;
2960 extra TEXT;
2961BEGIN
2962 IF gt IN ('agg', 'arith', 'value') THEN
2963 /* Reading the TEXT as a number without a PL/pgSQL exception block, which
2964 * a parallel worker cannot afford: entering one starts a subtransaction,
2965 * and this function is called from the evaluator, which runs wherever the
2966 * query does (PostgreSQL 11 raises "cannot start subtransactions during a
2967 * parallel operation"). What is not the TEXT of a number is the value of
2968 * a non-NUMERIC aggregate (a min over TEXT, a TIMESTAMP), which this
2969 * reading does not take. */
2970 extra := get_extra(token);
2971 IF extra ~ '^\s*([-+]?([0-9]+\.?[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?|[Nn][Aa][Nn])\s*$' THEN
2972 RETURN extra::NUMERIC;
2973 END IF;
2974 RETURN NULL;
2975 ELSIF gt = 'semimod' THEN
2976 RETURN agg_gate_value((get_children(token))[2]);
2977 ELSIF gt = 'conditioned' THEN
2978 RETURN agg_gate_value((get_children(token))[1]);
2979 ELSIF gt = 'case' THEN
2980 ch := get_children(token);
2981 n := array_length(ch, 1);
2982 FOR i IN 1 .. (n - 1) / 2 LOOP
2983 holds := agg_guard_holds(ch[2 * i - 1]);
2984 IF holds IS NULL THEN
2985 RETURN NULL;
2986 ELSIF holds THEN
2987 RETURN agg_gate_value(ch[2 * i]);
2988 END IF;
2989 END LOOP;
2990 RETURN agg_gate_value(ch[n]);
2991 END IF;
2992 RETURN NULL;
2993END
2994$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE
2995 SET search_path=provsql,pg_temp,public;
2996
2997/**
2998 * @brief Recover the @c "value (*)" display string for an aggregation gate
2999 *
3000 * Companion helper to the @c provsql.aggtoken_text_as_uuid GUC. With
3001 * the GUC on, an @c AGG_TOKEN cell prints as the underlying provenance
3002 * UUID, which is convenient for tooling that wants to click through to
3003 * the circuit but loses the human-readable aggregate value. This
3004 * function takes such a UUID and returns the original @c "value (*)"
3005 * string by reading the gate's @c extra (set by aggregate evaluation
3006 * for @c agg gates, and by @c agg_arith_make for the @c arith gates
3007 * that AGG_TOKEN arithmetic mints); for the other aggregate-carrying
3008 * gates (@c case, @c conditioned, @c semimod, @c value) the value is
3009 * resolved through the circuit by @c agg_gate_value. Returns @c NULL
3010 * if @p token does not resolve to an aggregate-carrying gate.
3011 *
3012 * @param token UUID of an @c agg gate (typically obtained from an
3013 * @c AGG_TOKEN cell when @c aggtoken_text_as_uuid is on,
3014 * or via a manual UUID cast otherwise).
3015 */
3016CREATE OR REPLACE FUNCTION agg_token_value_text(token UUID)
3017 RETURNS TEXT AS
3018$$
3019 SELECT CASE
3020 -- agg gates: extra is set by aggregate evaluation, in the aggregate's own
3021 -- type, so it reads as it is.
3022 WHEN provsql.get_gate_type(token) = 'agg'
3023 THEN provsql.get_extra(token) || ' (*)'
3024 -- arith gates: extra is the value agg_arith_make computed, in NUMERIC
3025 -- whatever the expression's type, so it is read in that type -- a double
3026 -- precision result prints its 16 digits and not NUMERIC's twenty.
3027 WHEN provsql.get_gate_type(token) = 'arith'
3028 THEN CASE provsql.agg_token_value_type(token)
3029 WHEN 'float8'::REGTYPE::oid
3030 THEN (provsql.get_extra(token)::NUMERIC::float8)::TEXT || ' (*)'
3031 WHEN 'float4'::REGTYPE::oid
3032 THEN (provsql.get_extra(token)::NUMERIC::float4)::TEXT || ' (*)'
3033 ELSE provsql.get_extra(token) || ' (*)'
3034 END
3035 -- other aggregate-carrying gates: resolve the actual-world value
3036 -- through the circuit.
3037 WHEN provsql.get_gate_type(token) IN ('case', 'conditioned', 'semimod', 'value')
3038 THEN provsql.agg_gate_value(token)::TEXT || ' (*)'
3039 ELSE NULL
3040 END;
3041$$ LANGUAGE sql STABLE STRICT PARALLEL SAFE;
3042
3043/** @brief Cast an AGG_TOKEN to NUMERIC (extracts the aggregate value, loses provenance) */
3044CREATE OR REPLACE FUNCTION agg_token_to_numeric(AGG_TOKEN)
3045 RETURNS NUMERIC
3046 AS 'provsql','agg_token_to_numeric' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3047
3048/** @brief Cast an AGG_TOKEN to double precision (extracts the aggregate value, loses provenance) */
3049CREATE OR REPLACE FUNCTION agg_token_to_float8(AGG_TOKEN)
3050 RETURNS double precision
3051 AS 'provsql','agg_token_to_float8' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3052
3053/** @brief Cast an AGG_TOKEN to INTEGER (extracts the aggregate value, loses provenance) */
3054CREATE OR REPLACE FUNCTION agg_token_to_int4(AGG_TOKEN)
3055 RETURNS INTEGER
3056 AS 'provsql','agg_token_to_int4' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3057
3058/** @brief Cast an AGG_TOKEN to bigint (extracts the aggregate value, loses provenance) */
3059CREATE OR REPLACE FUNCTION agg_token_to_int8(AGG_TOKEN)
3060 RETURNS bigint
3061 AS 'provsql','agg_token_to_int8' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3062
3063/** @brief Cast an AGG_TOKEN to BOOLEAN (extracts the aggregate value, loses provenance) */
3064CREATE OR REPLACE FUNCTION agg_token_to_bool(AGG_TOKEN)
3065 RETURNS BOOLEAN
3066 AS 'provsql','agg_token_to_bool' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3067
3068/** @brief Cast an AGG_TOKEN to TEXT (extracts the aggregate value, loses provenance) */
3069CREATE OR REPLACE FUNCTION agg_token_to_text(AGG_TOKEN)
3070 RETURNS TEXT
3071 AS 'provsql','agg_token_to_text' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3072
3073/** @brief Assignment cast from AGG_TOKEN to NUMERIC (extracts the scalar
3074 * value, dropping provenance). ASSIGNMENT, not IMPLICIT: provenance-
3075 * preserving arithmetic on aggregates is provided by the native
3076 * AGG_TOKEN operators below, so an implicit NUMERIC coercion would only
3077 * silently steal `s + 1` away from them (and reroute it differently
3078 * depending on whether provsql is in search_path). Write `s::NUMERIC`
3079 * to opt into the lossy scalar. */
3080CREATE CAST (AGG_TOKEN AS NUMERIC) WITH FUNCTION agg_token_to_numeric(AGG_TOKEN) AS ASSIGNMENT;
3081
3082-- ---------------------------------------------------------------------
3083-- Arithmetic on aggregates (AGG_TOKEN)
3084--
3085-- Mirrors the random_variable arithmetic surface: the operators build a
3086-- `gate_arith` over the operand provenance UUIDs (via provenance_arith,
3087-- info1 = PROVSQL_ARITH_*), so the arithmetic is recorded symbolically
3088-- in the circuit and can be resolved when a comparison (gate_cmp) over
3089-- the result is evaluated. Unlike random_variable (a bare UUID), an
3090-- AGG_TOKEN also carries a running scalar value, so each operator
3091-- additionally computes the resulting value and bundles it back with the
3092-- new gate.
3093-- ---------------------------------------------------------------------
3094
3095/** @brief Running value of an AGG_TOKEN as NUMERIC, without the
3096 * provenance-loss warning the public cast emits (internal use). */
3097CREATE OR REPLACE FUNCTION agg_token_value(AGG_TOKEN)
3098 RETURNS NUMERIC
3099 AS 'provsql','agg_token_value' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3100
3101/** @brief Value of an AGG_TOKEN as TEXT, NULL for a NULL value, without the
3102 * provenance-loss warning the public cast emits: the sort key of an
3103 * ORDER BY on an aggregate result (internal use). */
3104CREATE FUNCTION agg_token_plain_text(AGG_TOKEN)
3105 RETURNS TEXT
3106 AS 'provsql','agg_token_plain_text' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3107
3108/** @brief The children of the aggregation gate @p token, one per
3109 * contribution, to explode an aggregate result into rows (a join on it,
3110 * @c explode_table). Only for @c choose(), whose value is one of its
3111 * contributions; any other aggregate is refused, its value being none of
3112 * them (@c count(*) contributes a 1 per row) (internal use). */
3113CREATE FUNCTION agg_token_explode_children(token UUID)
3114 RETURNS UUID[] AS
3115$$
3116BEGIN
3117 IF provsql.get_gate_type(token) <> 'agg' THEN
3118 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3119 MESSAGE = 'ProvSQL: only the result of an aggregate can be exploded '
3120 'into rows',
3121 DETAIL = 'provsql-reason: explode-not-an-aggregate; scope: deliberate';
3122 END IF;
3123 IF (provsql.get_infos(token)).info1 <>
3124 'provsql.choose(ANYELEMENT)'::regprocedure::oid THEN
3125 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3126 MESSAGE = format('ProvSQL: the result of %s() cannot be exploded into '
3127 'rows, one per value it aggregates: only that of '
3128 'choose() is one of them; compare it in a HAVING '
3129 'clause, or mark it plain() to read its plain value',
3130 (SELECT proname FROM pg_catalog.pg_proc
3131 WHERE oid = (provsql.get_infos(token)).info1)),
3132 DETAIL = 'provsql-reason: explode-rows-aggregate-kind; scope: gap';
3133 END IF;
3134 RETURN provsql.get_children(token);
3135END
3136$$ LANGUAGE plpgsql STABLE PARALLEL SAFE;
3137
3138/** @brief The values the aggregate result @p token takes over the possible
3139 * worlds, as TEXT, to explode that result into one row per value: the value
3140 * of an aggregate read as data (a GROUP BY key, a DISTINCT, an arm of a set
3141 * operation). The planner annotates the row of a value @c v with the
3142 * comparison gate @c [token @c = @c v], so that the rows of one group are
3143 * pairwise exclusive and exactly one of them is in each world where the
3144 * group is.
3145 *
3146 * A @c count() takes every number of its contributions, a @c min(), a
3147 * @c max() and a @c choose() one of their contributed values. Any other
3148 * aggregate is refused (SQLSTATE 0A000): the values of a @c sum() are its
3149 * subset sums, those of a @c string_agg() one per ordering, and reading
3150 * them off the contributions one by one would be wrong. A NULL
3151 * contribution is refused as well: whether the result is NULL is then a
3152 * value of its own, which a comparison cannot express (internal use). */
3153CREATE FUNCTION agg_possible_values(input ANYELEMENT,
3154 with_null BOOLEAN DEFAULT false)
3155 RETURNS TEXT[] AS
3156$$
3157DECLARE
3158 max_values CONSTANT INT := 1000; -- an explosion multiplies the rows
3159 token UUID;
3160 fn TEXT;
3161 ns TEXT;
3162 vals TEXT[];
3163 n INT;
3164 counted INT;
3165 first INT;
3166 sums NUMERIC[];
3167 one NUMERIC;
3168 scalar_agg BOOLEAN;
3169 arms UUID[];
3170 cv UUID;
3171 cvals TEXT[];
3172BEGIN
3173 /* The planner hands the aggregate result itself (an AGG_TOKEN), whatever
3174 * the type the query declares for that column. */
3175 IF pg_typeof(input) <> 'provsql.AGG_TOKEN'::REGTYPE THEN
3176 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3177 MESSAGE = 'ProvSQL: only the result of an aggregate can be exploded '
3178 'into one row per value it takes over the possible worlds',
3179 DETAIL = 'provsql-reason: explode-not-an-aggregate; scope: deliberate';
3180 END IF;
3181 token := input::UUID;
3182 IF provsql.get_gate_type(token) = 'case' THEN
3183 /* A guarded selection -- COALESCE(sum(x), 0), a CASE over aggregates --
3184 * takes the values of its arms, [guard_1, value_1, ..., default]: an
3185 * aggregate's own, or a constant's. Each arm is selected where its
3186 * aggregate has a value, so an aggregate arm offers no NULL. */
3187 arms := provsql.get_children(token);
3188 vals := ARRAY[]::TEXT[];
3189 FOR i IN 1 .. coalesce(array_length(arms, 1), 0) LOOP
3190 CONTINUE WHEN i % 2 = 1 AND i < array_length(arms, 1);
3191 CASE provsql.get_gate_type(arms[i])
3192 WHEN 'value' THEN
3193 /* gate_null(), the value of an aggregate with no contribution at
3194 * all, is never selected: its guard, that the aggregate has a value,
3195 * holds in no world. The guarded selections exploded here
3196 * (COALESCE onto a constant) are never NULL. */
3197 IF coalesce(provsql.get_extra(arms[i]), '') NOT IN ('', 'NULL') THEN
3198 vals := vals || provsql.get_extra(arms[i]);
3199 END IF;
3200 WHEN 'agg', 'case' THEN
3201 vals := vals || provsql.agg_possible_values(
3202 provsql.agg_token_make(arms[i], 0));
3203 ELSE
3204 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3205 MESSAGE = 'ProvSQL: an arithmetic expression over aggregate '
3206 'results cannot be exploded into one row per value it '
3207 'takes over the possible worlds',
3208 DETAIL = 'provsql-reason: explode-arithmetic; scope: gap';
3209 END CASE;
3210 END LOOP;
3211 vals := ARRAY(SELECT DISTINCT v FROM unnest(vals) AS v);
3212 IF array_length(vals, 1) > max_values THEN
3213 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3214 MESSAGE = format('ProvSQL: this expression over aggregate results '
3215 'takes more than %s values over the possible worlds, '
3216 'too many to explode it into one row per value',
3217 max_values),
3218 HINT = 'mark it plain() to read its plain value',
3219 DETAIL = 'provsql-reason: explode-too-many-values; scope: gap';
3220 END IF;
3221 RETURN ARRAY(SELECT v FROM unnest(vals) AS v
3222 ORDER BY v::NUMERIC NULLS LAST);
3223 END IF;
3224 IF provsql.get_gate_type(token) <> 'agg' THEN
3225 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3226 MESSAGE = 'ProvSQL: an arithmetic expression over aggregate results '
3227 'cannot be exploded into one row per value it takes over '
3228 'the possible worlds',
3229 DETAIL = 'provsql-reason: explode-arithmetic; scope: gap';
3230 END IF;
3231 SELECT p.proname, s.nspname INTO fn, ns
3232 FROM pg_catalog.pg_proc p
3233 JOIN pg_catalog.pg_namespace s ON s.oid = p.pronamespace
3234 WHERE p.oid = (provsql.get_infos(token)).info1;
3235
3236 vals := ARRAY(SELECT provsql.get_extra((provsql.get_children(sm))[2])
3237 FROM unnest(provsql.get_children(token)) AS sm);
3238 n := coalesce(array_length(vals, 1), 0);
3239 /* NULL is a value of the aggregate like any other -- the one it takes where
3240 * no row contributes, which an aggregation over the whole table reaches in
3241 * the world holding none of its rows (a grouped one has no row there at all).
3242 * Whether to offer it is the caller's to decide: the rewriting asks for it
3243 * only where it can annotate that row with the aggregate having no value,
3244 * and never for a count, which is 0 rather than NULL over no row. */
3245 scalar_agg := with_null;
3246
3247 IF (ns, fn) = ('pg_catalog', 'count') THEN
3248 /* A count contributes 1 per row it counts and 0 per row it does not -- a
3249 * row whose value is NULL, as the null-padded row of an outer join is --
3250 * so its values are the numbers of rows counted, up to how many there are
3251 * to count. Zero is one of them where a row that is not counted can be
3252 * the only one there, or where the aggregation is over the whole table; a
3253 * group of counted rows only has none of its rows in no world, a group
3254 * being no group without a row. */
3255 counted := (SELECT count(*) FROM unnest(vals) AS v
3256 WHERE v IS NOT NULL AND v <> '0');
3257 first := CASE WHEN (provsql.get_infos(token)).info2 < 0 OR counted < n
3258 THEN 0 ELSE 1 END;
3259 IF counted + 1 - first > max_values THEN
3260 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3261 MESSAGE = format('ProvSQL: the result of %s() aggregates %s rows, '
3262 'so it takes too many values over the possible '
3263 'worlds to explode it into one row per value',
3264 fn, n),
3265 HINT = 'mark it plain() to read its plain value',
3266 DETAIL = 'provsql-reason: explode-too-many-values; scope: gap';
3267 END IF;
3268 RETURN ARRAY(SELECT i::TEXT
3269 FROM generate_series(least(first, counted), counted) AS i);
3270 END IF;
3271
3272 IF (ns, fn) NOT IN (('pg_catalog', 'min'), ('pg_catalog', 'max'),
3273 ('pg_catalog', 'sum'), ('provsql', 'choose')) THEN
3274 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3275 MESSAGE = format('ProvSQL: the result of %s() cannot be exploded into '
3276 'one row per value it takes over the possible worlds: '
3277 'only count(), min(), max(), sum() and choose() have '
3278 'values that can be enumerated', fn),
3279 HINT = 'compare it in a HAVING clause, or mark it plain() to read its '
3280 'plain value',
3281 DETAIL = 'provsql-reason: explode-aggregate-kind; scope: gap';
3282 END IF;
3284 /* An aggregate of aggregate results -- sum(revenue) over a view of
3285 * totals -- has contributions that are no constants but aggregate results
3286 * themselves, each taking several values: their own (agg_possible_values
3287 * of their gate), a NULL among them contributing nothing. A sum takes the
3288 * subset sums choosing one value of each contribution there, a minimum
3289 * (maximum, choice) one of their values. The combinations no world
3290 * realises (two contributions that depend on each other) are emitted too,
3291 * and their rows have a provenance of zero. */
3292 IF EXISTS (SELECT 1 FROM unnest(provsql.get_children(token)) AS sm
3293 WHERE provsql.get_gate_type(sm) = 'semimod'
3294 AND provsql.get_gate_type((provsql.get_children(sm))[2])
3295 <> 'value') THEN
3296 sums := ARRAY[]::NUMERIC[];
3297 vals := ARRAY[]::TEXT[];
3298 FOR cv IN SELECT (provsql.get_children(sm))[2]
3299 FROM unnest(provsql.get_children(token)) AS sm
3300 WHERE provsql.get_gate_type(sm) = 'semimod' LOOP
3301 cvals := CASE WHEN provsql.get_gate_type(cv) = 'value'
3302 THEN ARRAY[provsql.get_extra(cv)]
3303 ELSE provsql.agg_possible_values(
3304 provsql.agg_token_make(cv, 0)) END;
3305 cvals := ARRAY(SELECT v FROM unnest(cvals) AS v
3306 WHERE coalesce(v, '') NOT IN ('', 'NULL'));
3307 IF (ns, fn) = ('pg_catalog', 'sum') THEN
3308 sums := ARRAY(SELECT DISTINCT s FROM
3309 (SELECT unnest(sums) AS s
3310 UNION ALL SELECT v::NUMERIC FROM unnest(cvals) AS v
3311 UNION ALL SELECT a + b::NUMERIC
3312 FROM unnest(sums) AS a, unnest(cvals) AS b)
3313 AS u);
3314 ELSE
3315 vals := ARRAY(SELECT DISTINCT v FROM
3316 (SELECT unnest(vals) AS v
3317 UNION ALL SELECT unnest(cvals)) AS u);
3318 END IF;
3319 IF coalesce(array_length(sums, 1), 0) > max_values
3320 OR coalesce(array_length(vals, 1), 0) > max_values THEN
3321 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3322 MESSAGE = format('ProvSQL: the result of %s() takes more than %s '
3323 'values over the possible worlds, too many to '
3324 'explode it into one row per value', fn,
3325 max_values),
3326 HINT = 'mark it plain() to read its plain value',
3327 DETAIL = 'provsql-reason: explode-too-many-values; scope: gap';
3328 END IF;
3329 END LOOP;
3330 IF (ns, fn) = ('pg_catalog', 'sum') THEN
3331 RETURN ARRAY(SELECT s::TEXT FROM unnest(sums) AS s ORDER BY s)
3332 || CASE WHEN scalar_agg THEN ARRAY[NULL::TEXT]
3333 ELSE ARRAY[]::TEXT[] END;
3334 END IF;
3335 RETURN ARRAY(SELECT v FROM unnest(vals) AS v ORDER BY v)
3336 || CASE WHEN scalar_agg THEN ARRAY[NULL::TEXT]
3337 ELSE ARRAY[]::TEXT[] END;
3338 END IF;
3339
3340 IF EXISTS (SELECT 1 FROM unnest(vals) AS v WHERE v IS NULL) THEN
3341 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3342 MESSAGE = format('ProvSQL: the result of %s() aggregates a NULL value, '
3343 'so it cannot be exploded into one row per value it '
3344 'takes over the possible worlds: a comparison with '
3345 'NULL does not say that the result is NULL', fn),
3346 DETAIL = 'provsql-reason: explode-null-value; scope: gap';
3347 END IF;
3348
3349 IF (ns, fn) = ('pg_catalog', 'sum') THEN
3350 /* The value of a sum is the sum of the rows that are there, so its values
3351 * are its subset sums, reached by adding the contributions one at a time,
3352 * equal sums collapsing (three rows of 1 take three values, not eight).
3353 * The empty subset is the NULL above, which a scalar aggregation takes and
3354 * a grouped one does not (a group without a row is no group). The planner only sends sums over an
3355 * INTEGER column here, whose subset sums the evaluator's own arithmetic
3356 * reaches exactly. */
3357 sums := ARRAY[]::NUMERIC[];
3358 FOREACH one IN ARRAY ARRAY(SELECT v::NUMERIC FROM unnest(vals) AS v) LOOP
3359 sums := ARRAY(SELECT DISTINCT s FROM
3360 (SELECT unnest(sums) AS s
3361 UNION ALL SELECT one
3362 UNION ALL SELECT unnest(sums) + one) AS u);
3363 IF array_length(sums, 1) > max_values THEN
3364 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3365 MESSAGE = format('ProvSQL: the result of %s() takes more than %s '
3366 'values over the possible worlds, too many to '
3367 'explode it into one row per value', fn,
3368 max_values),
3369 HINT = 'mark it plain() to read its plain value',
3370 DETAIL = 'provsql-reason: explode-too-many-values; scope: gap';
3371 END IF;
3372 END LOOP;
3373 RETURN ARRAY(SELECT s::TEXT FROM unnest(sums) AS s ORDER BY s)
3374 || CASE WHEN scalar_agg THEN ARRAY[NULL::TEXT]
3375 ELSE ARRAY[]::TEXT[] END;
3376 END IF;
3377
3378 IF n > max_values THEN
3379 RAISE EXCEPTION USING ERRCODE = 'feature_not_supported',
3380 MESSAGE = format('ProvSQL: the result of %s() aggregates %s rows, so '
3381 'it takes too many values over the possible worlds to '
3382 'explode it into one row per value', fn, n),
3383 HINT = 'mark it plain() to read its plain value',
3384 DETAIL = 'provsql-reason: explode-too-many-values; scope: gap';
3385 END IF;
3386
3387 /* One row per distinct contributed value: each is the minimum (maximum,
3388 * choice) of the world where only its own row is. */
3389 RETURN ARRAY(SELECT DISTINCT v FROM unnest(vals) AS v ORDER BY v)
3390 || CASE WHEN scalar_agg THEN ARRAY[NULL::TEXT]
3391 ELSE ARRAY[]::TEXT[] END;
3392END
3393$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE;
3395/** @brief Value of an AGG_TOKEN as TEXT, NULL for a NULL value, without the
3396 * provenance-loss warning of the public casts: the value of an aggregate
3397 * result read as a plain value where ProvSQL casts it (in a function, an
3398 * operator, a comparison), which the planner reports once as evaluated as
3399 * plain SQL (internal use). */
3400CREATE FUNCTION agg_token_frozen_value(AGG_TOKEN)
3401 RETURNS TEXT
3402 AS 'provsql','agg_token_plain_text' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
3403
3404/** @brief Bundle a provenance gate UUID with a running value into an
3405 * AGG_TOKEN (inverse of the agg_token_uuid / agg_token_value
3406 * accessors). */
3407CREATE OR REPLACE FUNCTION agg_token_make(tok UUID, val NUMERIC)
3408 RETURNS AGG_TOKEN AS
3409$$
3410 SELECT format('( %s , %s )', tok::TEXT, val::TEXT)::provsql.AGG_TOKEN;
3411$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE
3412 SET search_path=provsql,pg_temp,public;
3413
3414/** @brief Lift a scalar NUMERIC constant into a gate_value leaf and
3415 * return its UUID, so it can be a child of a gate_arith (the agg-side
3416 * analogue of as_random for random_variable). */
3417CREATE OR REPLACE FUNCTION agg_value_gate(v NUMERIC)
3418 RETURNS UUID AS
3419$$
3420DECLARE
3421 token UUID := public.uuid_generate_v5(
3422 provsql.uuid_ns_provsql(), concat('value', v::TEXT));
3423BEGIN
3424 PERFORM provsql.create_gate(token, 'value', NULL, NULL, NULL, v::TEXT);
3425 RETURN token;
3426END
3427$$ LANGUAGE plpgsql STRICT IMMUTABLE PARALLEL SAFE
3428 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
3429
3430/**
3431 * @brief The SQL type of the value an @c AGG_TOKEN carries.
3432 *
3433 * An @c agg gate holds the aggregate's own result type in @c info2, next to
3434 * the scalar flag in its top bit; an @c arith gate holds the result type of
3435 * the operation it stands for, put there by @c agg_arith_make. Every other
3436 * aggregate-carrying gate holds a value the rewriting computed in @c NUMERIC,
3437 * which is what it answers for them.
3438 */
3439CREATE OR REPLACE FUNCTION agg_token_value_type(token UUID)
3440 RETURNS oid AS
3441$$
3442 SELECT CASE provsql.get_gate_type(token)
3443 WHEN 'agg' THEN (i.info2 & 2147483647)::oid
3444 WHEN 'arith' THEN CASE WHEN coalesce(i.info2, 0) = 0
3445 THEN 'NUMERIC'::REGTYPE::oid ELSE i.info2::oid END
3446 ELSE 'NUMERIC'::REGTYPE::oid
3447 END
3448 FROM provsql.get_infos(token) i;
3449$$ LANGUAGE sql STABLE STRICT PARALLEL SAFE
3450 SET search_path=provsql,pg_temp,public;
3451
3452/**
3453 * @brief The type the operation @p op over @p children answers in, by SQL's
3454 * own NUMERIC tower.
3455 *
3456 * The gate computes in @c NUMERIC whatever the types are -- it is the value
3457 * that is stored, and a wider one loses nothing -- but the value is READ in
3458 * the type the query's expression has, and @c double @c precision prints 16
3459 * digits where @c NUMERIC prints every one it holds. Recording the type is
3460 * what lets the reading round as SQL does; deriving it from the children makes
3461 * it a function of the gate, so two statements building the same expression
3462 * still agree on its token.
3463 *
3464 * Two operations are not the tower: the INTEGER division SQL writes as @c "/"
3465 * over integers (the @c INTDIV gate) answers in the INTEGER type, and
3466 * @c round(v, d) exists only over @c NUMERIC, so it answers in @c NUMERIC.
3467 */
3468CREATE OR REPLACE FUNCTION agg_arith_result_type(op INT, children UUID[])
3469 RETURNS oid AS
3470$$
3471DECLARE
3472 t oid;
3473 c UUID;
3474 has_float8 BOOLEAN := false;
3475 has_float4 BOOLEAN := false;
3476 has_numeric BOOLEAN := false;
3477 widest_int oid := NULL;
3478BEGIN
3479 IF children IS NULL THEN
3480 RETURN 'NUMERIC'::REGTYPE::oid;
3481 END IF;
3482 FOREACH c IN ARRAY children LOOP
3483 t := provsql.agg_token_value_type(c);
3484 IF t = 'float8'::REGTYPE::oid THEN has_float8 := true;
3485 ELSIF t = 'float4'::REGTYPE::oid THEN has_float4 := true;
3486 ELSIF t = 'NUMERIC'::REGTYPE::oid THEN has_numeric := true;
3487 ELSIF t = 'int8'::REGTYPE::oid THEN widest_int := 'int8'::REGTYPE::oid;
3488 ELSIF t = 'int4'::REGTYPE::oid THEN
3489 widest_int := coalesce(nullif(widest_int, 'int2'::REGTYPE::oid),
3490 'int4'::REGTYPE::oid);
3491 ELSIF t = 'int2'::REGTYPE::oid THEN
3492 widest_int := coalesce(widest_int, 'int2'::REGTYPE::oid);
3493 END IF;
3494 END LOOP;
3495 IF op = 16 THEN -- the value as double precision reads it
3496 RETURN 'float8'::REGTYPE::oid;
3497 END IF;
3498 IF op = 17 THEN -- ... as real reads it
3499 RETURN 'float4'::REGTYPE::oid;
3500 END IF;
3501 IF op = 11 THEN -- INTDIV
3502 RETURN coalesce(widest_int, 'int8'::REGTYPE::oid);
3503 END IF;
3504 IF op = 12 AND array_length(children, 1) = 2 THEN -- round(v, digits)
3505 RETURN 'NUMERIC'::REGTYPE::oid;
3506 END IF;
3507 IF has_float8 THEN
3508 RETURN 'float8'::REGTYPE::oid;
3509 END IF;
3510 IF has_float4 THEN -- no real-with-NUMERIC operator: SQL widens both
3511 RETURN CASE WHEN has_numeric THEN 'float8'::REGTYPE::oid
3512 ELSE 'float4'::REGTYPE::oid END;
3513 END IF;
3514 IF has_numeric THEN
3515 RETURN 'NUMERIC'::REGTYPE::oid;
3516 END IF;
3517 RETURN coalesce(widest_int, 'NUMERIC'::REGTYPE::oid);
3518END
3519$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE
3520 SET search_path=provsql,pg_temp,public;
3521
3522/** @brief Mint (or reuse) the gate_arith for an AGG_TOKEN arithmetic
3523 * result and return the AGG_TOKEN carrying it.
3524 *
3525 * The gate records the computed scalar in its @c extra, in @c NUMERIC --
3526 * exactly what aggregate evaluation does for @c agg gates -- and, in
3527 * @c info2, the SQL type the expression has (@c agg_arith_result_type), so
3528 * that @c agg_token_value_text recovers the @c "value (*)" display from the
3529 * bare UUID, read as SQL reads it (as ProvSQL Studio does for result cells
3530 * under @c provsql.aggtoken_text_as_uuid). A NULL value (a division by zero
3531 * on a row the database as it is may not have) keeps the gate. The gate UUID
3532 * is deterministic in (op, children), so re-recording the (identical) value
3533 * is idempotent. */
3534CREATE OR REPLACE FUNCTION agg_arith_make(op INT, children UUID[], val NUMERIC)
3535 RETURNS AGG_TOKEN AS
3536$$
3537DECLARE
3538 token UUID := public.uuid_generate_v5(
3539 provsql.uuid_ns_provsql(), concat('arith', op::TEXT, children::TEXT));
3540 restype oid;
3541 shown TEXT;
3542BEGIN
3543 IF op IS NULL OR children IS NULL THEN
3544 RETURN NULL;
3545 END IF;
3546 -- The gate keeps the value as it was computed, in NUMERIC: that is what the
3547 -- evaluators read, and the wider type loses nothing. The type of the
3548 -- expression goes beside it, so the value can be READ as SQL reads it.
3549 restype := provsql.agg_arith_result_type(op, children);
3550 PERFORM provsql.create_gate(token, 'arith', children, op, restype::INT,
3551 val::TEXT);
3552 -- A NULL value (a division by zero on a row the database as it is may not
3553 -- have) keeps the gate: its value in the other worlds is in the circuit.
3554 shown := CASE
3555 WHEN val IS NULL THEN 'NULL'
3556 WHEN restype = 'float8'::REGTYPE::oid THEN (val::float8)::TEXT
3557 WHEN restype = 'float4'::REGTYPE::oid THEN (val::float4)::TEXT
3558 ELSE val::TEXT
3559 END;
3560 RETURN format('( %s , %s )', token::TEXT, shown)::provsql.AGG_TOKEN;
3561END
3562$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
3563 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
3564
3565-- AGG_TOKEN <op> AGG_TOKEN --------------------------------------------
3566/** @brief AGG_TOKEN + AGG_TOKEN (gate_arith PLUS). */
3567CREATE OR REPLACE FUNCTION agg_token_plus(a AGG_TOKEN, b AGG_TOKEN)
3568 RETURNS AGG_TOKEN AS
3569$$ SELECT provsql.agg_arith_make(0, ARRAY[(a)::UUID, (b)::UUID],
3570 provsql.agg_token_value(a) + provsql.agg_token_value(b)); $$
3571 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3572
3573/** @brief AGG_TOKEN - AGG_TOKEN (gate_arith MINUS). */
3574CREATE OR REPLACE FUNCTION agg_token_minus(a AGG_TOKEN, b AGG_TOKEN)
3575 RETURNS AGG_TOKEN AS
3576$$ SELECT provsql.agg_arith_make(2, ARRAY[(a)::UUID, (b)::UUID],
3577 provsql.agg_token_value(a) - provsql.agg_token_value(b)); $$
3578 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3579
3580/** @brief AGG_TOKEN * AGG_TOKEN (gate_arith TIMES). */
3581CREATE OR REPLACE FUNCTION agg_token_times(a AGG_TOKEN, b AGG_TOKEN)
3582 RETURNS AGG_TOKEN AS
3583$$ SELECT provsql.agg_arith_make(1, ARRAY[(a)::UUID, (b)::UUID],
3584 provsql.agg_token_value(a) * provsql.agg_token_value(b)); $$
3585 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3586
3587/** @brief AGG_TOKEN / AGG_TOKEN (gate_arith DIV). */
3588CREATE OR REPLACE FUNCTION agg_token_div(a AGG_TOKEN, b AGG_TOKEN)
3589 RETURNS AGG_TOKEN AS
3590$$ SELECT provsql.agg_arith_make(3, ARRAY[(a)::UUID, (b)::UUID],
3591 provsql.agg_token_value(a) / NULLIF(provsql.agg_token_value(b), 0)); $$
3592 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3593
3594/** @brief Unary -AGG_TOKEN (gate_arith NEG). */
3595CREATE OR REPLACE FUNCTION agg_token_neg(a AGG_TOKEN)
3596 RETURNS AGG_TOKEN AS
3597$$ SELECT provsql.agg_arith_make(4, ARRAY[(a)::UUID],
3598 - provsql.agg_token_value(a)); $$
3599 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3600
3601-- round / floor / ceil / abs of an AGG_TOKEN ---------------------------
3602-- Named as the SQL functions they stand for, so that the rewriter's
3603-- re-resolution of a call whose argument became an AGG_TOKEN finds them
3604-- (try_swap_agg_func), exactly as the operators above are found. They compute
3605-- in NUMERIC, as the operators do, and the gate records the operation so the
3606-- value is read per possible world; the moment evaluators sample them, since
3607-- rounding does not commute with expectation.
3608/** @brief round(AGG_TOKEN) (gate_arith ROUND). */
3609CREATE OR REPLACE FUNCTION provsql_round(a AGG_TOKEN)
3610 RETURNS AGG_TOKEN AS
3611$$ SELECT provsql.agg_arith_make(12, ARRAY[(a)::UUID],
3612 pg_catalog.round(provsql.agg_token_value(a))); $$
3613 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3614
3615/** @brief round(AGG_TOKEN, INTEGER): to @p d decimal digits. */
3616CREATE OR REPLACE FUNCTION provsql_round(a AGG_TOKEN, d INTEGER)
3617 RETURNS AGG_TOKEN AS
3618$$ SELECT provsql.agg_arith_make(12,
3619 ARRAY[(a)::UUID, provsql.agg_value_gate(d::NUMERIC)],
3620 pg_catalog.round(provsql.agg_token_value(a), d)); $$
3621 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3622
3623/** @cond INTERNAL */
3624/**
3625 * @brief A cast of an aggregate result to a number, as the function of its
3626 * value that it is.
3627 *
3628 * A cast is a function call like any other, so the rewriting swaps
3629 * @c pg_catalog.NUMERIC(x) over an AGG_TOKEN for @c provsql.provsql_numeric(AGG_TOKEN)
3630 * wherever one is declared -- which is how round() and floor() became gate
3631 * operations. Between numbers the value is carried rather than frozen: a
3632 * widening (an INTEGER to @c NUMERIC, to a float) keeps it as it is, and a
3633 * narrowing to an INTEGER is the rounding gate, PostgreSQL's own cast rounding
3634 * half away from zero as that gate does. A cast to TEXT, to a BOOLEAN or to a
3635 * date has no arithmetic behind it and stays a reading of the plain value.
3636 */
3637CREATE OR REPLACE FUNCTION provsql_numeric(a AGG_TOKEN)
3638 RETURNS AGG_TOKEN AS $$ SELECT a $$
3639 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3640
3641/**
3642 * @brief float8(AGG_TOKEN): the value, as a double precision reads it.
3643 *
3644 * Not the identity it once was: the gates compute in @c NUMERIC, and this is
3645 * what says that the expression is a float, so that its value is read as SQL
3646 * reads it -- 2 and not 2.0000000000000000 for @c sum(x)/3 over such a column.
3647 * The gate is the rounding to that type, and every pass that walks arithmetic
3648 * treats it as the value of its child. A token already read in that type is
3649 * returned as it is, so nothing is wrapped twice.
3650 */
3651CREATE OR REPLACE FUNCTION provsql_float8(a AGG_TOKEN)
3652 RETURNS AGG_TOKEN AS
3653$$ SELECT CASE
3654 WHEN provsql.agg_token_value_type((a)::UUID) = 'float8'::REGTYPE::oid
3655 THEN a
3656 ELSE provsql.agg_arith_make(16, ARRAY[(a)::UUID],
3657 (provsql.agg_token_value(a)::float8)::NUMERIC)
3658 END $$
3659 LANGUAGE sql STABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3660
3661/** @brief float4(AGG_TOKEN): the value, as a real reads it (see float8). */
3662CREATE OR REPLACE FUNCTION provsql_float4(a AGG_TOKEN)
3663 RETURNS AGG_TOKEN AS
3664$$ SELECT CASE
3665 WHEN provsql.agg_token_value_type((a)::UUID) = 'float4'::REGTYPE::oid
3666 THEN a
3667 ELSE provsql.agg_arith_make(17, ARRAY[(a)::UUID],
3668 (provsql.agg_token_value(a)::float4)::NUMERIC)
3669 END $$
3670 LANGUAGE sql STABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3671
3672/** @brief int8(AGG_TOKEN): the value rounded, as the cast to bigint rounds. */
3673CREATE OR REPLACE FUNCTION provsql_int8(a AGG_TOKEN)
3674 RETURNS AGG_TOKEN AS $$ SELECT provsql.provsql_round(a) $$
3675 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3676
3677/** @brief int4(AGG_TOKEN): the value rounded, as the cast to INTEGER rounds. */
3678CREATE OR REPLACE FUNCTION provsql_int4(a AGG_TOKEN)
3679 RETURNS AGG_TOKEN AS $$ SELECT provsql.provsql_round(a) $$
3680 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3681
3682/** @brief int2(AGG_TOKEN): the value rounded, as the cast to smallint rounds. */
3683CREATE OR REPLACE FUNCTION provsql_int2(a AGG_TOKEN)
3684 RETURNS AGG_TOKEN AS $$ SELECT provsql.provsql_round(a) $$
3685 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3686/** @endcond */
3687
3688/** @brief floor(AGG_TOKEN) (gate_arith FLOOR). */
3689CREATE OR REPLACE FUNCTION provsql_floor(a AGG_TOKEN)
3690 RETURNS AGG_TOKEN AS
3691$$ SELECT provsql.agg_arith_make(13, ARRAY[(a)::UUID],
3692 pg_catalog.floor(provsql.agg_token_value(a))); $$
3693 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3694
3695/** @brief ceil(AGG_TOKEN) (gate_arith CEIL). */
3696CREATE OR REPLACE FUNCTION provsql_ceil(a AGG_TOKEN)
3697 RETURNS AGG_TOKEN AS
3698$$ SELECT provsql.agg_arith_make(14, ARRAY[(a)::UUID],
3699 pg_catalog.ceil(provsql.agg_token_value(a))); $$
3700 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3701
3702/** @brief ceiling(AGG_TOKEN), the SQL synonym of ceil. */
3703CREATE OR REPLACE FUNCTION provsql_ceiling(a AGG_TOKEN)
3704 RETURNS AGG_TOKEN AS
3705$$ SELECT provsql.agg_arith_make(14, ARRAY[(a)::UUID],
3706 pg_catalog.ceil(provsql.agg_token_value(a))); $$
3707 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3708
3709/** @brief abs(AGG_TOKEN) (gate_arith ABS). */
3710CREATE OR REPLACE FUNCTION provsql_abs(a AGG_TOKEN)
3711 RETURNS AGG_TOKEN AS
3712$$ SELECT provsql.agg_arith_make(15, ARRAY[(a)::UUID],
3713 pg_catalog.abs(provsql.agg_token_value(a))); $$
3714 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3715
3716-- AGG_TOKEN <op> NUMERIC ----------------------------------------------
3717/** @brief AGG_TOKEN + NUMERIC (gate_arith PLUS, constant lifted to a value gate). */
3718CREATE OR REPLACE FUNCTION agg_token_plus_numeric(a AGG_TOKEN, b NUMERIC)
3719 RETURNS AGG_TOKEN AS
3720$$ SELECT provsql.agg_arith_make(0, ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3721 provsql.agg_token_value(a) + b); $$
3722 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3723
3724/** @brief AGG_TOKEN - NUMERIC. */
3725CREATE OR REPLACE FUNCTION agg_token_minus_numeric(a AGG_TOKEN, b NUMERIC)
3726 RETURNS AGG_TOKEN AS
3727$$ SELECT provsql.agg_arith_make(2, ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3728 provsql.agg_token_value(a) - b); $$
3729 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3730
3731/** @brief AGG_TOKEN * NUMERIC. */
3732CREATE OR REPLACE FUNCTION agg_token_times_numeric(a AGG_TOKEN, b NUMERIC)
3733 RETURNS AGG_TOKEN AS
3734$$ SELECT provsql.agg_arith_make(1, ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3735 provsql.agg_token_value(a) * b); $$
3736 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3737
3738/** @brief AGG_TOKEN / NUMERIC. */
3739CREATE OR REPLACE FUNCTION agg_token_div_numeric(a AGG_TOKEN, b NUMERIC)
3740 RETURNS AGG_TOKEN AS
3741$$ SELECT provsql.agg_arith_make(3, ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3742 provsql.agg_token_value(a) / NULLIF(b, 0)); $$
3743 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3744
3745-- NUMERIC <op> AGG_TOKEN ----------------------------------------------
3746/** @brief NUMERIC + AGG_TOKEN. */
3747CREATE OR REPLACE FUNCTION numeric_plus_agg_token(a NUMERIC, b AGG_TOKEN)
3748 RETURNS AGG_TOKEN AS
3749$$ SELECT provsql.agg_arith_make(0, ARRAY[provsql.agg_value_gate(a), (b)::UUID],
3750 a + provsql.agg_token_value(b)); $$
3751 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3752
3753/** @brief NUMERIC - AGG_TOKEN. */
3754CREATE OR REPLACE FUNCTION numeric_minus_agg_token(a NUMERIC, b AGG_TOKEN)
3755 RETURNS AGG_TOKEN AS
3756$$ SELECT provsql.agg_arith_make(2, ARRAY[provsql.agg_value_gate(a), (b)::UUID],
3757 a - provsql.agg_token_value(b)); $$
3758 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3759
3760/** @brief NUMERIC * AGG_TOKEN. */
3761CREATE OR REPLACE FUNCTION numeric_times_agg_token(a NUMERIC, b AGG_TOKEN)
3762 RETURNS AGG_TOKEN AS
3763$$ SELECT provsql.agg_arith_make(1, ARRAY[provsql.agg_value_gate(a), (b)::UUID],
3764 a * provsql.agg_token_value(b)); $$
3765 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3766
3767/** @brief NUMERIC / AGG_TOKEN. */
3768CREATE OR REPLACE FUNCTION numeric_div_agg_token(a NUMERIC, b AGG_TOKEN)
3769 RETURNS AGG_TOKEN AS
3770$$ SELECT provsql.agg_arith_make(3, ARRAY[provsql.agg_value_gate(a), (b)::UUID],
3771 a / NULLIF(provsql.agg_token_value(b), 0)); $$
3772 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3773
3774/**
3775 * @brief AGG_TOKEN / AGG_TOKEN, in INTEGER division (internal)
3776 *
3777 * The rewriter calls it instead of agg_token_div when both operands were
3778 * integers in the query, as for count(*) / count(x): SQL divides them
3779 * with truncation toward zero, and the displayed value does too. The gate
3780 * is an arith gate of its own operator (11, PROVSQL_ARITH_INTDIV), which
3781 * the evaluators truncate in every world.
3782 */
3783CREATE OR REPLACE FUNCTION agg_token_intdiv(a AGG_TOKEN, b AGG_TOKEN)
3784 RETURNS AGG_TOKEN AS
3785$$ SELECT provsql.agg_arith_make(11, ARRAY[(a)::UUID, (b)::UUID],
3786 trunc(provsql.agg_token_value(a) / NULLIF(provsql.agg_token_value(b), 0))); $$
3787 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3788
3789/** @brief AGG_TOKEN / NUMERIC, in INTEGER division (internal; see agg_token_intdiv). */
3790CREATE OR REPLACE FUNCTION agg_token_intdiv_numeric(a AGG_TOKEN, b NUMERIC)
3791 RETURNS AGG_TOKEN AS
3792$$ SELECT provsql.agg_arith_make(11, ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3793 trunc(provsql.agg_token_value(a) / NULLIF(b, 0))); $$
3794 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3795
3796/** @brief NUMERIC / AGG_TOKEN, in INTEGER division (internal; see agg_token_intdiv). */
3797CREATE OR REPLACE FUNCTION numeric_intdiv_agg_token(a NUMERIC, b AGG_TOKEN)
3798 RETURNS AGG_TOKEN AS
3799$$ SELECT provsql.agg_arith_make(11, ARRAY[provsql.agg_value_gate(a), (b)::UUID],
3800 trunc(a / NULLIF(provsql.agg_token_value(b), 0))); $$
3801 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3802
3803-- Operator declarations -----------------------------------------------
3804CREATE OPERATOR + (LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_plus, COMMUTATOR = +);
3805CREATE OPERATOR - (LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_minus);
3806CREATE OPERATOR * (LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_times, COMMUTATOR = *);
3807CREATE OPERATOR / (LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_div);
3808CREATE OPERATOR - (RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_neg);
3809/* Prefix @ is PostgreSQL's absolute value. Its own procedure is numeric_abs
3810 or int8abs rather than abs, so the swap cannot reach the counterpart by
3811 resolving the operator's function: the operator over AGG_TOKEN is declared
3812 here instead, and ORDER BY @(2 - max(x)) carries its gate like abs(...). */
3813CREATE OPERATOR @ (RIGHTARG=AGG_TOKEN, PROCEDURE=provsql_abs);
3815/**
3816 * @brief @p fn of the value of @p a, computed in the type the value is read in.
3817 *
3818 * The gates compute in @c NUMERIC, which loses nothing for the four basic
3819 * operations: computing exactly and reading the result as @c double
3820 * @c precision gives what floating-point arithmetic gives, since IEEE requires
3821 * each of them to be correctly rounded. @c sqrt, @c ln and @c exp are not
3822 * like that -- @c NUMERIC computes them to a fixed scale, so @c sqrt(3) comes
3823 * out to fifteen decimals and the value read back differs from SQL's in its
3824 * last digit -- so where the expression is a float, they are computed as SQL
3825 * computes them, in that type, and the NUMERIC the gate stores is that value.
3826 */
3827CREATE OR REPLACE FUNCTION agg_transcendental(fn TEXT, a AGG_TOKEN)
3828 RETURNS NUMERIC AS
3829$$
3830 SELECT CASE
3831 WHEN provsql.agg_token_value_type((a)::UUID)
3832 IN ('float8'::REGTYPE::oid, 'float4'::REGTYPE::oid)
3833 THEN (CASE fn
3834 WHEN 'sqrt' THEN sqrt(provsql.agg_token_value(a)::float8)
3835 WHEN 'ln' THEN ln(provsql.agg_token_value(a)::float8)
3836 WHEN 'exp' THEN exp(provsql.agg_token_value(a)::float8)
3837 END)::text::NUMERIC /* through the float's own text: the cast to
3838 * NUMERIC keeps fifteen digits, its TEXT
3839 * keeps every one the value has */
3840 ELSE CASE fn
3841 WHEN 'sqrt' THEN sqrt(provsql.agg_token_value(a))
3842 WHEN 'ln' THEN ln(provsql.agg_token_value(a))
3843 WHEN 'exp' THEN exp(provsql.agg_token_value(a))
3844 END
3845 END;
3846$$ LANGUAGE sql STABLE STRICT PARALLEL SAFE
3847 SET search_path=provsql,pg_temp,public;
3848
3849/** @brief ln(AGG_TOKEN) (gate_arith LN): the logarithm of the value the
3850 * aggregate takes, in every world, rather than of the one it takes in the
3851 * database as it is. */
3852CREATE OR REPLACE FUNCTION provsql_ln(a AGG_TOKEN)
3853 RETURNS AGG_TOKEN AS
3854$$ SELECT provsql.agg_arith_make(8, ARRAY[(a)::UUID],
3855 provsql.agg_transcendental('ln', a)); $$
3856 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3857
3858/** @brief exp(AGG_TOKEN) (gate_arith EXP). */
3859CREATE OR REPLACE FUNCTION provsql_exp(a AGG_TOKEN)
3860 RETURNS AGG_TOKEN AS
3861$$ SELECT provsql.agg_arith_make(9, ARRAY[(a)::UUID],
3862 provsql.agg_transcendental('exp', a)); $$
3863 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3865/** @brief sqrt(AGG_TOKEN): the square root is the power of one half
3866 * (gate_arith POW, whose exponent is a value gate). */
3867CREATE OR REPLACE FUNCTION provsql_sqrt(a AGG_TOKEN)
3868 RETURNS AGG_TOKEN AS
3869$$ SELECT provsql.agg_arith_make(7,
3870 ARRAY[(a)::UUID, provsql.agg_value_gate(0.5)],
3871 provsql.agg_transcendental('sqrt', a)); $$
3872 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3873
3874/** @brief AGG_TOKEN ^ NUMERIC (gate_arith POW, constant lifted to a value
3875 * gate). */
3876CREATE OR REPLACE FUNCTION agg_token_pow_numeric(a AGG_TOKEN, b NUMERIC)
3877 RETURNS AGG_TOKEN AS
3878$$ SELECT provsql.agg_arith_make(7,
3879 ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3880 provsql.agg_token_value(a) ^ b); $$
3881 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3882
3883CREATE OPERATOR ^ (LEFTARG=AGG_TOKEN, RIGHTARG=NUMERIC,
3884 PROCEDURE=agg_token_pow_numeric);
3885
3886/** @brief power(AGG_TOKEN, NUMERIC) (gate_arith POW, the exponent lifted to
3887 * a value gate): what @c power(sum(x), 2) is carried as, the way
3888 * @c sum(x) ^ 2 already is. */
3889CREATE OR REPLACE FUNCTION provsql_power(a AGG_TOKEN, b NUMERIC)
3890 RETURNS AGG_TOKEN AS
3891$$ SELECT provsql.agg_arith_make(7,
3892 ARRAY[(a)::UUID, provsql.agg_value_gate(b)],
3893 power(provsql.agg_token_value(a), b)); $$
3894 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3895
3896/** @brief power(AGG_TOKEN, double precision): computed in double precision,
3897 * as SQL computes it, and the exponent stored through its own TEXT, which
3898 * keeps every digit the float has (see @c agg_transcendental). */
3899CREATE OR REPLACE FUNCTION provsql_power(a AGG_TOKEN, b double precision)
3900 RETURNS AGG_TOKEN AS
3901$$ SELECT provsql.agg_arith_make(7,
3902 ARRAY[(a)::UUID, provsql.agg_value_gate(b::text::NUMERIC)],
3903 power(provsql.agg_token_value(a)::float8, b)::text::NUMERIC); $$
3904 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3905
3906/** @brief pow(AGG_TOKEN, NUMERIC): @c pow is @c power's other name. */
3907CREATE OR REPLACE FUNCTION provsql_pow(a AGG_TOKEN, b NUMERIC)
3908 RETURNS AGG_TOKEN AS
3909$$ SELECT provsql.provsql_power(a, b); $$
3910 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3911
3912/** @brief pow(AGG_TOKEN, double precision). */
3913CREATE OR REPLACE FUNCTION provsql_pow(a AGG_TOKEN, b double precision)
3914 RETURNS AGG_TOKEN AS
3915$$ SELECT provsql.provsql_power(a, b); $$
3916 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE SET search_path=provsql,pg_temp,public;
3917
3918CREATE OPERATOR + (LEFTARG=AGG_TOKEN, RIGHTARG=NUMERIC, PROCEDURE=agg_token_plus_numeric, COMMUTATOR = +);
3919CREATE OPERATOR - (LEFTARG=AGG_TOKEN, RIGHTARG=NUMERIC, PROCEDURE=agg_token_minus_numeric);
3920CREATE OPERATOR * (LEFTARG=AGG_TOKEN, RIGHTARG=NUMERIC, PROCEDURE=agg_token_times_numeric, COMMUTATOR = *);
3921CREATE OPERATOR / (LEFTARG=AGG_TOKEN, RIGHTARG=NUMERIC, PROCEDURE=agg_token_div_numeric);
3922
3923CREATE OPERATOR + (LEFTARG=NUMERIC, RIGHTARG=AGG_TOKEN, PROCEDURE=numeric_plus_agg_token, COMMUTATOR = +);
3924CREATE OPERATOR - (LEFTARG=NUMERIC, RIGHTARG=AGG_TOKEN, PROCEDURE=numeric_minus_agg_token);
3925CREATE OPERATOR * (LEFTARG=NUMERIC, RIGHTARG=AGG_TOKEN, PROCEDURE=numeric_times_agg_token, COMMUTATOR = *);
3926CREATE OPERATOR / (LEFTARG=NUMERIC, RIGHTARG=AGG_TOKEN, PROCEDURE=numeric_div_agg_token);
3927
3928/** @brief Assignment cast from AGG_TOKEN to double precision */
3929CREATE CAST (AGG_TOKEN AS double precision) WITH FUNCTION agg_token_to_float8(AGG_TOKEN) AS ASSIGNMENT;
3930/** @brief Assignment cast from AGG_TOKEN to INTEGER */
3931CREATE CAST (AGG_TOKEN AS INTEGER) WITH FUNCTION agg_token_to_int4(AGG_TOKEN) AS ASSIGNMENT;
3932/** @brief Assignment cast from AGG_TOKEN to bigint */
3933CREATE CAST (AGG_TOKEN AS bigint) WITH FUNCTION agg_token_to_int8(AGG_TOKEN) AS ASSIGNMENT;
3934/** @brief Assignment cast from AGG_TOKEN to TEXT (extracts value, not UUID) */
3935CREATE CAST (AGG_TOKEN AS TEXT) WITH FUNCTION agg_token_to_text(AGG_TOKEN) AS ASSIGNMENT;
3936/** @brief Assignment cast from AGG_TOKEN to BOOLEAN (bool_and, bool_or, every) */
3937CREATE CAST (AGG_TOKEN AS BOOLEAN) WITH FUNCTION agg_token_to_bool(AGG_TOKEN) AS ASSIGNMENT;
3939/**
3940 * @brief Condition a discrete aggregate's distribution on an event:
3941 * @c "SUM(x) | C".
3943 * Mirrors @c random_variable_cond for the @c AGG_TOKEN carrier: returns a
3944 * conditioned @c AGG_TOKEN that flows onward, its provenance token wrapped in
3945 * the composable two-child @c gate_conditioned @c [agg_target, condition]
3946 * while its running value is preserved. The moment / support dispatchers
3947 * unpack it (@c agg_conditioned_target + @c rv_conditioned_prov) and route
3948 * through the existing @c agg_raw_moment with the condition conjoined into the
3949 * @c prov argument, so @c expected(SUM(x)|C) / @c variance(SUM(x)|C) report
3950 * the conditional aggregate distribution. Nested conditioning folds.
3951 */
3952CREATE OR REPLACE FUNCTION agg_token_cond(a AGG_TOKEN, cond UUID)
3953 RETURNS AGG_TOKEN AS
3955DECLARE
3956 tok UUID;
3957 ev UUID;
3958 result UUID;
3959 ch UUID[];
3960BEGIN
3961 IF cond IS NULL OR cond = gate_one() THEN
3962 RETURN a;
3963 END IF;
3964
3965 tok := (a)::UUID;
3966 IF get_gate_type(tok) = 'conditioned'
3967 AND array_length(get_children(tok), 1) = 2 THEN
3968 ch := get_children(tok);
3969 tok := ch[1];
3970 ev := provenance_times(ch[2], cond);
3971 ELSE
3972 ev := cond;
3973 END IF;
3974
3975 result := public.uuid_generate_v5(uuid_ns_provsql(),
3976 concat('conditioned', tok, ev));
3977 PERFORM create_gate(result, 'conditioned', ARRAY[tok, ev]);
3978 RETURN agg_token_make(result, agg_token_value(a));
3980$$ LANGUAGE plpgsql IMMUTABLE SET search_path=provsql,pg_temp,public
3981 SECURITY DEFINER PARALLEL SAFE;
3982
3983CREATE OPERATOR | (
3984 LEFTARG = AGG_TOKEN,
3985 RIGHTARG = UUID,
3986 PROCEDURE = agg_token_cond
3988
3989/**
3990 * @brief Placeholder for @c "SUM(x) | (predicate)" on an AGG_TOKEN.
3991 *
3992 * Lets the conditioning event be a natural Boolean predicate (e.g.
3993 * @c "SUM(x) | (SUM(x) > 5)") instead of a hand-built gate. Never executes:
3994 * the planner converts the Boolean operand into a condition gate and emits
3995 * @c agg_token_cond.
3996 */
3997CREATE OR REPLACE FUNCTION agg_token_cond_predicate(
3998 a AGG_TOKEN, predicate BOOLEAN) RETURNS AGG_TOKEN AS
3999$$
4000BEGIN
4001 RAISE EXCEPTION 'AGG_TOKEN | (predicate) must be rewritten by the ProvSQL '
4002 'planner hook: the right operand must be a Boolean combination of '
4003 'aggregate / random_variable comparisons (is provsql.active off?)'
4004 USING ERRCODE = 'feature_not_supported',
4005 DETAIL = 'provsql-reason: operator-not-rewritten; scope: gap';
4006END
4007$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
4008
4009CREATE OPERATOR | (
4010 LEFTARG = AGG_TOKEN,
4011 RIGHTARG = BOOLEAN,
4012 PROCEDURE = agg_token_cond_predicate
4013);
4014
4016 * @brief Unpack the target of a conditioned @c AGG_TOKEN.
4017 *
4018 * For a @c "SUM(x) | C" whose provenance token is the two-child
4019 * @c gate_conditioned @c [agg_target, condition] returns the AGG_TOKEN over
4020 * @c agg_target (same running value); for any other AGG_TOKEN returns it
4021 * unchanged. The conditioning event itself is recovered separately via
4022 * @c rv_conditioned_prov on the token's UUID.
4023 */
4024CREATE OR REPLACE FUNCTION agg_conditioned_target(a AGG_TOKEN)
4025 RETURNS AGG_TOKEN AS
4026$$
4027 SELECT CASE
4028 WHEN provsql.get_gate_type((a)::UUID) = 'conditioned'
4029 AND array_length(provsql.get_children((a)::UUID), 1) = 2
4030 THEN provsql.agg_token_make(
4031 (provsql.get_children((a)::UUID))[1], provsql.agg_token_value(a))
4032 ELSE a
4033 END;
4034$$ LANGUAGE sql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
4036/**
4037 * @brief Placeholder comparison of AGG_TOKEN with NUMERIC
4038 *
4039 * This function is never actually called; it exists so the SQL parser
4040 * accepts comparison operators between AGG_TOKEN and NUMERIC values.
4041 * The ProvSQL query rewriter replaces these comparisons at plan time.
4042 */
4043CREATE OR REPLACE FUNCTION agg_token_comp_numeric(a AGG_TOKEN, b NUMERIC)
4044RETURNS BOOLEAN
4045LANGUAGE plpgsql
4046IMMUTABLE STRICT PARALLEL SAFE
4047AS $$
4048BEGIN
4049 RAISE EXCEPTION 'Comparison AGG_TOKEN-NUMERIC not implemented, should be replaced by ProvSQL behavior'
4050 USING ERRCODE = 'feature_not_supported',
4051 DETAIL = 'provsql-reason: agg-comparison-not-rewritten; scope: gap';
4052END;
4053$$;
4054
4055/**
4056 * @brief Placeholder comparison of NUMERIC with AGG_TOKEN
4057 *
4058 * Symmetric to agg_token_comp_numeric; never actually called.
4059 * The ProvSQL query rewriter replaces these comparisons at plan time.
4061CREATE OR REPLACE FUNCTION numeric_comp_agg_token(a NUMERIC, b AGG_TOKEN)
4062RETURNS BOOLEAN
4063LANGUAGE plpgsql
4064IMMUTABLE STRICT PARALLEL SAFE
4065AS $$
4066BEGIN
4067 RAISE EXCEPTION 'Comparison NUMERIC-AGG_TOKEN not implemented, should be replaced by ProvSQL behavior'
4068 USING ERRCODE = 'feature_not_supported',
4069 DETAIL = 'provsql-reason: agg-comparison-not-rewritten; scope: gap';
4070END;
4071$$;
4072
4073/** @brief SQL operator AGG_TOKEN < NUMERIC (placeholder rewritten by ProvSQL at plan time) */
4074CREATE OPERATOR < (
4075 LEFTARG = AGG_TOKEN,
4076 RIGHTARG = NUMERIC,
4077 PROCEDURE = agg_token_comp_numeric,
4078 COMMUTATOR = >,
4079 NEGATOR = >=
4080);
4081/** @brief SQL operator NUMERIC < AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4082CREATE OPERATOR < (
4083 LEFTARG = NUMERIC,
4084 RIGHTARG = AGG_TOKEN,
4085 PROCEDURE = numeric_comp_agg_token,
4086 COMMUTATOR = >,
4087 NEGATOR = >=
4088);
4089
4090/** @brief SQL operator AGG_TOKEN <= NUMERIC (placeholder rewritten by ProvSQL at plan time) */
4091CREATE OPERATOR <= (
4092 LEFTARG = AGG_TOKEN,
4093 RIGHTARG = NUMERIC,
4094 PROCEDURE = agg_token_comp_numeric,
4095 COMMUTATOR = >=,
4096 NEGATOR = >
4097);
4098/** @brief SQL operator NUMERIC <= AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4099CREATE OPERATOR <= (
4100 LEFTARG = NUMERIC,
4101 RIGHTARG = AGG_TOKEN,
4102 PROCEDURE = numeric_comp_agg_token,
4103 COMMUTATOR = >=,
4104 NEGATOR = >
4105);
4106
4107/** @brief SQL operator AGG_TOKEN = NUMERIC (placeholder rewritten by ProvSQL at plan time) */
4108CREATE OPERATOR = (
4109 LEFTARG = AGG_TOKEN,
4110 RIGHTARG = NUMERIC,
4111 PROCEDURE = agg_token_comp_numeric,
4112 COMMUTATOR = =,
4113 NEGATOR = <>
4114);
4115/** @brief SQL operator NUMERIC = AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4116CREATE OPERATOR = (
4117 LEFTARG = NUMERIC,
4118 RIGHTARG = AGG_TOKEN,
4119 PROCEDURE = numeric_comp_agg_token,
4120 COMMUTATOR = =,
4121 NEGATOR = <>
4123
4124/** @brief SQL operator AGG_TOKEN <> NUMERIC (placeholder rewritten by ProvSQL at plan time) */
4125CREATE OPERATOR <> (
4126 LEFTARG = AGG_TOKEN,
4127 RIGHTARG = NUMERIC,
4128 PROCEDURE = agg_token_comp_numeric,
4129 COMMUTATOR = <>,
4130 NEGATOR = =
4131);
4132/** @brief SQL operator NUMERIC <> AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4133CREATE OPERATOR <> (
4134 LEFTARG = NUMERIC,
4135 RIGHTARG = AGG_TOKEN,
4136 PROCEDURE = numeric_comp_agg_token,
4137 COMMUTATOR = <>,
4138 NEGATOR = =
4139);
4140
4141/** @brief SQL operator AGG_TOKEN >= NUMERIC (placeholder rewritten by ProvSQL at plan time) */
4142CREATE OPERATOR >= (
4143 LEFTARG = AGG_TOKEN,
4144 RIGHTARG = NUMERIC,
4145 PROCEDURE = agg_token_comp_numeric,
4146 COMMUTATOR = <=,
4147 NEGATOR = <
4148);
4149/** @brief SQL operator NUMERIC >= AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4150CREATE OPERATOR >= (
4151 LEFTARG = NUMERIC,
4152 RIGHTARG = AGG_TOKEN,
4153 PROCEDURE = numeric_comp_agg_token,
4154 COMMUTATOR = <=,
4155 NEGATOR = <
4156);
4157
4158/** @brief SQL operator AGG_TOKEN > NUMERIC (placeholder rewritten by ProvSQL at plan time) */
4159CREATE OPERATOR > (
4160 LEFTARG = AGG_TOKEN,
4161 RIGHTARG = NUMERIC,
4162 PROCEDURE = agg_token_comp_numeric,
4163 COMMUTATOR = <,
4164 NEGATOR = <=
4165);
4166/** @brief SQL operator NUMERIC > AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4167CREATE OPERATOR > (
4168 LEFTARG = NUMERIC,
4169 RIGHTARG = AGG_TOKEN,
4170 PROCEDURE = numeric_comp_agg_token,
4171 COMMUTATOR = <,
4172 NEGATOR = <=
4173);
4174
4175/**
4176 * @brief Placeholder comparison of two AGG_TOKEN values (the diagonal)
4177 *
4178 * Never actually called; lets the parser accept AGG_TOKEN \<op\> AGG_TOKEN
4179 * (e.g. sum(x) > sum(y) on materialised tokens), which the ProvSQL
4180 * rewriter lowers to a gate_cmp at plan time. Declaring this diagonal
4181 * also disambiguates `s = s2` (otherwise "operator is not unique",
4182 * because both AGG_TOKEN -> UUID and AGG_TOKEN -> NUMERIC casts apply).
4183 */
4184CREATE OR REPLACE FUNCTION agg_token_comp_agg_token(a AGG_TOKEN, b AGG_TOKEN)
4185RETURNS BOOLEAN
4186LANGUAGE plpgsql
4187IMMUTABLE STRICT PARALLEL SAFE
4188AS $$
4189BEGIN
4190 RAISE EXCEPTION 'Comparison AGG_TOKEN-AGG_TOKEN not implemented, should be replaced by ProvSQL behavior'
4191 USING ERRCODE = 'feature_not_supported',
4192 DETAIL = 'provsql-reason: agg-comparison-not-rewritten; scope: gap';
4193END;
4194$$;
4195
4196/** @brief SQL operator AGG_TOKEN < AGG_TOKEN (placeholder rewritten at plan time) */
4197CREATE OPERATOR < (
4198 LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_comp_agg_token,
4199 COMMUTATOR = >, NEGATOR = >=
4200);
4201/** @brief SQL operator AGG_TOKEN <= AGG_TOKEN (placeholder rewritten at plan time) */
4202CREATE OPERATOR <= (
4203 LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_comp_agg_token,
4204 COMMUTATOR = >=, NEGATOR = >
4205);
4206/** @brief SQL operator AGG_TOKEN > AGG_TOKEN (placeholder rewritten at plan time) */
4207CREATE OPERATOR > (
4208 LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_comp_agg_token,
4209 COMMUTATOR = <, NEGATOR = <=
4210);
4211/** @brief SQL operator AGG_TOKEN >= AGG_TOKEN (placeholder rewritten at plan time) */
4212CREATE OPERATOR >= (
4213 LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_comp_agg_token,
4214 COMMUTATOR = <=, NEGATOR = <
4215);
4216/** @brief SQL operator AGG_TOKEN = AGG_TOKEN (placeholder rewritten at plan time) */
4217CREATE OPERATOR = (
4218 LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_comp_agg_token,
4219 COMMUTATOR = =, NEGATOR = <>
4220);
4221/** @brief SQL operator AGG_TOKEN <> AGG_TOKEN (placeholder rewritten at plan time) */
4222CREATE OPERATOR <> (
4223 LEFTARG=AGG_TOKEN, RIGHTARG=AGG_TOKEN, PROCEDURE=agg_token_comp_agg_token,
4224 COMMUTATOR = <>, NEGATOR = =
4225);
4226
4227/**
4228 * @brief Placeholder comparison of AGG_TOKEN with TEXT
4229 *
4230 * This function is never actually called; it exists so the SQL parser
4231 * accepts comparison operators between AGG_TOKEN and TEXT values.
4232 * The ProvSQL query rewriter replaces these comparisons at plan time.
4233 */
4234CREATE OR REPLACE FUNCTION agg_token_comp_text(a AGG_TOKEN, b TEXT)
4235RETURNS BOOLEAN
4236LANGUAGE plpgsql
4237IMMUTABLE STRICT PARALLEL SAFE
4238AS $$
4239BEGIN
4240 RAISE EXCEPTION 'Comparison AGG_TOKEN-TEXT not implemented, should be replaced by ProvSQL behavior'
4241 USING ERRCODE = 'feature_not_supported',
4242 DETAIL = 'provsql-reason: agg-comparison-not-rewritten; scope: gap';
4243END;
4244$$;
4245
4246/**
4247 * @brief Placeholder comparison of TEXT with AGG_TOKEN
4248 *
4249 * Symmetric to agg_token_comp_text; never actually called.
4250 * The ProvSQL query rewriter replaces these comparisons at plan time.
4251 */
4252CREATE OR REPLACE FUNCTION text_comp_agg_token(a TEXT, b AGG_TOKEN)
4253RETURNS BOOLEAN
4254LANGUAGE plpgsql
4255IMMUTABLE STRICT PARALLEL SAFE
4256AS $$
4257BEGIN
4258 RAISE EXCEPTION 'Comparison TEXT-AGG_TOKEN not implemented, should be replaced by ProvSQL behavior'
4259 USING ERRCODE = 'feature_not_supported',
4260 DETAIL = 'provsql-reason: agg-comparison-not-rewritten; scope: gap';
4261END;
4262$$;
4263
4264/** @brief SQL operator AGG_TOKEN = TEXT (placeholder rewritten by ProvSQL at plan time) */
4265CREATE OPERATOR = (
4266 LEFTARG = AGG_TOKEN,
4267 RIGHTARG = TEXT,
4268 PROCEDURE = agg_token_comp_text,
4269 COMMUTATOR = =,
4270 NEGATOR = <>
4271);
4272/** @brief SQL operator TEXT = AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4273CREATE OPERATOR = (
4274 LEFTARG = TEXT,
4275 RIGHTARG = AGG_TOKEN,
4276 PROCEDURE = text_comp_agg_token,
4277 COMMUTATOR = =,
4278 NEGATOR = <>
4279);
4280
4281/** @brief SQL operator AGG_TOKEN <> TEXT (placeholder rewritten by ProvSQL at plan time) */
4282CREATE OPERATOR <> (
4283 LEFTARG = AGG_TOKEN,
4284 RIGHTARG = TEXT,
4285 PROCEDURE = agg_token_comp_text,
4286 COMMUTATOR = <>,
4287 NEGATOR = =
4288);
4289/** @brief SQL operator TEXT <> AGG_TOKEN (placeholder rewritten by ProvSQL at plan time) */
4290CREATE OPERATOR <> (
4291 LEFTARG = TEXT,
4292 RIGHTARG = AGG_TOKEN,
4293 PROCEDURE = text_comp_agg_token,
4294 COMMUTATOR = <>,
4295 NEGATOR = =
4296);
4297
4298/** @} */
4299
4300/** @defgroup random_variable_type Type for continuous random variables
4301 *
4302 * Custom type <tt>random_variable</tt>: a thin wrapper around a
4303 * provenance gate UUID, used to expose continuous probabilistic
4304 * c-tables in SQL. The UUID indexes either a <tt>gate_rv</tt>
4305 * (an actual distribution) or a <tt>gate_value</tt> (a
4306 * zero-variance constant produced by <tt>provsql.as_random</tt>).
4307 * Binary-coercible with <tt>UUID</tt> (same 16-byte layout), so an
4308 * <tt>rv</tt>-typed expression flows directly into any function
4309 * expecting a UUID at zero runtime cost.
4311 * Constructors live in this group: <tt>provsql.normal(μ, σ)</tt>,
4312 * <tt>provsql.uniform(a, b)</tt>, <tt>provsql.exponential(λ)</tt>,
4313 * <tt>provsql.erlang(k, λ)</tt>, <tt>provsql.gamma(k, λ)</tt>,
4314 * <tt>provsql.chi_squared(k)</tt>, <tt>provsql.lognormal(μ, σ)</tt>,
4315 * <tt>provsql.weibull(k, λ)</tt>, <tt>provsql.pareto(xₘ, α)</tt>,
4316 * <tt>provsql.beta(α, β)</tt>,
4317 * the discrete count constructors (<tt>provsql.poisson(λ)</tt>,
4318 * <tt>provsql.binomial(n, p)</tt>, <tt>provsql.geometric(p)</tt>,
4319 * <tt>provsql.hypergeometric(N, K, n)</tt>,
4320 * <tt>provsql.negative_binomial(r, p)</tt>, all lowering to
4321 * @c categorical via @c categorical_from_log_pmf),
4322 * and <tt>provsql.as_random(c)</tt>.
4323 * Operator overloads
4324 * (<tt>+ - * /</tt> and the six comparators) are defined further
4325 * below, alongside direct <tt>rv_cmp_*</tt> UUID constructors for
4326 * callers that want a <tt>gate_cmp</tt> token without going through
4327 * the planner hook.
4328 * @{
4329 */
4330
4331CREATE TYPE random_variable;
4332
4333/** @brief Input function for the random_variable type */
4334CREATE OR REPLACE FUNCTION random_variable_in(CSTRING)
4335 RETURNS random_variable
4336 AS 'provsql','random_variable_in' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
4337
4338/** @brief Output function for the random_variable type */
4339CREATE OR REPLACE FUNCTION random_variable_out(random_variable)
4340 RETURNS CSTRING
4341 AS 'provsql','random_variable_out' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
4343CREATE TYPE random_variable (
4344 internallength = 16,
4345 input = random_variable_in,
4346 output = random_variable_out,
4347 alignment = char
4348);
4349
4350/** @brief Build a random_variable from a UUID (internal). */
4351CREATE OR REPLACE FUNCTION random_variable_make(tok UUID)
4352 RETURNS random_variable
4353 AS 'provsql','random_variable_make' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
4354
4355/** @brief Binary-coercible cast random_variable -> UUID.
4356 * A random_variable is byte-for-byte a pg_uuid_t (alignment char,
4357 * length 16), so WITHOUT FUNCTION lets PostgreSQL reinterpret the
4358 * bytes at zero runtime cost. The cast is ASSIGNMENT (not IMPLICIT):
4359 * an implicit cross-domain cast would silently reroute a comparison
4360 * such as `v < w` to `UUID < UUID` (raw byte comparison) whenever
4361 * `provsql` is not in search_path, since operators are resolved
4362 * through search_path but casts are not. Demoting to ASSIGNMENT
4363 * turns that silent wrong result into a clean parse error. Passing a
4364 * random_variable to a UUID-taking function now needs an explicit
4365 * `v::UUID` (function resolution never applies assignment casts). */
4366CREATE CAST (random_variable AS UUID) WITHOUT FUNCTION AS ASSIGNMENT;
4367CREATE CAST (UUID AS random_variable) WITHOUT FUNCTION;
4368
4369/**
4370 * @brief Coerce an @c AGG_TOKEN to a @c random_variable (its circuit token).
4371 *
4372 * An aggregate over probabilistic tuples IS a random variable: its
4373 * @c AGG_TOKEN carries the provenance circuit of the aggregate distribution.
4374 * Exposing that as a @c random_variable lets a comparison / conditioning
4375 * predicate mix the two -- e.g. conditioning a latent leaf on a count,
4376 * @c "R | (poisson(lambda) = C)" with @c C a @c count(*) AGG_TOKEN -- resolve
4377 * to the ordinary @c random_variable comparison operators (which the planner
4378 * hook rewrites into a @c gate_cmp). IMPLICIT so the mixed comparison
4379 * type-checks without an explicit cast; the polymorphic dispatchers keep
4380 * their exact @c AGG_TOKEN overloads (an exact match beats the cast).
4381 */
4382CREATE OR REPLACE FUNCTION agg_token_to_random_variable(a AGG_TOKEN)
4383 RETURNS random_variable AS
4384$$ SELECT provsql.random_variable_make(provsql.agg_token_uuid($1)); $$
4385 LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
4386CREATE CAST (AGG_TOKEN AS random_variable)
4387 WITH FUNCTION agg_token_to_random_variable(AGG_TOKEN) AS IMPLICIT;
4388
4389/**
4390 * @brief Internal: true iff @p x is a finite (non-NaN, non-±∞) float8.
4391 *
4392 * PostgreSQL's <tt>isnan</tt> is defined for <tt>NUMERIC</tt> only,
4393 * not for <tt>double precision</tt>; we use the inequality form,
4394 * which works because PG defines <tt>NaN = NaN</tt> as <tt>TRUE</tt>
4395 * for floats (so <tt>NaN <> 'NaN'::float8</tt> is <tt>FALSE</tt>).
4396 */
4397CREATE OR REPLACE FUNCTION is_finite_float8(x double precision)
4398 RETURNS BOOL AS
4399$$
4400 SELECT $1 <> 'NaN'::float8 AND $1 <> 'Infinity'::float8 AND $1 <> '-Infinity'::float8;
4401$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
4402
4403/*
4404 * Latent (token-valued) distribution parameters.
4405 *
4406 * A distribution parameter may be a scalar provenance token -- another
4407 * random_variable (or an AGG_TOKEN cast to UUID) -- rather than a
4408 * concrete double. The parameter is then a random variable itself,
4409 * making the leaf a compound (hierarchical) distribution: e.g.
4410 * normal(M, 1) with M ~ normal(0, 10). The token constructors below
4411 * wire such parameters as children of the gate_rv, encoding each wired
4412 * slot as "$i" in the extra TEXT (a literal slot keeps its decimal TEXT,
4413 * so an all-literal call is byte-identical to the plain NUMERIC
4414 * constructor). Only the Monte Carlo sampler resolves the wires (per
4415 * iteration); every analytic path recognises the wired form and falls
4416 * through to MC.
4417 */
4418
4419/**
4420 * @brief Internal: build a two-parameter latent @c gate_rv.
4421 *
4422 * Each parameter is supplied as EITHER a token (@p pN_tok, a scalar
4423 * gate @c UUID) OR a literal (@p pN_lit); exactly one is non-NULL per
4424 * parameter. Token parameters are appended to the gate's wire vector
4425 * in order and referenced as @c "$i" in the @c extra TEXT; literal
4426 * parameters keep their decimal TEXT. Not @c STRICT: the NULLs are the
4427 * literal-vs-token sentinels.
4428 */
4429CREATE OR REPLACE FUNCTION rv_parametric2(
4430 family TEXT,
4431 p1_tok UUID, p1_lit double precision,
4432 p2_tok UUID, p2_lit double precision)
4433 RETURNS random_variable AS
4434$$
4435DECLARE
4436 token UUID;
4437 wires UUID[] := ARRAY[]::UUID[];
4438 s1 TEXT;
4439 s2 TEXT;
4440BEGIN
4441 IF p1_tok IS NOT NULL THEN
4442 wires := wires || p1_tok;
4443 s1 := '$' || (array_length(wires, 1) - 1);
4444 ELSE
4445 IF NOT provsql.is_finite_float8(p1_lit) THEN
4446 RAISE EXCEPTION 'provsql.%: literal parameter must be finite (got %)',
4447 family, p1_lit;
4448 END IF;
4449 s1 := p1_lit::TEXT;
4450 END IF;
4451 IF p2_tok IS NOT NULL THEN
4452 wires := wires || p2_tok;
4453 s2 := '$' || (array_length(wires, 1) - 1);
4454 ELSE
4455 IF NOT provsql.is_finite_float8(p2_lit) THEN
4456 RAISE EXCEPTION 'provsql.%: literal parameter must be finite (got %)',
4457 family, p2_lit;
4458 END IF;
4459 s2 := p2_lit::TEXT;
4460 END IF;
4461 token := public.uuid_generate_v4();
4462 PERFORM provsql.create_gate(token, 'rv', wires, NULL, NULL,
4463 family || ':' || s1 || ',' || s2);
4464 RETURN provsql.random_variable_make(token);
4465END
4466$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE;
4467
4469 * @brief Internal: build a one-parameter latent @c gate_rv (rate/scale).
4470 */
4471CREATE OR REPLACE FUNCTION rv_parametric1(family TEXT, p_tok UUID)
4472 RETURNS random_variable AS
4473$$
4474DECLARE
4475 token UUID;
4476BEGIN
4477 token := public.uuid_generate_v4();
4478 PERFORM provsql.create_gate(token, 'rv', ARRAY[p_tok], NULL, NULL, family || ':$0');
4479 RETURN provsql.random_variable_make(token);
4480END
4481$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4482
4483/*
4484 * Token-accepting constructor overloads. For each NUMERIC family the
4485 * three mixed-arity forms (token, literal), (literal, token), (token,
4486 * token) let any parameter be a random_variable; an AGG_TOKEN parameter
4487 * is passed as @c (agg)::UUID::random_variable. The all-literal call
4488 * still resolves to the plain NUMERIC constructor (an exact match beats
4489 * the implicit NUMERIC->random_variable cast), so the literal fast path
4490 * is unchanged. STRICT: a NULL parameter yields a NULL random_variable.
4491 */
4492
4493-- normal(mu, sigma)
4494CREATE OR REPLACE FUNCTION normal(mu random_variable, sigma double precision)
4495 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('normal', ($1)::UUID, NULL, NULL, $2); $$
4496 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4497CREATE OR REPLACE FUNCTION normal(mu double precision, sigma random_variable)
4498 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('normal', NULL, $1, ($2)::UUID, NULL); $$
4499 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4500CREATE OR REPLACE FUNCTION normal(mu random_variable, sigma random_variable)
4501 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('normal', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4502 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4503
4504-- logistic(mu, s)
4505CREATE OR REPLACE FUNCTION logistic(mu random_variable, s double precision)
4506 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('logistic', ($1)::UUID, NULL, NULL, $2); $$
4507 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4508CREATE OR REPLACE FUNCTION logistic(mu double precision, s random_variable)
4509 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('logistic', NULL, $1, ($2)::UUID, NULL); $$
4510 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4511CREATE OR REPLACE FUNCTION logistic(mu random_variable, s random_variable)
4512 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('logistic', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4513 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4514
4515-- uniform(a, b)
4516CREATE OR REPLACE FUNCTION uniform(a random_variable, b double precision)
4517 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('uniform', ($1)::UUID, NULL, NULL, $2); $$
4518 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4519CREATE OR REPLACE FUNCTION uniform(a double precision, b random_variable)
4520 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('uniform', NULL, $1, ($2)::UUID, NULL); $$
4521 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4522CREATE OR REPLACE FUNCTION uniform(a random_variable, b random_variable)
4523 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('uniform', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4524 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4525
4526-- exponential(lambda)
4527CREATE OR REPLACE FUNCTION exponential(lambda random_variable)
4528 RETURNS random_variable AS $$ SELECT provsql.rv_parametric1('exponential', ($1)::UUID); $$
4529 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4530
4531-- gamma(k, lambda)
4532CREATE OR REPLACE FUNCTION gamma(k random_variable, lambda double precision)
4533 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('gamma', ($1)::UUID, NULL, NULL, $2); $$
4534 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4535CREATE OR REPLACE FUNCTION gamma(k double precision, lambda random_variable)
4536 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('gamma', NULL, $1, ($2)::UUID, NULL); $$
4537 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4538CREATE OR REPLACE FUNCTION gamma(k random_variable, lambda random_variable)
4539 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('gamma', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4540 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4541
4542-- lognormal(mu, sigma)
4543CREATE OR REPLACE FUNCTION lognormal(mu random_variable, sigma double precision)
4544 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('lognormal', ($1)::UUID, NULL, NULL, $2); $$
4545 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4546CREATE OR REPLACE FUNCTION lognormal(mu double precision, sigma random_variable)
4547 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('lognormal', NULL, $1, ($2)::UUID, NULL); $$
4548 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4549CREATE OR REPLACE FUNCTION lognormal(mu random_variable, sigma random_variable)
4550 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('lognormal', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4551 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4552
4553-- weibull(k, lambda)
4554CREATE OR REPLACE FUNCTION weibull(k random_variable, lambda double precision)
4555 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('weibull', ($1)::UUID, NULL, NULL, $2); $$
4556 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4557CREATE OR REPLACE FUNCTION weibull(k double precision, lambda random_variable)
4558 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('weibull', NULL, $1, ($2)::UUID, NULL); $$
4559 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4560CREATE OR REPLACE FUNCTION weibull(k random_variable, lambda random_variable)
4561 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('weibull', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4562 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4563
4564-- pareto(xm, alpha)
4565CREATE OR REPLACE FUNCTION pareto(xm random_variable, alpha double precision)
4566 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('pareto', ($1)::UUID, NULL, NULL, $2); $$
4567 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4568CREATE OR REPLACE FUNCTION pareto(xm double precision, alpha random_variable)
4569 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('pareto', NULL, $1, ($2)::UUID, NULL); $$
4570 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4571CREATE OR REPLACE FUNCTION pareto(xm random_variable, alpha random_variable)
4572 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('pareto', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4573 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4574
4575-- beta(alpha, beta)
4576CREATE OR REPLACE FUNCTION beta(alpha random_variable, beta double precision)
4577 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('beta', ($1)::UUID, NULL, NULL, $2); $$
4578 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4579CREATE OR REPLACE FUNCTION beta(alpha double precision, beta random_variable)
4580 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('beta', NULL, $1, ($2)::UUID, NULL); $$
4581 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4582CREATE OR REPLACE FUNCTION beta(alpha random_variable, beta random_variable)
4583 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('beta', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4584 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4585
4586-- inverse_gamma(alpha, beta)
4587CREATE OR REPLACE FUNCTION inverse_gamma(alpha random_variable, beta double precision)
4588 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('inverse_gamma', ($1)::UUID, NULL, NULL, $2); $$
4589 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4590CREATE OR REPLACE FUNCTION inverse_gamma(alpha double precision, beta random_variable)
4591 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('inverse_gamma', NULL, $1, ($2)::UUID, NULL); $$
4592 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4593CREATE OR REPLACE FUNCTION inverse_gamma(alpha random_variable, beta random_variable)
4594 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('inverse_gamma', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4595 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4596
4597-- inverse_gaussian(mu, lambda)
4598CREATE OR REPLACE FUNCTION inverse_gaussian(mu random_variable, lambda double precision)
4599 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('inverse_gaussian', ($1)::UUID, NULL, NULL, $2); $$
4600 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4601CREATE OR REPLACE FUNCTION inverse_gaussian(mu double precision, lambda random_variable)
4602 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('inverse_gaussian', NULL, $1, ($2)::UUID, NULL); $$
4603 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4604CREATE OR REPLACE FUNCTION inverse_gaussian(mu random_variable, lambda random_variable)
4605 RETURNS random_variable AS $$ SELECT provsql.rv_parametric2('inverse_gaussian', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
4606 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
4607
4608/**
4609 * @brief Construct a normal-distribution random variable
4610 *
4611 * Creates a fresh <tt>gate_rv</tt> with @c "normal:μ,σ" stored in
4612 * the gate's @c extra field, and returns a <tt>random_variable</tt>
4613 * pointing at it.
4614 *
4615 * Validation:
4616 * - @p mu and @p sigma must be finite (no @c NaN, no @c ±Infinity).
4617 * - @p sigma must be non-negative.
4618 * - When @p sigma is zero the distribution degenerates to the Dirac
4619 * at @p mu; the call is silently routed through @c as_random(mu),
4620 * producing a @c gate_value rather than a zero-variance @c gate_rv.
4621 * This keeps the sampler / moment / boundcheck paths free of σ=0
4622 * special cases and lets <tt>normal(x, 0)</tt> share its gate with
4623 * <tt>as_random(x)</tt>.
4624 *
4625 * @warning The <tt>VOLATILE</tt> marking is load-bearing and must
4626 * not be weakened. Each call mints a fresh <tt>uuid_generate_v4</tt>
4627 * token because two calls to <tt>normal(0, 1)</tt> are *independent*
4628 * random variables; if PostgreSQL were allowed to fold the function
4629 * (which it would under <tt>STABLE</tt> / <tt>IMMUTABLE</tt>), two
4630 * calls in the same query would share a UUID and collapse into a
4631 * single dependent RV, silently breaking the c-table semantics.
4632 * Same warning applies to @c uniform and @c exponential below.
4633 *
4634 * @sa <a href="https://en.wikipedia.org/wiki/Normal_distribution">Wikipedia: Normal distribution</a>
4635 */
4636CREATE OR REPLACE FUNCTION normal(mu double precision, sigma double precision)
4637 RETURNS random_variable AS
4639DECLARE
4640 token UUID;
4641BEGIN
4642 IF NOT provsql.is_finite_float8(mu) OR NOT provsql.is_finite_float8(sigma) THEN
4643 RAISE EXCEPTION 'provsql.normal: parameters must be finite (got mu=%, sigma=%)', mu, sigma;
4644 END IF;
4645 IF sigma < 0 THEN
4646 RAISE EXCEPTION 'provsql.normal: sigma must be non-negative (got %)', sigma;
4647 END IF;
4648 IF sigma = 0 THEN
4649 RETURN provsql.as_random(mu);
4650 END IF;
4651 token := public.uuid_generate_v4();
4652 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'normal:' || mu || ',' || sigma);
4653 RETURN provsql.random_variable_make(token);
4654END
4655$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4656
4657/**
4658 * @brief Construct a logistic-distribution random variable Logistic(μ, s)
4659 *
4660 * The location-scale family whose CDF is the logistic sigmoid; a threshold
4661 * event over a Logistic(0, 1) noise realises the logit link exactly
4662 * (@c P(eps < score) = 1/(1 + exp(-score))), the natural link for a
4663 * log-odds / latent-utility selection model.
4664 *
4665 * Validation:
4666 * - @p mu and @p s must be finite.
4667 * - @p s (the scale) must be non-negative; <tt>s = 0</tt> is the Dirac at
4668 * @p mu, routed through @c as_random(mu) as with @c normal's sigma = 0.
4669 *
4670 * @param mu location (the mean and median).
4671 * @param s scale (> 0); the variance is @f$\pi^2 s^2 / 3@f$.
4672 * @return a @c random_variable token for Logistic(μ, s).
4673 *
4674 * @sa <a href="https://en.wikipedia.org/wiki/Logistic_distribution">Wikipedia: Logistic distribution</a>
4675 */
4676CREATE OR REPLACE FUNCTION logistic(mu double precision, s double precision)
4677 RETURNS random_variable AS
4678$$
4679DECLARE
4680 token UUID;
4681BEGIN
4682 IF NOT provsql.is_finite_float8(mu) OR NOT provsql.is_finite_float8(s) THEN
4683 RAISE EXCEPTION 'provsql.logistic: parameters must be finite (got mu=%, s=%)', mu, s;
4684 END IF;
4685 IF s < 0 THEN
4686 RAISE EXCEPTION 'provsql.logistic: scale s must be non-negative (got %)', s;
4687 END IF;
4688 IF s = 0 THEN
4689 RETURN provsql.as_random(mu);
4690 END IF;
4691 token := public.uuid_generate_v4();
4692 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'logistic:' || mu || ',' || s);
4693 RETURN provsql.random_variable_make(token);
4694END
4695$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4696
4697/**
4698 * @brief Construct a uniform-distribution random variable on [a, b]
4699 *
4700 * Validation:
4701 * - @p a and @p b must be finite.
4702 * - @p a must be ≤ @p b (reversed bounds are rejected).
4703 * - When <tt>a = b</tt> the distribution is the Dirac at @p a; the
4704 * call is silently routed through @c as_random(a) for the same
4705 * reason as @c normal with @p sigma = 0.
4706 *
4707 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4708 * @ref normal.
4710 * @sa <a href="https://en.wikipedia.org/wiki/Continuous_uniform_distribution">Wikipedia: Continuous uniform distribution</a>
4711 */
4712CREATE OR REPLACE FUNCTION uniform(a double precision, b double precision)
4713 RETURNS random_variable AS
4714$$
4715DECLARE
4716 token UUID;
4717BEGIN
4718 IF NOT provsql.is_finite_float8(a) OR NOT provsql.is_finite_float8(b) THEN
4719 RAISE EXCEPTION 'provsql.uniform: bounds must be finite (got a=%, b=%)', a, b;
4720 END IF;
4721 IF a > b THEN
4722 RAISE EXCEPTION 'provsql.uniform: a must be <= b (got a=%, b=%)', a, b;
4723 END IF;
4724 IF a = b THEN
4725 RETURN provsql.as_random(a);
4726 END IF;
4727 token := public.uuid_generate_v4();
4728 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'uniform:' || a || ',' || b);
4729 RETURN provsql.random_variable_make(token);
4731$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4732
4733/**
4734 * @brief Construct an exponential-distribution random variable with rate λ
4735 *
4736 * Validation:
4737 * - @p lambda must be finite and strictly positive. No degenerate
4738 * form exists for the exponential distribution, so there is no
4739 * silent route through @c as_random.
4740 *
4741 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4742 * @ref normal.
4743 *
4744 * @sa <a href="https://en.wikipedia.org/wiki/Exponential_distribution">Wikipedia: Exponential distribution</a>
4745 */
4746CREATE OR REPLACE FUNCTION exponential(lambda double precision)
4747 RETURNS random_variable AS
4748$$
4749DECLARE
4750 token UUID;
4751BEGIN
4752 IF NOT provsql.is_finite_float8(lambda) THEN
4753 RAISE EXCEPTION 'provsql.exponential: lambda must be finite (got %)', lambda;
4754 END IF;
4755 IF lambda <= 0 THEN
4756 RAISE EXCEPTION 'provsql.exponential: lambda must be strictly positive (got %)', lambda;
4757 END IF;
4758 token := public.uuid_generate_v4();
4759 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'exponential:' || lambda);
4760 RETURN provsql.random_variable_make(token);
4761END
4762$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4763
4764/**
4765 * @brief Construct an Erlang-distribution random variable, sum of
4766 * @p k i.i.d. exponentials with shared rate @p lambda
4767 *
4768 * The Erlang distribution is the sum of @p k independent
4769 * <tt>Exp(λ)</tt> random variables (equivalently the gamma with
4770 * INTEGER shape). It is the natural closure of i.i.d.
4771 * exponentials under addition, and is materialised here as a single
4772 * <tt>gate_rv</tt> so the analytic CDF and closed-form moments fire
4773 * directly (rather than the sampler having to draw and sum @p k
4774 * exponential leaves per Monte-Carlo iteration).
4775 *
4776 * Validation:
4777 * - @p k must be ≥ 1. The degenerate @c k=1 case is silently routed
4778 * through @c exponential so <tt>erlang(1, λ)</tt> shares its gate
4779 * with <tt>exponential(λ)</tt>.
4780 * - @p lambda must be finite and strictly positive.
4781 *
4782 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4783 * @ref normal.
4784 *
4785 * @sa <a href="https://en.wikipedia.org/wiki/Erlang_distribution">Wikipedia: Erlang distribution</a>
4786 */
4787CREATE OR REPLACE FUNCTION erlang(k INTEGER, lambda double precision)
4788 RETURNS random_variable AS
4789$$
4790DECLARE
4791 token UUID;
4792BEGIN
4793 IF k < 1 THEN
4794 RAISE EXCEPTION 'provsql.erlang: k must be >= 1 (got %)', k;
4795 END IF;
4796 IF NOT provsql.is_finite_float8(lambda) THEN
4797 RAISE EXCEPTION 'provsql.erlang: lambda must be finite (got %)', lambda;
4798 END IF;
4799 IF lambda <= 0 THEN
4800 RAISE EXCEPTION 'provsql.erlang: lambda must be strictly positive (got %)', lambda;
4801 END IF;
4802 IF k = 1 THEN
4803 RETURN provsql.exponential(lambda);
4804 END IF;
4805 token := public.uuid_generate_v4();
4806 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'erlang:' || k || ',' || lambda);
4807 RETURN provsql.random_variable_make(token);
4808END
4809$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4810
4811/**
4812 * @brief Construct a gamma-distribution random variable with shape @p k
4813 * (any positive real) and rate @p lambda
4814 *
4815 * The gamma distribution generalises Erlang to non-INTEGER shape; its
4816 * CDF is the regularised lower incomplete gamma, evaluated in closed
4817 * form by the analytic passes. Sums of independent gammas with the
4818 * same rate fold to a single gamma in the simplifier.
4819 *
4820 * Validation:
4821 * - @p k must be finite and strictly positive. An INTEGER @p k (in
4822 * @c INTEGER range) is silently routed through @c erlang -- the gamma
4823 * with INTEGER shape *is* Erlang -- so <tt>gamma(2, λ)</tt> shares
4824 * its gate encoding and closure interplay with <tt>erlang(2, λ)</tt>.
4825 * - @p lambda must be finite and strictly positive.
4826 *
4827 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4828 * @ref normal.
4829 *
4830 * @sa <a href="https://en.wikipedia.org/wiki/Gamma_distribution">Wikipedia: Gamma distribution</a>
4832CREATE OR REPLACE FUNCTION gamma(k double precision, lambda double precision)
4833 RETURNS random_variable AS
4835DECLARE
4836 token UUID;
4837BEGIN
4838 IF NOT provsql.is_finite_float8(k) THEN
4839 RAISE EXCEPTION 'provsql.gamma: k must be finite (got %)', k;
4840 END IF;
4841 IF k <= 0 THEN
4842 RAISE EXCEPTION 'provsql.gamma: k must be strictly positive (got %)', k;
4843 END IF;
4844 IF NOT provsql.is_finite_float8(lambda) THEN
4845 RAISE EXCEPTION 'provsql.gamma: lambda must be finite (got %)', lambda;
4846 END IF;
4847 IF lambda <= 0 THEN
4848 RAISE EXCEPTION 'provsql.gamma: lambda must be strictly positive (got %)', lambda;
4849 END IF;
4850 IF k = floor(k) AND k <= 2147483647 THEN
4851 RETURN provsql.erlang(k::INTEGER, lambda);
4852 END IF;
4853 token := public.uuid_generate_v4();
4854 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'gamma:' || k || ',' || lambda);
4855 RETURN provsql.random_variable_make(token);
4856END
4857$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4858
4859/**
4860 * @brief Construct a chi-squared random variable with @p k degrees of
4861 * freedom: syntactic sugar for <tt>gamma(k/2, 1/2)</tt>
4862 *
4863 * @p k is accepted as @c double @c precision so fractional degrees of
4864 * freedom work; it must be finite and strictly positive. Even degrees
4865 * of freedom route through @c erlang via @c gamma's INTEGER-shape rule.
4866 *
4867 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4868 * @ref normal.
4870 * @sa <a href="https://en.wikipedia.org/wiki/Chi-squared_distribution">Wikipedia: Chi-squared distribution</a>
4871 */
4872CREATE OR REPLACE FUNCTION chi_squared(k double precision)
4873 RETURNS random_variable AS
4874$$
4875BEGIN
4876 IF NOT provsql.is_finite_float8(k) THEN
4877 RAISE EXCEPTION 'provsql.chi_squared: k must be finite (got %)', k;
4878 END IF;
4879 IF k <= 0 THEN
4880 RAISE EXCEPTION 'provsql.chi_squared: k must be strictly positive (got %)', k;
4881 END IF;
4882 RETURN provsql.gamma(k / 2, 0.5);
4883END
4884$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4885
4886/**
4887 * @brief Construct a log-normal random variable: @c exp of a
4888 * Normal(@p mu, @p sigma), parameterised by the underlying
4889 * normal (so its median is <tt>exp(mu)</tt> and its mean
4890 * <tt>exp(mu + sigma^2/2)</tt>)
4891 *
4892 * The multiplicative counterpart of @c normal: products of independent
4893 * lognormals fold to a lognormal in the simplifier, and the
4894 * <tt>exp(normal(...))</tt> / <tt>ln(lognormal(...))</tt> bridges fold
4895 * in both directions, so log-scale models stay closed-form.
4896 *
4897 * Validation mirrors @c normal: both parameters must be finite,
4898 * @p sigma non-negative; the degenerate @c sigma = 0 case is silently
4899 * routed through @c as_random (a Dirac at <tt>exp(mu)</tt>).
4900 *
4901 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4902 * @ref normal.
4903 *
4904 * @sa <a href="https://en.wikipedia.org/wiki/Log-normal_distribution">Wikipedia: Log-normal distribution</a>
4906CREATE OR REPLACE FUNCTION lognormal(mu double precision, sigma double precision)
4907 RETURNS random_variable AS
4908$$
4909DECLARE
4910 token UUID;
4911BEGIN
4912 IF NOT provsql.is_finite_float8(mu) OR NOT provsql.is_finite_float8(sigma) THEN
4913 RAISE EXCEPTION 'provsql.lognormal: parameters must be finite (got mu=%, sigma=%)', mu, sigma;
4914 END IF;
4915 IF sigma < 0 THEN
4916 RAISE EXCEPTION 'provsql.lognormal: sigma must be non-negative (got %)', sigma;
4917 END IF;
4918 IF sigma = 0 THEN
4919 RETURN provsql.as_random(exp(mu));
4920 END IF;
4921 token := public.uuid_generate_v4();
4922 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'lognormal:' || mu || ',' || sigma);
4923 RETURN provsql.random_variable_make(token);
4924END
4925$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4926
4927/**
4928 * @brief Construct a Weibull random variable with shape @p k and
4929 * scale @p lambda
4930 *
4931 * @p lambda is the SCALE (the 63.2% quantile), not a rate: @c k = 1 is
4932 * the exponential with rate <tt>1/lambda</tt>, and that case is
4933 * silently routed through @c exponential to share its gate. The shape
4934 * tunes the hazard: @c k < 1 infant mortality, @c k > 1 wear-out.
4935 * Quantiles are exact, truncated moments are closed-form (via the
4936 * regularised incomplete gamma), and the min of i.i.d. Weibulls has a
4937 * closed-form mean (min-stability).
4938 *
4939 * Validation: both parameters must be finite and strictly positive.
4940 *
4941 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4942 * @ref normal.
4943 *
4944 * @sa <a href="https://en.wikipedia.org/wiki/Weibull_distribution">Wikipedia: Weibull distribution</a>
4945 */
4946CREATE OR REPLACE FUNCTION weibull(k double precision, lambda double precision)
4947 RETURNS random_variable AS
4948$$
4949DECLARE
4950 token UUID;
4951BEGIN
4952 IF NOT provsql.is_finite_float8(k) OR NOT provsql.is_finite_float8(lambda) THEN
4953 RAISE EXCEPTION 'provsql.weibull: parameters must be finite (got k=%, lambda=%)', k, lambda;
4954 END IF;
4955 IF k <= 0 OR lambda <= 0 THEN
4956 RAISE EXCEPTION 'provsql.weibull: parameters must be strictly positive (got k=%, lambda=%)', k, lambda;
4957 END IF;
4958 IF k = 1 THEN
4959 RETURN provsql.exponential(1 / lambda);
4960 END IF;
4961 token := public.uuid_generate_v4();
4962 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'weibull:' || k || ',' || lambda);
4963 RETURN provsql.random_variable_make(token);
4964END
4965$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
4966
4967/**
4968 * @brief Construct a Pareto random variable with scale (minimum)
4969 * @p xm and shape @p alpha
4970 *
4971 * The canonical heavy-tailed power law. Raw moments are @b infinite
4972 * for <tt>alpha <= k</tt> and reported as <tt>Infinity</tt> (the mean
4973 * for <tt>alpha <= 1</tt>, the variance for <tt>alpha <= 2</tt>)
4974 * rather than estimated; quantiles, truncated moments, conditional
4975 * sampling (self-similarity: <tt>X | X > a</tt> is Pareto(a, alpha)),
4976 * and Pareto-vs-Pareto comparisons are all exact.
4977 *
4978 * Validation: both parameters must be finite and strictly positive.
4979 *
4980 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
4981 * @ref normal.
4982 *
4983 * @sa <a href="https://en.wikipedia.org/wiki/Pareto_distribution">Wikipedia: Pareto distribution</a>
4984 */
4985CREATE OR REPLACE FUNCTION pareto(xm double precision, alpha double precision)
4986 RETURNS random_variable AS
4987$$
4988DECLARE
4989 token UUID;
4990BEGIN
4991 IF NOT provsql.is_finite_float8(xm) OR NOT provsql.is_finite_float8(alpha) THEN
4992 RAISE EXCEPTION 'provsql.pareto: parameters must be finite (got xm=%, alpha=%)', xm, alpha;
4993 END IF;
4994 IF xm <= 0 OR alpha <= 0 THEN
4995 RAISE EXCEPTION 'provsql.pareto: parameters must be strictly positive (got xm=%, alpha=%)', xm, alpha;
4996 END IF;
4997 token := public.uuid_generate_v4();
4998 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'pareto:' || xm || ',' || alpha);
4999 RETURN provsql.random_variable_make(token);
5000END
5001$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5002
5003/**
5004 * @brief Construct an inverse-gamma random variable with shape
5005 * @p alpha and scale @p beta
5006 *
5007 * The distribution of <tt>1/Y</tt> for <tt>Y ~ gamma(alpha, beta)</tt>
5008 * (the conjugate prior for a Gaussian variance). Its CDF is the
5009 * regularised upper incomplete gamma, evaluated in closed form by the
5010 * analytic passes; raw moments are @b infinite for <tt>alpha <= k</tt>
5011 * and reported as <tt>Infinity</tt> (the mean for <tt>alpha <= 1</tt>,
5012 * the variance for <tt>alpha <= 2</tt>) rather than estimated. Positive
5013 * scalings rescale @p beta in the simplifier.
5015 * Validation: both parameters must be finite and strictly positive.
5016 *
5017 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
5018 * @ref normal.
5019 *
5020 * @sa <a href="https://en.wikipedia.org/wiki/Inverse-gamma_distribution">Wikipedia: Inverse-gamma distribution</a>
5021 */
5022CREATE OR REPLACE FUNCTION inverse_gamma(alpha double precision, beta double precision)
5023 RETURNS random_variable AS
5024$$
5025DECLARE
5026 token UUID;
5027BEGIN
5028 IF NOT provsql.is_finite_float8(alpha) OR NOT provsql.is_finite_float8(beta) THEN
5029 RAISE EXCEPTION 'provsql.inverse_gamma: parameters must be finite (got alpha=%, beta=%)', alpha, beta;
5030 END IF;
5031 IF alpha <= 0 OR beta <= 0 THEN
5032 RAISE EXCEPTION 'provsql.inverse_gamma: parameters must be strictly positive (got alpha=%, beta=%)', alpha, beta;
5033 END IF;
5034 token := public.uuid_generate_v4();
5035 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'inverse_gamma:' || alpha || ',' || beta);
5036 RETURN provsql.random_variable_make(token);
5037END
5038$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5039
5040/**
5041 * @brief Construct an inverse-Gaussian (Wald) random variable with mean
5042 * @p mu and shape @p lambda
5043 *
5044 * The first-passage time of Brownian motion with drift: a positive,
5045 * right-skewed family. Its CDF has a closed form in the standard normal
5046 * @c Phi, so comparisons and quantiles are analytic; all raw moments are
5047 * finite. Positive scalings map <tt>c·IG(mu, lambda)</tt> to
5048 * <tt>IG(c·mu, c·lambda)</tt>, and a sum of independent inverse
5049 * Gaussians sharing the ratio <tt>lambda/mu²</tt> folds to a single
5050 * inverse Gaussian in the simplifier. @ref wald is an alias.
5052 * Validation: both parameters must be finite and strictly positive.
5053 *
5054 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
5055 * @ref normal.
5056 *
5057 * @sa <a href="https://en.wikipedia.org/wiki/Inverse_Gaussian_distribution">Wikipedia: Inverse Gaussian distribution</a>
5058 */
5059CREATE OR REPLACE FUNCTION inverse_gaussian(mu double precision, lambda double precision)
5060 RETURNS random_variable AS
5061$$
5062DECLARE
5063 token UUID;
5064BEGIN
5065 IF NOT provsql.is_finite_float8(mu) OR NOT provsql.is_finite_float8(lambda) THEN
5066 RAISE EXCEPTION 'provsql.inverse_gaussian: parameters must be finite (got mu=%, lambda=%)', mu, lambda;
5067 END IF;
5068 IF mu <= 0 OR lambda <= 0 THEN
5069 RAISE EXCEPTION 'provsql.inverse_gaussian: parameters must be strictly positive (got mu=%, lambda=%)', mu, lambda;
5070 END IF;
5071 token := public.uuid_generate_v4();
5072 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'inverse_gaussian:' || mu || ',' || lambda);
5073 RETURN provsql.random_variable_make(token);
5074END
5075$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5076
5077/**
5078 * @brief Wald distribution: alias for @ref inverse_gaussian.
5079 *
5080 * @sa <a href="https://en.wikipedia.org/wiki/Inverse_Gaussian_distribution">Wikipedia: Inverse Gaussian distribution</a>
5081 */
5082CREATE OR REPLACE FUNCTION wald(mu double precision, lambda double precision)
5083 RETURNS random_variable AS
5084$$
5085 SELECT provsql.inverse_gaussian(mu, lambda);
5086$$ LANGUAGE sql VOLATILE PARALLEL UNSAFE;
5087
5088/**
5089 * @brief Build a discrete (categorical) random variable from outcomes
5090 * and UNNORMALISED log-masses
5092 * The shared back end of the discrete count constructors (@c poisson,
5093 * @c binomial, @c geometric, @c hypergeometric,
5094 * @c negative_binomial), and directly usable for any custom discrete
5095 * pmf: the log-masses are shifted by their maximum (so only relative
5096 * magnitudes matter and no @c exp underflows), outcomes whose relative
5097 * mass is below <tt>1e-15</tt> are dropped, and the rest is
5098 * renormalised before being handed to @c categorical. Working in log
5099 * space keeps arbitrarily large parameters stable (e.g. a
5100 * <tt>Poisson(1000)</tt> pmf whose linear-space recurrence would
5101 * underflow at @c exp(-1000)).
5102 *
5103 * @param outcomes outcome values, same length as @p log_pmf
5104 * @param log_pmf natural logs of the (unnormalised) masses
5105 */
5106CREATE OR REPLACE FUNCTION categorical_from_log_pmf(
5107 outcomes double precision[], log_pmf double precision[])
5108 RETURNS random_variable AS
5109$$
5110DECLARE
5111 n INT := array_length(outcomes, 1);
5112 max_lp double precision := '-Infinity';
5113 kept_o double precision[] := '{}';
5114 kept_p double precision[] := '{}';
5115 total double precision := 0;
5116 v double precision;
5117 i INT;
5118BEGIN
5119 IF n IS NULL OR n = 0 OR n <> coalesce(array_length(log_pmf, 1), 0) THEN
5120 RAISE EXCEPTION 'provsql.categorical_from_log_pmf: outcomes and log_pmf must be non-empty arrays of the same length';
5121 END IF;
5122 FOR i IN 1..n LOOP
5123 IF log_pmf[i] > max_lp THEN max_lp := log_pmf[i]; END IF;
5124 END LOOP;
5125 IF max_lp = '-Infinity' THEN
5126 RAISE EXCEPTION 'provsql.categorical_from_log_pmf: all masses are zero';
5127 END IF;
5128 FOR i IN 1..n LOOP
5129 v := exp(log_pmf[i] - max_lp);
5130 IF v >= 1e-15 THEN
5131 kept_o := array_append(kept_o, outcomes[i]);
5132 kept_p := array_append(kept_p, v);
5133 total := total + v;
5134 END IF;
5135 END LOOP;
5136 FOR i IN 1..array_length(kept_p, 1) LOOP
5137 kept_p[i] := kept_p[i] / total;
5138 END LOOP;
5139 RETURN provsql.categorical(kept_p, kept_o);
5140END
5141$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5142
5143/**
5144 * @brief Construct a Poisson random variable with mean @p lambda, as a
5145 * truncated categorical
5146 *
5147 * The pmf is enumerated over <tt>[max(0, λ-12√λ), λ+12√λ+30]</tt> (the
5148 * omitted tails carry ~1e-30 of mass) by the log-space recurrence
5149 * <tt>ln p(k+1) = ln p(k) + ln λ - ln(k+1)</tt> and handed to
5150 * @c categorical_from_log_pmf, so moments, quantiles, and (in)equality
5151 * comparisons are exact over the enumerated support. @c lambda = 0 is
5152 * a Dirac at @c 0 (routed through @c as_random); supports up to 10000
5153 * outcomes (λ up to ~170000), beyond which it raises -- approximate
5154 * huge means by @c normal(λ, √λ) instead.
5155 *
5156 * @sa <a href="https://en.wikipedia.org/wiki/Poisson_distribution">Wikipedia: Poisson distribution</a>
5158CREATE OR REPLACE FUNCTION poisson(lambda double precision)
5159 RETURNS random_variable AS
5160$$
5161DECLARE
5162 lo INT;
5163 hi INT;
5164 outcomes double precision[] := '{}';
5165 lps double precision[] := '{}';
5166 lp double precision := 0;
5167 k INT;
5168BEGIN
5169 IF NOT provsql.is_finite_float8(lambda) OR lambda < 0 THEN
5170 RAISE EXCEPTION 'provsql.poisson: lambda must be finite and non-negative (got %)', lambda;
5171 END IF;
5172 IF lambda = 0 THEN
5173 RETURN provsql.as_random(0);
5174 END IF;
5175 lo := greatest(0, floor(lambda - 12 * sqrt(lambda)))::INT;
5176 hi := ceil(lambda + 12 * sqrt(lambda))::INT + 30;
5177 IF hi - lo + 1 > 10000 THEN
5178 RAISE EXCEPTION 'provsql.poisson: support window of % outcomes exceeds 10000; approximate with normal(%, sqrt(%))', hi - lo + 1, lambda, lambda;
5179 END IF;
5180 -- ln p(0) = -λ; walk the recurrence, keeping only the window.
5181 lp := -lambda;
5182 FOR k IN 1..hi LOOP
5183 lp := lp + ln(lambda) - ln(k::double precision);
5184 IF k >= lo THEN
5185 outcomes := array_append(outcomes, k::double precision);
5186 lps := array_append(lps, lp);
5187 END IF;
5188 END LOOP;
5189 IF lo = 0 THEN
5190 outcomes := array_prepend(0::double precision, outcomes);
5191 lps := array_prepend(-lambda, lps);
5192 END IF;
5193 RETURN provsql.categorical_from_log_pmf(outcomes, lps);
5194END
5195$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5197/**
5198 * @brief Poisson with a LATENT rate: @c poisson(random_variable).
5199 *
5200 * A latent (token-valued) rate cannot be enumerated into a categorical at
5201 * construction, so this builds a parametric @c gate_rv leaf (family
5202 * @c "poisson") wiring the rate, exactly like the continuous latent
5203 * constructors. Only the Monte Carlo sampler resolves the rate (per draw,
5204 * then draws a Poisson); @c observe weights by the Poisson pmf; the mean is
5205 * exact (E[Poisson(Λ)] = E[Λ], affine). Unblocks discrete-likelihood
5206 * posteriors such as @c "R | (poisson(120*R) = observed_count)".
5207 */
5208CREATE OR REPLACE FUNCTION poisson(lambda random_variable)
5209 RETURNS random_variable AS
5210$$ SELECT provsql.rv_parametric1('poisson', ($1)::UUID); $$
5211 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
5212
5213/**
5214 * @brief Construct a Beta(α, β) random variable on the unit interval
5215 *
5216 * The conjugate prior of Bernoulli / binomial success probabilities:
5217 * closed-form moments, CDF through the regularised incomplete beta,
5218 * quantiles through the generic CDF bisection over the finite
5219 * @c [0, 1] support, and closed-form truncated moments (interval
5220 * conditioning). <tt>Beta(1, 1)</tt> IS <tt>Uniform(0, 1)</tt> and is
5221 * silently routed through @c uniform to share its richer closed forms.
5222 *
5223 * Validation: both shapes must be finite and strictly positive.
5224 *
5225 * @warning <tt>VOLATILE</tt> is load-bearing; see the warning on
5226 * @ref normal.
5227 *
5228 * @sa <a href="https://en.wikipedia.org/wiki/Beta_distribution">Wikipedia: Beta distribution</a>
5229 */
5230CREATE OR REPLACE FUNCTION beta(alpha double precision, beta double precision)
5231 RETURNS random_variable AS
5232$$
5233DECLARE
5234 token UUID;
5235BEGIN
5236 IF NOT provsql.is_finite_float8(alpha) OR NOT provsql.is_finite_float8(beta) THEN
5237 RAISE EXCEPTION 'provsql.beta: parameters must be finite (got alpha=%, beta=%)', alpha, beta;
5238 END IF;
5239 IF alpha <= 0 OR beta <= 0 THEN
5240 RAISE EXCEPTION 'provsql.beta: parameters must be strictly positive (got alpha=%, beta=%)', alpha, beta;
5241 END IF;
5242 IF alpha = 1 AND beta = 1 THEN
5243 RETURN provsql.uniform(0, 1);
5244 END IF;
5245 token := public.uuid_generate_v4();
5246 PERFORM provsql.create_gate(token, 'rv', NULL, NULL, NULL, 'beta:' || alpha || ',' || beta);
5247 RETURN provsql.random_variable_make(token);
5248END
5249$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5250
5251/**
5252 * @brief Construct a Binomial(n, p) random variable (number of
5253 * successes in @p n independent trials), as a categorical
5254 *
5255 * Enumerated over <tt>{0..n}</tt> by the log-space recurrence
5256 * <tt>ln p(k+1) = ln p(k) + ln((n-k)/(k+1)) + ln(p/(1-p))</tt>
5257 * (outcomes below 1e-15 relative mass are dropped). @c p = 0 /
5258 * @c p = 1 are Diracs at @c 0 / @c n; @c n is capped at 10000.
5259 *
5260 * @sa <a href="https://en.wikipedia.org/wiki/Binomial_distribution">Wikipedia: Binomial distribution</a>
5261 */
5262CREATE OR REPLACE FUNCTION binomial(n INTEGER, p double precision)
5263 RETURNS random_variable AS
5264$$
5265DECLARE
5266 outcomes double precision[] := '{}';
5267 lps double precision[] := '{}';
5268 lp double precision;
5269 k INT;
5270BEGIN
5271 IF n IS NULL OR n < 0 THEN
5272 RAISE EXCEPTION 'provsql.binomial: n must be non-negative (got %)', n;
5273 END IF;
5274 IF NOT provsql.is_finite_float8(p) OR p < 0 OR p > 1 THEN
5275 RAISE EXCEPTION 'provsql.binomial: p must be in [0, 1] (got %)', p;
5276 END IF;
5277 IF n > 10000 THEN
5278 RAISE EXCEPTION 'provsql.binomial: n = % exceeds 10000; approximate with normal(n*p, sqrt(n*p*(1-p)))', n;
5279 END IF;
5280 IF n = 0 OR p = 0 THEN
5281 RETURN provsql.as_random(0);
5282 END IF;
5283 IF p = 1 THEN
5284 RETURN provsql.as_random(n);
5285 END IF;
5286 lp := n * ln(1 - p); -- ln p(0)
5287 outcomes := array_append(outcomes, 0::double precision);
5288 lps := array_append(lps, lp);
5289 FOR k IN 0..(n - 1) LOOP
5290 lp := lp + ln((n - k)::double precision / (k + 1)) + ln(p / (1 - p));
5291 outcomes := array_append(outcomes, (k + 1)::double precision);
5292 lps := array_append(lps, lp);
5293 END LOOP;
5294 RETURN provsql.categorical_from_log_pmf(outcomes, lps);
5295END
5296$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5297
5298/**
5299 * @brief Binomial with a fixed trial count and a LATENT success
5300 * probability: @c binomial(INTEGER, random_variable).
5301 *
5302 * @p n is a literal trial count; @p p is a latent (token-valued) success
5303 * probability (e.g. @c "40.0 / N" for a latent population size @c N).
5304 * Builds a parametric @c gate_rv leaf (family @c "binomial", @c extra
5305 * @c "binomial:n,$0") the Monte Carlo sampler resolves per draw; @c observe
5306 * weights by the Binomial pmf. Unblocks capture-recapture-style posteriors
5307 * such as @c "N | (binomial(50, 40.0/N) = recaptured_count)".
5308 */
5309CREATE OR REPLACE FUNCTION binomial(n INTEGER, p random_variable)
5310 RETURNS random_variable AS
5311$$ SELECT provsql.rv_parametric2('binomial', NULL, $1::double precision,
5312 ($2)::UUID, NULL); $$
5313 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
5314
5315/**
5316 * @brief Construct a Geometric(p) random variable -- the number of
5317 * TRIALS up to and including the first success (support
5318 * starting at 1; subtract 1 for the failures convention)
5319 *
5320 * <tt>P(X = k) = (1-p)^{k-1} p</tt>, enumerated up to the 1e-15
5321 * relative-mass tail and renormalised. @c p = 1 is a Dirac at @c 1.
5322 *
5323 * @sa <a href="https://en.wikipedia.org/wiki/Geometric_distribution">Wikipedia: Geometric distribution</a>
5324 */
5325CREATE OR REPLACE FUNCTION geometric(p double precision)
5326 RETURNS random_variable AS
5327$$
5328DECLARE
5329 k_max INT;
5330 outcomes double precision[] := '{}';
5331 lps double precision[] := '{}';
5332 k INT;
5333BEGIN
5334 IF NOT provsql.is_finite_float8(p) OR p <= 0 OR p > 1 THEN
5335 RAISE EXCEPTION 'provsql.geometric: p must be in (0, 1] (got %)', p;
5336 END IF;
5337 IF p = 1 THEN
5338 RETURN provsql.as_random(1);
5339 END IF;
5340 k_max := 1 + ceil(ln(1e-15) / ln(1 - p))::INT;
5341 IF k_max > 10000 THEN
5342 RAISE EXCEPTION 'provsql.geometric: support window of % outcomes exceeds 10000 (p = % is too small); approximate with exponential(%)', k_max, p, p;
5343 END IF;
5344 FOR k IN 1..k_max LOOP
5345 outcomes := array_append(outcomes, k::double precision);
5346 lps := array_append(lps, (k - 1) * ln(1 - p) + ln(p));
5347 END LOOP;
5348 RETURN provsql.categorical_from_log_pmf(outcomes, lps);
5349END
5350$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5351
5352/**
5353 * @brief Geometric with a LATENT success probability: @c geometric(random_variable).
5354 *
5355 * A latent (token-valued) @p p cannot be enumerated at construction, so this
5356 * builds a parametric @c gate_rv leaf (family @c "geometric") wiring the
5357 * probability, resolved per draw by the sampler. @c observe weights by the
5358 * geometric pmf; unblocks a Beta-Geometric conjugate posterior.
5359 */
5360CREATE OR REPLACE FUNCTION geometric(p random_variable)
5361 RETURNS random_variable AS
5362$$ SELECT provsql.rv_parametric1('geometric', ($1)::UUID); $$
5363 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
5364
5365/**
5366 * @brief Construct a Hypergeometric(N, K, n) random variable: the
5367 * number of marked items among @p n draws WITHOUT replacement
5368 * from a population of @p pop_n items of which @p k_marked are
5369 * marked
5370 *
5371 * The exact finite support <tt>[max(0, n-(N-K)), min(n, K)]</tt> is
5372 * enumerated by the pmf ratio recurrence (in log space, so large
5373 * populations cannot overflow) and normalised -- exact "sampling
5374 * without replacement" probabilities with no combinatorial functions
5375 * needed.
5376 *
5377 * @sa <a href="https://en.wikipedia.org/wiki/Hypergeometric_distribution">Wikipedia: Hypergeometric distribution</a>
5378 */
5379CREATE OR REPLACE FUNCTION hypergeometric(pop_n INTEGER, k_marked INTEGER, n INTEGER)
5380 RETURNS random_variable AS
5381$$
5382DECLARE
5383 lo INT;
5384 hi INT;
5385 outcomes double precision[] := '{}';
5386 lps double precision[] := '{}';
5387 lp double precision := 0; -- relative log-mass; normalised later
5388 k INT;
5389BEGIN
5390 IF pop_n IS NULL OR k_marked IS NULL OR n IS NULL
5391 OR pop_n < 0 OR k_marked < 0 OR n < 0
5392 OR k_marked > pop_n OR n > pop_n THEN
5393 RAISE EXCEPTION 'provsql.hypergeometric: need 0 <= k_marked, n <= pop_n (got pop_n=%, k_marked=%, n=%)', pop_n, k_marked, n;
5394 END IF;
5395 lo := greatest(0, n - (pop_n - k_marked));
5396 hi := least(n, k_marked);
5397 IF hi - lo + 1 > 10000 THEN
5398 RAISE EXCEPTION 'provsql.hypergeometric: support window of % outcomes exceeds 10000', hi - lo + 1;
5399 END IF;
5400 outcomes := array_append(outcomes, lo::double precision);
5401 lps := array_append(lps, lp);
5402 FOR k IN lo..(hi - 1) LOOP
5403 -- pmf(k+1)/pmf(k) = (K-k)(n-k) / ((k+1)(N-K-n+k+1))
5404 lp := lp + ln((k_marked - k)::double precision * (n - k))
5405 - ln((k + 1)::double precision * (pop_n - k_marked - n + k + 1));
5406 outcomes := array_append(outcomes, (k + 1)::double precision);
5407 lps := array_append(lps, lp);
5408 END LOOP;
5409 RETURN provsql.categorical_from_log_pmf(outcomes, lps);
5410END
5411$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5412
5413/**
5414 * @brief Construct a negative-binomial random variable: the number of
5415 * FAILURES before the @p r-th success (support starting at 0),
5416 * with real @p r > 0 allowed (the Polya / overdispersed-count
5417 * parameterisation, the Poisson-Gamma mixture)
5418 *
5419 * <tt>P(X = k) = C(k+r-1, k) p^r (1-p)^k</tt>, enumerated by the
5420 * log-space recurrence
5421 * <tt>ln p(k+1) = ln p(k) + ln((k+r)/(k+1)) + ln(1-p)</tt> up to the
5422 * 1e-15 relative-mass tail. @c p = 1 is a Dirac at @c 0.
5423 *
5424 * @sa <a href="https://en.wikipedia.org/wiki/Negative_binomial_distribution">Wikipedia: Negative binomial distribution</a>
5425 */
5426CREATE OR REPLACE FUNCTION negative_binomial(r double precision, p double precision)
5427 RETURNS random_variable AS
5428$$
5429DECLARE
5430 outcomes double precision[] := '{}';
5431 lps double precision[] := '{}';
5432 lp double precision;
5433 max_lp double precision;
5434 mean double precision;
5435 k INT := 0;
5436BEGIN
5437 IF NOT provsql.is_finite_float8(r) OR r <= 0 THEN
5438 RAISE EXCEPTION 'provsql.negative_binomial: r must be finite and strictly positive (got %)', r;
5439 END IF;
5440 IF NOT provsql.is_finite_float8(p) OR p <= 0 OR p > 1 THEN
5441 RAISE EXCEPTION 'provsql.negative_binomial: p must be in (0, 1] (got %)', p;
5442 END IF;
5443 IF p = 1 THEN
5444 RETURN provsql.as_random(0);
5445 END IF;
5446 mean := r * (1 - p) / p;
5447 lp := r * ln(p); -- ln p(0)
5448 max_lp := lp;
5449 outcomes := array_append(outcomes, 0::double precision);
5450 lps := array_append(lps, lp);
5451 LOOP
5452 lp := lp + ln((k + r) / (k + 1)) + ln(1 - p);
5453 k := k + 1;
5454 IF lp > max_lp THEN max_lp := lp; END IF;
5455 outcomes := array_append(outcomes, k::double precision);
5456 lps := array_append(lps, lp);
5457 EXIT WHEN k > mean AND lp < max_lp + ln(1e-15);
5458 IF k >= 10000 THEN
5459 RAISE EXCEPTION 'provsql.negative_binomial: support window exceeds 10000 outcomes (r=%, p=%)', r, p;
5460 END IF;
5461 END LOOP;
5462 RETURN provsql.categorical_from_log_pmf(outcomes, lps);
5463END
5464$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5465
5466/*
5467 * NegativeBinomial with a LATENT parameter: the count r (number of successes)
5468 * stays a plain number while the success probability p is a random_variable,
5469 * built as a parametric gate_rv leaf (family "negative_binomial") -- the
5470 * Beta-NegativeBinomial conjugate shape. The all-random and latent-r forms
5471 * are provided for uniformity with the continuous constructors.
5472 */
5473CREATE OR REPLACE FUNCTION negative_binomial(r double precision, p random_variable)
5474 RETURNS random_variable AS
5475$$ SELECT provsql.rv_parametric2('negative_binomial', NULL, $1, ($2)::UUID, NULL); $$
5476 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
5477CREATE OR REPLACE FUNCTION negative_binomial(r random_variable, p double precision)
5478 RETURNS random_variable AS
5479$$ SELECT provsql.rv_parametric2('negative_binomial', ($1)::UUID, NULL, NULL, $2); $$
5480 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
5481CREATE OR REPLACE FUNCTION negative_binomial(r random_variable, p random_variable)
5482 RETURNS random_variable AS
5483$$ SELECT provsql.rv_parametric2('negative_binomial', ($1)::UUID, NULL, ($2)::UUID, NULL); $$
5484 LANGUAGE sql STRICT VOLATILE PARALLEL UNSAFE;
5485
5486/**
5487 * @brief Catalog of the registered continuous-distribution families.
5488 *
5489 * One row per @c gate_rv family known to this build of the extension:
5490 * @c name is the on-disk token (the part before the colon in the gate's
5491 * @c extra encoding), @c nparams the parameter count, @c param_names the
5492 * conventional parameter symbols in @c extra order (e.g.
5493 * <tt>{μ, σ}</tt>), and @c label a short display glyph (e.g. @c "N",
5494 * @c "Γ"). UI clients (ProvSQL Studio's circuit inspector) read this to
5495 * render families they were not hard-coded for, so a newly added family
5496 * shows up without a client release.
5497 */
5498CREATE OR REPLACE FUNCTION rv_families()
5499 RETURNS TABLE(name TEXT, nparams INT, param_names TEXT[], label TEXT) AS
5500 'provsql','rv_families' LANGUAGE C STABLE PARALLEL SAFE;
5501
5502/**
5503 * @brief Construct a probabilistic-mixture random variable.
5504 *
5505 * Returns a @c random_variable whose distribution is a Bernoulli
5506 * mixture of two scalar RV roots: with probability <tt>P(p = true)</tt>
5507 * the mixture samples @p x, with the complementary probability it
5508 * samples @p y. The mixing token @p p is a @c gate_input Bernoulli
5509 * whose probability has been pinned with @c set_prob, and the same
5510 * @p p can be shared with other branches of the circuit -- the
5511 * Monte-Carlo sampler's per-iteration cache couples every reference
5512 * to the same draw, so users can build joint conditional structures
5513 * (e.g. <tt>mixture(p, X1, Y1) + mixture(p, X2, Y2)</tt> samples
5514 * X1 + X2 with prob π and Y1 + Y2 with prob 1-π).
5515 *
5516 * @p x and @p y may be any scalar RV root: a base @c gate_rv
5517 * (@c normal / @c uniform / @c exponential / @c erlang), a
5518 * @c gate_value Dirac (@c as_random), a @c gate_arith expression, or
5519 * another @c mixture. N-ary mixtures are built by composition --
5520 * <tt>mixture(p1, A, mixture(p2, B, C))</tt> realises a 3-component
5521 * mixture with effective weights <tt>π1, (1-π1)·π2, (1-π1)·(1-π2)</tt>.
5522 *
5523 * Validation:
5524 * - @p p must point to a Boolean gate (@c input, @c mulinput,
5525 * @c update, @c plus, @c times, @c monus, @c project, @c eq,
5526 * @c cmp, @c zero, @c one). Compound Boolean gates derive their
5527 * probability from their atoms via the active probability-evaluation
5528 * method; a bare @c gate_input's probability is whatever @c set_prob
5529 * pinned (@c set_prob is responsible for keeping it in [0, 1]).
5530 * - @p x and @p y must be scalar RV roots; aggregate / Boolean roots
5531 * are rejected at construction.
5532 *
5533 * Two calls to @c mixture with the same @c (p, x, y) operands collapse
5534 * to the same @c gate_mixture node by v5-hash, exactly like
5535 * @c arith(PLUS, X, Y). Draw independence is controlled by @p p:
5536 * sharing @p p couples branch selection across consumers via the
5537 * sampler's @c bool_cache_; minting independent Bernoullis (e.g. via
5538 * the @c mixture(p_value, …) overload) decouples them.
5539 *
5540 * @sa <a href="https://en.wikipedia.org/wiki/Mixture_distribution">Wikipedia: Mixture distribution</a>
5541 */
5542CREATE OR REPLACE FUNCTION mixture(
5543 p UUID, x random_variable, y random_variable)
5544 RETURNS random_variable AS
5545$$
5546DECLARE
5547 token UUID;
5548 p_kind provsql.PROVENANCE_GATE;
5549 x_uuid UUID;
5550 y_uuid UUID;
5551 x_kind provsql.PROVENANCE_GATE;
5552 y_kind provsql.PROVENANCE_GATE;
5553BEGIN
5554 p_kind := provsql.get_gate_type(p);
5555 IF p_kind NOT IN ('input','mulinput','update',
5556 'plus','times','monus',
5557 'project','eq','cmp',
5558 'zero','one') THEN
5559 RAISE EXCEPTION 'provsql.mixture: p must be a Boolean gate '
5560 '(input/mulinput/update/plus/times/monus/project/eq/cmp/zero/one), got %', p_kind
5561 USING ERRCODE = 'feature_not_supported',
5562 DETAIL = 'provsql-reason: mixture-argument-kind; scope: out-of-scope';
5563 END IF;
5564
5565 x_uuid := (x)::UUID;
5566 y_uuid := (y)::UUID;
5567 x_kind := provsql.get_gate_type(x_uuid);
5568 y_kind := provsql.get_gate_type(y_uuid);
5569 IF x_kind NOT IN ('rv','value','arith','mixture') THEN
5570 RAISE EXCEPTION 'provsql.mixture: x must be a scalar RV root (rv / value / arith / mixture), got %', x_kind
5571 USING ERRCODE = 'feature_not_supported',
5572 DETAIL = 'provsql-reason: mixture-argument-kind; scope: out-of-scope';
5573 END IF;
5574 IF y_kind NOT IN ('rv','value','arith','mixture') THEN
5575 RAISE EXCEPTION 'provsql.mixture: y must be a scalar RV root (rv / value / arith / mixture), got %', y_kind
5576 USING ERRCODE = 'feature_not_supported',
5577 DETAIL = 'provsql-reason: mixture-argument-kind; scope: out-of-scope';
5578 END IF;
5580 token := public.uuid_generate_v5(
5581 provsql.uuid_ns_provsql(),
5582 concat('mixture', p, x_uuid, y_uuid));
5583 PERFORM provsql.create_gate(token, 'mixture', ARRAY[p, x_uuid, y_uuid]);
5584 RETURN provsql.random_variable_make(token);
5585END
5586$$ LANGUAGE plpgsql STRICT IMMUTABLE PARALLEL SAFE;
5587
5588/**
5589 * @brief Ad-hoc mixture constructor that mints a fresh anonymous
5590 * @c gate_input Bernoulli with probability @p p_value.
5591 *
5592 * Sugar over the @c mixture(UUID, x, y) form: when the caller doesn't
5593 * care about reusing the Bernoulli token elsewhere in the circuit
5594 * (which is the common case &ndash; "give me a 0.3 / 0.7 weighted GMM,
5595 * I don't need to share the coin"), this overload creates the
5596 * underlying @c gate_input on the fly with a fresh
5597 * @c uuid_generate_v4() token, pins @p p_value via @c set_prob, and
5598 * threads everything into the UUID-keyed constructor.
5599 *
5600 * A probability of exactly 1 or 0 is a constant, not a coin: the
5601 * mixture is then @p x or @p y itself, and no gate is created.
5602 *
5603 * Each call mints a NEW Bernoulli, so two calls to
5604 * <tt>mixture(0.5, X, Y)</tt> are *independent* mixtures whose branch
5605 * selections are uncorrelated. When coupling is desired (e.g. two
5606 * mixtures sharing a coin), use the @c mixture(UUID, x, y) form with a
5607 * user-managed @c gate_input token.
5608 *
5609 * @warning <tt>VOLATILE</tt> is load-bearing for the same reason as
5610 * @ref normal and the other RV constructors -- folding under
5611 * @c STABLE / @c IMMUTABLE would collapse two independent draws into
5612 * one shared gate.
5613 *
5614 * @sa <a href="https://en.wikipedia.org/wiki/Mixture_distribution">Wikipedia: Mixture distribution</a>
5615 */
5616CREATE OR REPLACE FUNCTION mixture(
5617 p_value double precision,
5618 x random_variable,
5619 y random_variable)
5620 RETURNS random_variable AS
5621$$
5622DECLARE
5623 p_token UUID;
5624BEGIN
5625 IF p_value IS NULL OR p_value <> p_value OR p_value < 0 OR p_value > 1 THEN
5626 RAISE EXCEPTION 'provsql.mixture: probability must be in [0,1] (got %)', p_value;
5627 END IF;
5628 IF p_value = 1 THEN
5629 RETURN x;
5630 ELSIF p_value = 0 THEN
5631 RETURN y;
5632 END IF;
5633 p_token := public.uuid_generate_v4();
5634 PERFORM provsql.create_gate(p_token, 'input');
5635 PERFORM provsql.set_prob(p_token, p_value);
5636 RETURN provsql.mixture(p_token, x, y);
5637END
5638$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5639
5640/**
5641 * @brief Categorical-RV constructor over explicit (probabilities,
5642 * values) arrays.
5643 *
5644 * Builds a categorical-form @c gate_mixture directly: a fresh
5645 * @c gate_input "key" anchor and one @c gate_mulinput per outcome with
5646 * positive mass, all sharing the key. The wires
5647 * <tt>[key, mul_1, ..., mul_n]</tt> are what downstream evaluators
5648 * (@c Expectation, @c MonteCarloSampler, @c AnalyticEvaluator,
5649 * @c RangeCheck) recognise via @c isCategoricalMixture and treat as a
5650 * scalar RV with the categorical distribution @p probs over
5651 * @p outcomes.
5652 *
5653 * Validation:
5654 * - @p probs and @p outcomes must be non-null, same length, length &ge; 1.
5655 * - Each @c probs[i] must be finite, in <tt>[0, 1]</tt>, and the array
5656 * must sum to 1 within @c 1e-9.
5657 * - Each @c outcomes[i] must be finite.
5658 *
5659 * Each call mints a fresh key gate and a fresh set of mulinputs, so
5660 * two calls to @c categorical with the same arrays are *independent*
5661 * categorical RVs. The marking is @c VOLATILE accordingly.
5662 *
5663 * Degenerate case: a categorical with exactly one positive-mass
5664 * outcome reduces to @c as_random(v) at construction (the block would
5665 * just be a single mulinput, which is operationally a Dirac point
5666 * mass). Two such calls share the @c gate_value UUID via the v5
5667 * convention @c as_random already uses.
5668 *
5669 * @sa @c mixture for the Bernoulli-weighted choice constructor.
5670 * @sa <a href="https://en.wikipedia.org/wiki/Categorical_distribution">Wikipedia: Categorical distribution</a>
5671 */
5672CREATE OR REPLACE FUNCTION categorical(
5673 probs double precision[],
5674 outcomes double precision[])
5675 RETURNS random_variable AS
5676$$
5677DECLARE
5678 n INTEGER;
5679 p_sum double precision := 0.0;
5680 i INTEGER;
5681 key_token UUID;
5682 mix_token UUID;
5683 mul_token UUID;
5684 mul_tokens UUID[] := ARRAY[]::UUID[];
5685 mix_wires UUID[];
5686 pi_i double precision;
5687 vi_i double precision;
5688BEGIN
5689 IF probs IS NULL OR outcomes IS NULL THEN
5690 RAISE EXCEPTION 'provsql.categorical: probs and outcomes must be non-null';
5691 END IF;
5692 n := array_length(probs, 1);
5693 IF n IS NULL OR n < 1 THEN
5694 RAISE EXCEPTION 'provsql.categorical: probs must be non-empty';
5695 END IF;
5696 IF array_length(outcomes, 1) <> n THEN
5697 RAISE EXCEPTION 'provsql.categorical: probs and outcomes must have the same length (got % and %)',
5698 n, array_length(outcomes, 1);
5699 END IF;
5700
5701 FOR i IN 1..n LOOP
5702 pi_i := probs[i];
5703 vi_i := outcomes[i];
5704 -- PostgreSQL diverges from IEEE 754: NaN = NaN is TRUE there, so
5705 -- the canonical x <> x NaN test doesn't fire. Compare against the
5706 -- literal 'NaN'::float8 instead, and reject ±Infinity for outcomes
5707 -- explicitly.
5708 IF pi_i IS NULL OR pi_i = 'NaN'::float8 OR pi_i < 0 OR pi_i > 1 THEN
5709 RAISE EXCEPTION 'provsql.categorical: probs[%] must be in [0,1] (got %)', i, pi_i;
5710 END IF;
5711 IF vi_i IS NULL OR vi_i = 'NaN'::float8
5712 OR vi_i = 'Infinity'::float8 OR vi_i = '-Infinity'::float8 THEN
5713 RAISE EXCEPTION 'provsql.categorical: outcomes[%] must be finite (got %)', i, vi_i;
5714 END IF;
5715 p_sum := p_sum + pi_i;
5716 END LOOP;
5717 IF abs(p_sum - 1.0) > 1e-9 THEN
5718 RAISE EXCEPTION 'provsql.categorical: probs must sum to 1 within 1e-9 (got %)', p_sum;
5719 END IF;
5720
5721 -- Degenerate case: exactly one positive-mass outcome (the rest are
5722 -- zero). The "categorical" is then a Dirac point mass; skip the
5723 -- block-allocation entirely and return @c as_random(v), which yields
5724 -- a shared, v5-keyed gate_value -- exactly what downstream
5725 -- evaluators (rv_moment, AnalyticEvaluator, rv_support) treat
5726 -- specially. Saves a key gate and a mulinput per call, and lets
5727 -- two calls to @c categorical({1.0}, {v}) collide on the same
5728 -- gate_value UUID instead of producing distinct anonymous blocks.
5729 DECLARE
5730 nb_positive INTEGER := 0;
5731 only_idx INTEGER := 0;
5732 BEGIN
5733 FOR i IN 1..n LOOP
5734 IF probs[i] > 0.0 THEN
5735 nb_positive := nb_positive + 1;
5736 only_idx := i;
5737 END IF;
5738 END LOOP;
5739 IF nb_positive = 1 THEN
5740 RETURN provsql.as_random(outcomes[only_idx]);
5741 END IF;
5742 END;
5743
5744 -- Mint the block's key anchor. Probability 1.0 matches the
5745 -- joint-table convention: the categorical mass lives on the
5746 -- mulinputs, the key just identifies the block.
5747 key_token := public.uuid_generate_v4();
5748 PERFORM provsql.create_gate(key_token, 'input');
5749 PERFORM provsql.set_prob(key_token, 1.0);
5750
5751 -- One mulinput per positive-probability outcome. Zero-probability
5752 -- entries contribute no mass and are skipped: the gate_mixture's
5753 -- wire vector is otherwise polluted with no-op leaves.
5754 FOR i IN 1..n LOOP
5755 pi_i := probs[i];
5756 IF pi_i <= 0.0 THEN CONTINUE; END IF;
5757 mul_token := public.uuid_generate_v4();
5758 PERFORM provsql.create_gate(mul_token, 'mulinput', ARRAY[key_token],
5759 i - 1, NULL, outcomes[i]::TEXT);
5760 PERFORM provsql.set_prob(mul_token, pi_i);
5761 mul_tokens := mul_tokens || mul_token;
5762 END LOOP;
5763
5764 mix_wires := ARRAY[key_token] || mul_tokens;
5765 mix_token := public.uuid_generate_v4();
5766 PERFORM provsql.create_gate(mix_token, 'mixture', mix_wires);
5767 RETURN provsql.random_variable_make(mix_token);
5768END
5769$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5770
5771/**
5772 * @brief Gaussian-mixture-model (GMM) constructor.
5773 *
5774 * Packages the common fitted-density pattern -- a categorical choice
5775 * among Normal components -- into one call:
5776 *
5777 * @code
5778 * provsql.gmm(weights => ARRAY[0.3, 0.5, 0.2],
5779 * means => ARRAY[120.0, 380.0, 1200.0],
5780 * stddevs => ARRAY[40.0, 90.0, 250.0])
5781 * @endcode
5782 *
5783 * No new gate: the mixture decomposes into a stick-breaking cascade of
5784 * Bernoulli @c gate_mixture nodes over @c gate_rv Normal leaves
5785 * (component @c i is selected with conditional probability
5786 * @c w_i / (w_i + ... + w_n), so the joint selection probabilities are
5787 * exactly @p weights), which every evaluator already handles: moments
5788 * are closed-form through the mixture recursion, sampling is exact,
5789 * and comparisons ride the existing mixture machinery. Zero-weight
5790 * components are skipped; a single positive-weight component returns
5791 * its Normal directly (no mixture node).
5792 *
5793 * Validation mirrors @c categorical: same-length non-empty arrays,
5794 * weights finite in <tt>[0, 1]</tt> summing to 1 within @c 1e-9; the
5795 * component parameters are validated by @c provsql.normal (finite
5796 * @c mu, non-negative @c sigma; @c sigma @c = @c 0 degenerates to a
5797 * Dirac component).
5799 * @sa @c mixture, @c categorical, @c normal
5800 * @sa <a href="https://en.wikipedia.org/wiki/Mixture_model">Wikipedia: Mixture model</a>
5801 */
5802CREATE OR REPLACE FUNCTION gmm(
5803 weights double precision[],
5804 means double precision[],
5805 stddevs double precision[])
5806 RETURNS random_variable AS
5807$$
5808DECLARE
5809 n INTEGER;
5810 w_sum double precision := 0.0;
5811 i INTEGER;
5812 acc random_variable := NULL;
5813 remaining double precision := 0.0;
5814BEGIN
5815 IF weights IS NULL OR means IS NULL OR stddevs IS NULL THEN
5816 RAISE EXCEPTION 'provsql.gmm: weights, means, and stddevs must be non-null';
5817 END IF;
5818 n := array_length(weights, 1);
5819 IF n IS NULL OR n < 1 THEN
5820 RAISE EXCEPTION 'provsql.gmm: weights must be non-empty';
5821 END IF;
5822 IF array_length(means, 1) <> n OR array_length(stddevs, 1) <> n THEN
5823 RAISE EXCEPTION 'provsql.gmm: weights, means, and stddevs must have the same length (got %, %, %)',
5824 n, array_length(means, 1), array_length(stddevs, 1);
5825 END IF;
5826 FOR i IN 1..n LOOP
5827 IF weights[i] IS NULL OR weights[i] = 'NaN'::float8
5828 OR weights[i] < 0 OR weights[i] > 1 THEN
5829 RAISE EXCEPTION 'provsql.gmm: weights[%] must be in [0,1] (got %)',
5830 i, weights[i];
5831 END IF;
5832 w_sum := w_sum + weights[i];
5833 END LOOP;
5834 IF abs(w_sum - 1.0) > 1e-9 THEN
5835 RAISE EXCEPTION 'provsql.gmm: weights must sum to 1 within 1e-9 (got %)', w_sum;
5836 END IF;
5837
5838 -- Stick-breaking, built back to front: acc holds the mixture of
5839 -- components i+1..n, and prepending component i selects it with
5840 -- conditional probability w_i / (w_i + ... + w_n).
5841 FOR i IN REVERSE n..1 LOOP
5842 IF weights[i] <= 0.0 THEN
5843 CONTINUE;
5844 END IF;
5845 IF acc IS NULL THEN
5846 acc := provsql.normal(means[i], stddevs[i]);
5847 remaining := weights[i];
5848 ELSE
5849 remaining := remaining + weights[i];
5850 acc := provsql.mixture(least(1.0, weights[i] / remaining),
5851 provsql.normal(means[i], stddevs[i]), acc);
5852 END IF;
5853 END LOOP;
5854 RETURN acc;
5855END
5856$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5857
5858/**
5859 * @brief Empirical-samples constructor: the ecdf of a sample bundle as
5860 * a @c random_variable.
5861 *
5862 * Loads a Monte Carlo / MCMC / bootstrap sample array as the discrete
5863 * distribution putting mass @c 1/n on each draw (duplicates merge, so a
5864 * value drawn @c k times carries @c k/n) -- the standard empirical
5865 * distribution. Reduces entirely to @ref categorical, so the whole
5866 * exact discrete surface applies: moments are the sample moments,
5867 * comparisons against constants are decided analytically ("fraction of
5868 * samples below c"), and quantiles are the exact empirical quantiles.
5869 *
5870 * @code
5871 * -- Bulk load via array_agg over a sample table
5872 * INSERT INTO model_posteriors
5873 * SELECT param, provsql.empirical_samples(array_agg(value))
5874 * FROM mcmc_chain GROUP BY param;
5875 * @endcode
5876 *
5877 * At most 10000 distinct values (the categorical block cap): thin the
5878 * chain or bin the samples (e.g. with @c width_bucket) beyond that.
5880 * @sa @ref categorical, @ref empirical_cdf
5881 * @sa <a href="https://en.wikipedia.org/wiki/Empirical_distribution_function">Wikipedia: Empirical distribution function</a>
5882 */
5883CREATE OR REPLACE FUNCTION empirical_samples(samples double precision[])
5884 RETURNS random_variable AS
5885$$
5886DECLARE
5887 n INTEGER;
5888 sorted double precision[];
5889 outcomes double precision[] := '{}';
5890 probs double precision[] := '{}';
5891 v double precision;
5892 prev double precision;
5893 run INTEGER := 0;
5894 started BOOLEAN := false;
5895BEGIN
5896 n := array_length(samples, 1);
5897 IF n IS NULL OR n < 1 THEN
5898 RAISE EXCEPTION 'provsql.empirical_samples: samples must be non-empty';
5899 END IF;
5900 sorted := ARRAY(SELECT s FROM unnest(samples) AS s ORDER BY 1);
5901 FOREACH v IN ARRAY sorted LOOP
5902 IF v IS NULL OR v = 'NaN'::float8
5903 OR v = 'Infinity'::float8 OR v = '-Infinity'::float8 THEN
5904 RAISE EXCEPTION
5905 'provsql.empirical_samples: samples must be finite (got %)', v;
5906 END IF;
5907 IF started AND v = prev THEN
5908 run := run + 1;
5909 ELSE
5910 IF started THEN
5911 outcomes := outcomes || prev;
5912 probs := probs || (run::double precision / n);
5913 END IF;
5914 prev := v;
5915 run := 1;
5916 started := true;
5917 END IF;
5918 END LOOP;
5919 outcomes := outcomes || prev;
5920 probs := probs || (run::double precision / n);
5921 IF array_length(outcomes, 1) > 10000 THEN
5922 RAISE EXCEPTION
5923 'provsql.empirical_samples: at most 10000 distinct values are '
5924 'supported (got %); thin the chain or bin the samples (e.g. with '
5925 'width_bucket)', array_length(outcomes, 1);
5926 END IF;
5927 RETURN provsql.categorical(probs, outcomes);
5928END
5929$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
5930
5931/**
5932 * @brief Empirical-CDF constructor: a piecewise-linear CDF table as a
5933 * @c random_variable.
5934 *
5935 * Loads a tabulated CDF -- simulation output percentile tables, risk
5936 * models, expert-elicited forecasts -- as the distribution whose CDF is
5937 * @c cdf[i] at @c grid[i], linear in between: mass
5938 * @c cdf[i+1] @c - @c cdf[i] spread uniformly over
5939 * <tt>(grid[i], grid[i+1])</tt>, plus (when @c cdf[1] @c > @c 0) an
5940 * atom of mass @c cdf[1] at @c grid[1] for the probability at or below
5941 * the grid start. Packaged, like @ref gmm, as a stick-breaking cascade
5942 * of Bernoulli @ref mixture nodes over @ref uniform components (and the
5943 * optional @ref as_random atom), so moments and sampling are exact
5944 * through the existing mixture machinery; comparisons ride Monte Carlo.
5945 *
5946 * @code
5947 * provsql.empirical_cdf(
5948 * grid => ARRAY[0.0, 0.5, 1.0, 2.0, 5.0, 10.0, 20.0],
5949 * cdf => ARRAY[0.32, 0.51, 0.67, 0.82, 0.94, 0.99, 1.0])
5950 * @endcode
5951 *
5952 * Validation: same-length arrays of at least two entries, @p grid
5953 * strictly increasing and finite, @p cdf non-decreasing within
5954 * <tt>[0, 1]</tt> and ending at @c 1 within @c 1e-9.
5955 *
5956 * @sa @ref gmm, @ref empirical_samples
5957 * @sa <a href="https://en.wikipedia.org/wiki/Cumulative_distribution_function">Wikipedia: Cumulative distribution function</a>
5958 */
5959CREATE OR REPLACE FUNCTION empirical_cdf(grid double precision[],
5960 cdf double precision[])
5961 RETURNS random_variable AS
5962$$
5963DECLARE
5964 n INTEGER;
5965 i INTEGER;
5966 acc random_variable := NULL;
5967 remaining double precision := 0.0;
5968 w double precision;
5969 comp random_variable;
5970BEGIN
5971 n := array_length(grid, 1);
5972 IF n IS NULL OR n < 2 THEN
5973 RAISE EXCEPTION 'provsql.empirical_cdf: grid must have at least two entries';
5974 END IF;
5975 IF array_length(cdf, 1) <> n THEN
5976 RAISE EXCEPTION 'provsql.empirical_cdf: grid and cdf must have the same length (got % and %)',
5977 n, array_length(cdf, 1);
5978 END IF;
5979 IF n > 10000 THEN
5980 RAISE EXCEPTION 'provsql.empirical_cdf: at most 10000 grid points are supported (got %)', n;
5981 END IF;
5982 FOR i IN 1..n LOOP
5983 IF grid[i] IS NULL OR grid[i] = 'NaN'::float8
5984 OR grid[i] = 'Infinity'::float8 OR grid[i] = '-Infinity'::float8 THEN
5985 RAISE EXCEPTION 'provsql.empirical_cdf: grid[%] must be finite (got %)', i, grid[i];
5986 END IF;
5987 IF i > 1 AND NOT grid[i] > grid[i-1] THEN
5988 RAISE EXCEPTION 'provsql.empirical_cdf: grid must be strictly increasing (grid[%] = %, grid[%] = %)',
5989 i-1, grid[i-1], i, grid[i];
5990 END IF;
5991 IF cdf[i] IS NULL OR cdf[i] = 'NaN'::float8 OR cdf[i] < 0 OR cdf[i] > 1 THEN
5992 RAISE EXCEPTION 'provsql.empirical_cdf: cdf[%] must be in [0,1] (got %)', i, cdf[i];
5993 END IF;
5994 IF i > 1 AND cdf[i] < cdf[i-1] THEN
5995 RAISE EXCEPTION 'provsql.empirical_cdf: cdf must be non-decreasing (cdf[%] = %, cdf[%] = %)',
5996 i-1, cdf[i-1], i, cdf[i];
5997 END IF;
5998 END LOOP;
5999 IF abs(cdf[n] - 1.0) > 1e-9 THEN
6000 RAISE EXCEPTION 'provsql.empirical_cdf: cdf must end at 1 within 1e-9 (got %)', cdf[n];
6001 END IF;
6002
6003 -- Stick-breaking cascade, back to front: component i = 1 is the atom
6004 -- at the grid start (mass cdf[1]); component i >= 2 is
6005 -- uniform(grid[i-1], grid[i]) with mass cdf[i] - cdf[i-1].
6006 FOR i IN REVERSE n..1 LOOP
6007 w := CASE WHEN i = 1 THEN cdf[1] ELSE cdf[i] - cdf[i-1] END;
6008 IF w <= 0.0 THEN
6009 CONTINUE;
6010 END IF;
6011 comp := CASE WHEN i = 1 THEN provsql.as_random(grid[1])
6012 ELSE provsql.uniform(grid[i-1], grid[i]) END;
6013 IF acc IS NULL THEN
6014 acc := comp;
6015 remaining := w;
6016 ELSE
6017 remaining := remaining + w;
6018 acc := provsql.mixture(least(1.0, w / remaining), comp, acc);
6019 END IF;
6020 END LOOP;
6021 RETURN acc;
6022END
6023$$ LANGUAGE plpgsql STRICT VOLATILE PARALLEL UNSAFE;
6025/**
6026 * @brief Lift a deterministic constant into a random_variable
6027 *
6028 * Creates a <tt>gate_value</tt> carrying the constant's TEXT form so
6029 * that comparisons against a <tt>random_variable</tt> column produce
6030 * the same circuit shape regardless of whether the operand is an
6031 * actual RV or a literal constant.
6032 *
6033 * Marked <tt>IMMUTABLE</tt>: the gate UUID is derived deterministically
6034 * from the constant via the same v5 convention as <tt>provenance_semimod</tt>'s
6035 * inline value gate (<tt>concat('value', CAST(c AS VARCHAR))</tt>), so
6036 * <tt>as_random(2)</tt> always resolves to the same gate, and any other
6037 * code path that already creates a value gate for the same constant
6038 * (e.g. <tt>provenance_semimod</tt>) shares the UUID.
6039 * <tt>create_gate</tt> is idempotent on already-mapped tokens, so
6040 * repeat invocations are harmless.
6041 *
6042 * @sa <a href="https://en.wikipedia.org/wiki/Degenerate_distribution">Wikipedia: Degenerate distribution (Dirac point mass)</a>
6043 */
6044CREATE OR REPLACE FUNCTION as_random(c double precision)
6045 RETURNS random_variable AS
6047DECLARE
6048 -- Canonicalise -0.0 to +0.0: IEEE 754 defines x + 0.0 = +0.0 for
6049 -- both signed zeros, and is identity for finite, NaN, and ±Infinity.
6050 -- Without this, as_random(-0.0) and as_random(+0.0) would produce
6051 -- different gate UUIDs (their CAST AS VARCHAR TEXT representations
6052 -- differ: '-0' vs '0') even though they denote the same constant.
6053 c_canon double precision := c + 0.0;
6054 c_text varchar := CAST(c_canon AS VARCHAR);
6055 token UUID := public.uuid_generate_v5(
6056 provsql.uuid_ns_provsql(), concat('value', c_text));
6057BEGIN
6058 PERFORM provsql.create_gate(token, 'value', NULL, NULL, NULL, c_text);
6059 RETURN provsql.random_variable_make(token);
6060END
6061$$ LANGUAGE plpgsql STRICT IMMUTABLE PARALLEL SAFE;
6063/**
6064 * @brief Implicit cast double precision -> random_variable (lifts a
6065 * scalar literal to a constant RV).
6066 *
6067 * Lets users write <tt>WHERE reading > 2.5::float8</tt> instead of
6068 * <tt>WHERE reading > provsql.as_random(2.5)</tt>; the planner-hook
6069 * rewriter then sees a uniform <tt>random_variable</tt> on both sides.
6070 * Sibling casts below cover @c INTEGER and @c NUMERIC literals so
6071 * plain <tt>WHERE reading > 2</tt> and <tt>WHERE reading > 2.5</tt>
6072 * also work; PostgreSQL's operator resolution does not chain casts
6073 * across more than one step, so each NUMERIC-source type needs its
6074 * own direct cast.
6075 */
6076CREATE CAST (double precision AS random_variable)
6077 WITH FUNCTION as_random(double precision) AS IMPLICIT;
6078
6079/** @brief @c as_random for @c INTEGER (delegates to the @c float8 form). */
6080CREATE OR REPLACE FUNCTION as_random(c INTEGER)
6081 RETURNS random_variable AS
6082$$ SELECT provsql.as_random(c::double precision); $$
6083LANGUAGE sql STRICT IMMUTABLE PARALLEL SAFE;
6084
6085/** @brief @c as_random for @c NUMERIC (delegates to the @c float8 form). */
6086CREATE OR REPLACE FUNCTION as_random(c NUMERIC)
6087 RETURNS random_variable AS
6088$$ SELECT provsql.as_random(c::double precision); $$
6089LANGUAGE sql STRICT IMMUTABLE PARALLEL SAFE;
6090
6091/** @brief Implicit cast INTEGER -> random_variable. */
6092CREATE CAST (INTEGER AS random_variable)
6093 WITH FUNCTION as_random(INTEGER) AS IMPLICIT;
6095/** @brief Implicit cast NUMERIC -> random_variable. */
6096CREATE CAST (NUMERIC AS random_variable)
6097 WITH FUNCTION as_random(NUMERIC) AS IMPLICIT;
6098
6099/**
6100 * @name Arithmetic and comparison on random_variable
6101 *
6102 * Each binary operator below is declared on @c (random_variable,
6103 * random_variable) only; mixed shapes such as <tt>rv + 2</tt> or
6104 * <tt>2.5 > rv</tt> resolve through the implicit casts from
6105 * @c INTEGER / @c NUMERIC / @c double @c precision to
6106 * @c random_variable declared above. This avoids the resolution
6107 * ambiguity that would arise if both <tt>(rv, NUMERIC)</tt> and
6108 * <tt>(rv, rv)</tt> overloads were declared while implicit casts also
6109 * existed.
6110 *
6111 * Arithmetic operators build a @c gate_arith via @c provenance_arith
6112 * and return a new @c random_variable wrapping its UUID.
6113 *
6114 * Comparison operators are placeholders that return @c BOOLEAN and
6115 * raise if executed -- the @c BOOLEAN return type is required so that
6116 * PostgreSQL accepts <tt>WHERE rv > 2</tt> at parse-analyze. The
6117 * planner hook intercepts every such @c OpExpr (matched by
6118 * @c opfuncid against @c constants_t::OID_FUNCTION_RV_CMP) and rewrites
6119 * it into a @c provenance_cmp call whose UUID is conjoined into the
6120 * tuple's @c provsql column via @c provenance_times. Code that needs
6121 * a @c gate_cmp UUID directly (without going through the planner hook)
6122 * uses the @c rv_cmp_* family below, which call @c provenance_cmp
6123 * with the matching float8-comparator OID.
6124 *
6125 * @{
6126 */
6127
6128/** @brief @c random_variable + @c random_variable (gate_arith PLUS). */
6129CREATE OR REPLACE FUNCTION random_variable_plus(
6130 a random_variable, b random_variable)
6131 RETURNS random_variable AS
6132$$
6133 SELECT provsql.random_variable_make(
6134 provsql.provenance_arith(
6135 0, -- PROVSQL_ARITH_PLUS
6136 ARRAY[(a)::UUID,
6137 (b)::UUID]));
6138$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6139
6140/** @brief @c random_variable - @c random_variable (gate_arith MINUS). */
6141CREATE OR REPLACE FUNCTION random_variable_minus(
6142 a random_variable, b random_variable)
6143 RETURNS random_variable AS
6144$$
6145 SELECT provsql.random_variable_make(
6146 provsql.provenance_arith(
6147 2, -- PROVSQL_ARITH_MINUS
6148 ARRAY[(a)::UUID,
6149 (b)::UUID]));
6150$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6151
6152/** @brief @c random_variable * @c random_variable (gate_arith TIMES). */
6153CREATE OR REPLACE FUNCTION random_variable_times(
6154 a random_variable, b random_variable)
6155 RETURNS random_variable AS
6156$$
6157 SELECT provsql.random_variable_make(
6158 provsql.provenance_arith(
6159 1, -- PROVSQL_ARITH_TIMES
6160 ARRAY[(a)::UUID,
6161 (b)::UUID]));
6162$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6163
6164/** @brief @c random_variable / @c random_variable (gate_arith DIV). */
6165CREATE OR REPLACE FUNCTION random_variable_div(
6166 a random_variable, b random_variable)
6167 RETURNS random_variable AS
6168$$
6169 SELECT provsql.random_variable_make(
6170 provsql.provenance_arith(
6171 3, -- PROVSQL_ARITH_DIV
6172 ARRAY[(a)::UUID,
6173 (b)::UUID]));
6174$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6175
6176/** @brief Unary @c -random_variable (gate_arith NEG). */
6177CREATE OR REPLACE FUNCTION random_variable_neg(a random_variable)
6178 RETURNS random_variable AS
6179$$
6180 SELECT provsql.random_variable_make(
6181 provsql.provenance_arith(
6182 4, -- PROVSQL_ARITH_NEG
6183 ARRAY[(a)::UUID]));
6184$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6185
6186/**
6187 * @brief @c random_variable ^ @c random_variable (gate_arith POW).
6188 *
6189 * Real-valued branch only: evaluation raises if a negative base is
6190 * drawn together with a non-INTEGER exponent (write
6191 * <tt>pow(greatest(x, 0), p)</tt> for the non-negative branch).
6192 */
6193CREATE OR REPLACE FUNCTION random_variable_pow(
6194 a random_variable, b random_variable)
6195 RETURNS random_variable AS
6196$$
6197 SELECT provsql.random_variable_make(
6198 provsql.provenance_arith(
6199 7, -- PROVSQL_ARITH_POW
6200 ARRAY[(a)::UUID,
6201 (b)::UUID]));
6202$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6203
6204/**
6205 * @brief Natural logarithm of a @c random_variable (gate_arith LN).
6206 *
6207 * Defined on @c [0, +Infinity): evaluation raises if a negative value
6208 * is drawn (restrict the argument's support); a draw of exactly @c 0
6209 * yields @c -Infinity.
6210 */
6211CREATE OR REPLACE FUNCTION ln(a random_variable)
6212 RETURNS random_variable AS
6213$$
6214 SELECT provsql.random_variable_make(
6215 provsql.provenance_arith(
6216 8, -- PROVSQL_ARITH_LN
6217 ARRAY[(a)::UUID]));
6218$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6219
6220/** @brief @c e^x for a @c random_variable (gate_arith EXP). Total. */
6221CREATE OR REPLACE FUNCTION exp(a random_variable)
6222 RETURNS random_variable AS
6223$$
6224 SELECT provsql.random_variable_make(
6225 provsql.provenance_arith(
6226 9, -- PROVSQL_ARITH_EXP
6227 ARRAY[(a)::UUID]));
6228$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6229
6230/**
6231 * @brief @c pow / @c power spellings of the @c ^ operator, mirroring
6232 * PostgreSQL's NUMERIC surface. Scalar exponents resolve
6233 * through the implicit NUMERIC-to-rv casts:
6234 * <tt>pow(x, 0.5)</tt> is <tt>x ^ 0.5</tt>.
6235 */
6236CREATE OR REPLACE FUNCTION pow(a random_variable, b random_variable)
6237 RETURNS random_variable AS
6238$$
6239 SELECT provsql.random_variable_pow(a, b);
6240$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6241
6242CREATE OR REPLACE FUNCTION power(a random_variable, b random_variable)
6243 RETURNS random_variable AS
6244$$
6245 SELECT provsql.random_variable_pow(a, b);
6246$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6247
6248/**
6249 * @brief Square root of a @c random_variable: sugar for
6250 * <tt>x ^ 0.5</tt> (no gate or opcode of its own). Evaluation
6251 * raises on a negative draw, like any non-INTEGER exponent.
6252 */
6253CREATE OR REPLACE FUNCTION sqrt(a random_variable)
6254 RETURNS random_variable AS
6255$$
6256 SELECT provsql.random_variable_pow(a, provsql.as_random(0.5));
6257$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6258
6259/**
6260 * @brief Internal helper: float8-comparator OID for a given symbol.
6261 *
6262 * Wraps the @c '&lt;sym&gt;(double precision,double precision)'::regoperator
6263 * lookup so the per-comparator functions read uniformly. Marked
6264 * @c IMMUTABLE because the resolved OID is fixed at catalog level
6265 * (the float8 comparators are core PG and never re-installed).
6266 */
6267CREATE OR REPLACE FUNCTION random_variable_cmp_oid(sym TEXT)
6268 RETURNS oid AS
6269$$
6270 SELECT (sym || '(double precision,double precision)')::regoperator::oid;
6271$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6272
6273/* The six @c random_variable_{lt,le,eq,ne,ge,gt} functions below are
6274 * BOOLEAN placeholders -- they exist only so the @c (rv, rv) operators
6275 * can be declared at all (PostgreSQL needs a procedure to bind to the
6276 * operator definition, and a procedure returning anything but @c BOOLEAN
6277 * would be rejected by parse-analyze in a WHERE position). They MUST
6278 * NOT be invoked directly: the planner hook in @c src/provsql.c
6279 * intercepts every @c OpExpr whose @c opfuncid matches one of these and
6280 * rewrites it into a @c provenance_cmp() call against the row's
6281 * provenance. If the executor ever reaches one of these, it means the
6282 * planner hook was bypassed (e.g. @c provsql.active was off), in which
6283 * case raising is the right behaviour. */
6284
6285/** @brief Placeholder body shared by every <tt>random_variable_*</tt>
6286 * comparison procedure. Raises with a uniform message. */
6287CREATE OR REPLACE FUNCTION random_variable_cmp_placeholder(
6288 a random_variable, b random_variable)
6289 RETURNS BOOLEAN AS
6290$$
6291BEGIN
6292 RAISE EXCEPTION 'random_variable comparison must be rewritten by the '
6293 'ProvSQL planner hook (is provsql.active off?)'
6294 USING ERRCODE = 'feature_not_supported',
6295 DETAIL = 'provsql-reason: rv-operator-not-rewritten; scope: out-of-scope';
6296END
6297$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
6298
6299CREATE OR REPLACE FUNCTION random_variable_lt(
6300 a random_variable, b random_variable) RETURNS BOOLEAN AS
6301$$ SELECT provsql.random_variable_cmp_placeholder(a, b); $$
6302LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6303
6304CREATE OR REPLACE FUNCTION random_variable_le(
6305 a random_variable, b random_variable) RETURNS BOOLEAN AS
6306$$ SELECT provsql.random_variable_cmp_placeholder(a, b); $$
6307LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6308
6309CREATE OR REPLACE FUNCTION random_variable_eq(
6310 a random_variable, b random_variable) RETURNS BOOLEAN AS
6311$$ SELECT provsql.random_variable_cmp_placeholder(a, b); $$
6312LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6313
6314CREATE OR REPLACE FUNCTION random_variable_ne(
6315 a random_variable, b random_variable) RETURNS BOOLEAN AS
6316$$ SELECT provsql.random_variable_cmp_placeholder(a, b); $$
6317LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6318
6319CREATE OR REPLACE FUNCTION random_variable_ge(
6320 a random_variable, b random_variable) RETURNS BOOLEAN AS
6321$$ SELECT provsql.random_variable_cmp_placeholder(a, b); $$
6322LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6323
6324CREATE OR REPLACE FUNCTION random_variable_gt(
6325 a random_variable, b random_variable) RETURNS BOOLEAN AS
6326$$ SELECT provsql.random_variable_cmp_placeholder(a, b); $$
6327LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6328
6329/* Direct UUID constructors -- used by tests and any caller that wants
6330 * a @c gate_cmp without going through the planner hook (e.g. building
6331 * a circuit fragment in a SELECT list). Each delegates to
6332 * @c provenance_cmp with the matching float8-comparator OID. */
6333
6334/** @brief Build a @c gate_cmp for <tt>a &lt; b</tt> and return its UUID. */
6335CREATE OR REPLACE FUNCTION rv_cmp_lt(
6336 a random_variable, b random_variable) RETURNS UUID AS
6337$$
6338 SELECT provsql.provenance_cmp(
6339 (a)::UUID,
6340 provsql.random_variable_cmp_oid('<'),
6341 (b)::UUID);
6342$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6343
6344/** @brief Build a @c gate_cmp for <tt>a &le; b</tt> and return its UUID. */
6345CREATE OR REPLACE FUNCTION rv_cmp_le(
6346 a random_variable, b random_variable) RETURNS UUID AS
6347$$
6348 SELECT provsql.provenance_cmp(
6349 (a)::UUID,
6350 provsql.random_variable_cmp_oid('<='),
6351 (b)::UUID);
6352$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6353
6354/** @brief Build a @c gate_cmp for <tt>a = b</tt> and return its UUID. */
6355CREATE OR REPLACE FUNCTION rv_cmp_eq(
6356 a random_variable, b random_variable) RETURNS UUID AS
6357$$
6358 SELECT provsql.provenance_cmp(
6359 (a)::UUID,
6360 provsql.random_variable_cmp_oid('='),
6361 (b)::UUID);
6362$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6363
6364/** @brief Build a @c gate_cmp for <tt>a &lt;&gt; b</tt> and return its UUID. */
6365CREATE OR REPLACE FUNCTION rv_cmp_ne(
6366 a random_variable, b random_variable) RETURNS UUID AS
6367$$
6368 SELECT provsql.provenance_cmp(
6369 (a)::UUID,
6370 provsql.random_variable_cmp_oid('<>'),
6371 (b)::UUID);
6372$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6373
6374/** @brief Build a @c gate_cmp for <tt>a &ge; b</tt> and return its UUID. */
6375CREATE OR REPLACE FUNCTION rv_cmp_ge(
6376 a random_variable, b random_variable) RETURNS UUID AS
6377$$
6378 SELECT provsql.provenance_cmp(
6379 (a)::UUID,
6380 provsql.random_variable_cmp_oid('>='),
6381 (b)::UUID);
6382$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6383
6384/** @brief Build a @c gate_cmp for <tt>a &gt; b</tt> and return its UUID. */
6385CREATE OR REPLACE FUNCTION rv_cmp_gt(
6386 a random_variable, b random_variable) RETURNS UUID AS
6387$$
6388 SELECT provsql.provenance_cmp(
6389 (a)::UUID,
6390 provsql.random_variable_cmp_oid('>'),
6391 (b)::UUID);
6392$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
6393
6394CREATE OPERATOR + (
6395 LEFTARG = random_variable,
6396 RIGHTARG = random_variable,
6397 PROCEDURE = random_variable_plus,
6398 COMMUTATOR = +
6399);
6400
6401CREATE OPERATOR - (
6402 LEFTARG = random_variable,
6403 RIGHTARG = random_variable,
6404 PROCEDURE = random_variable_minus
6405);
6406
6407CREATE OPERATOR * (
6408 LEFTARG = random_variable,
6409 RIGHTARG = random_variable,
6410 PROCEDURE = random_variable_times,
6411 COMMUTATOR = *
6412);
6413
6414CREATE OPERATOR / (
6415 LEFTARG = random_variable,
6416 RIGHTARG = random_variable,
6417 PROCEDURE = random_variable_div
6418);
6419
6420/** @brief Prefix unary minus on @c random_variable. */
6421CREATE OPERATOR - (
6422 RIGHTARG = random_variable,
6423 PROCEDURE = random_variable_neg
6424);
6425
6426CREATE OPERATOR ^ (
6427 LEFTARG = random_variable,
6428 RIGHTARG = random_variable,
6429 PROCEDURE = random_variable_pow
6430);
6431
6432CREATE OPERATOR < (
6433 LEFTARG = random_variable,
6434 RIGHTARG = random_variable,
6435 PROCEDURE = random_variable_lt,
6436 COMMUTATOR = >,
6437 NEGATOR = >=
6438);
6439
6440CREATE OPERATOR <= (
6441 LEFTARG = random_variable,
6442 RIGHTARG = random_variable,
6443 PROCEDURE = random_variable_le,
6444 COMMUTATOR = >=,
6445 NEGATOR = >
6446);
6447
6448CREATE OPERATOR = (
6449 LEFTARG = random_variable,
6450 RIGHTARG = random_variable,
6451 PROCEDURE = random_variable_eq,
6452 COMMUTATOR = =,
6453 NEGATOR = <>
6454);
6455
6456CREATE OPERATOR <> (
6457 LEFTARG = random_variable,
6458 RIGHTARG = random_variable,
6459 PROCEDURE = random_variable_ne,
6460 COMMUTATOR = <>,
6461 NEGATOR = =
6462);
6463
6464CREATE OPERATOR >= (
6465 LEFTARG = random_variable,
6466 RIGHTARG = random_variable,
6467 PROCEDURE = random_variable_ge,
6468 COMMUTATOR = <=,
6469 NEGATOR = <
6470);
6471
6472/**
6473 * @brief Order @c AGG_TOKEN values by the value each carries.
6475 * With a cast of an aggregate carried rather than frozen, a column of
6476 * @c AGG_TOKEN is what a query sorts, groups or takes the DISTINCT of, and
6477 * those need an ordering. It is the ordering of the values on the data as it
6478 * is -- the one ProvSQL already documents for @c ORDER @c BY on an aggregate
6479 * -- and the comparison says so, once for the statement.
6480 */
6481CREATE OR REPLACE FUNCTION agg_token_btree_cmp(a AGG_TOKEN, b AGG_TOKEN)
6482 RETURNS INTEGER AS 'MODULE_PATHNAME', 'agg_token_btree_cmp'
6483 LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
6484
6485CREATE OPERATOR CLASS agg_token_ops
6486 DEFAULT FOR TYPE AGG_TOKEN USING btree AS
6487 OPERATOR 1 <,
6488 OPERATOR 2 <=,
6489 OPERATOR 3 =,
6490 OPERATOR 4 >=,
6491 OPERATOR 5 >,
6492 FUNCTION 1 agg_token_btree_cmp(AGG_TOKEN, AGG_TOKEN);
6493
6494
6495CREATE OPERATOR > (
6496 LEFTARG = random_variable,
6497 RIGHTARG = random_variable,
6498 PROCEDURE = random_variable_gt,
6499 COMMUTATOR = <,
6500 NEGATOR = <=
6501);
6502
6503/**
6504 * @brief btree comparison support for @c random_variable -- always an error.
6505 *
6506 * A @c random_variable is a distribution, not a scalar, so it has no total
6507 * order: sorting (@c ORDER @c BY), de-duplicating (@c DISTINCT), grouping, and
6508 * the built-in @c GREATEST / @c LEAST all reduce to this btree comparison
6509 * proc, which raises a clear diagnostic rather than a placeholder message.
6510 *
6511 * The proc exists only so a DEFAULT btree operator class can be declared for
6512 * @c random_variable -- which is what lets PostgreSQL's @c GREATEST / @c LEAST
6513 * grammar parse over random variables so the planner hook can lift it into a
6514 * @c gate_arith @c MAX / @c MIN order statistic. When the hook is active the
6515 * @c GREATEST / @c LEAST node is rewritten before it ever calls this proc.
6516 */
6517CREATE OR REPLACE FUNCTION random_variable_btree_cmp(
6518 a random_variable, b random_variable) RETURNS INTEGER AS
6519$$
6520BEGIN
6521 RAISE EXCEPTION 'comparison or ordering of random_variable values is '
6522 'meaningless: a random_variable is a distribution, not a scalar'
6523 USING HINT =
6524 'Compare them as a probabilistic event -- in a WHERE / JOIN clause or '
6525 'with probability(x > y); take order statistics with provsql.greatest / '
6526 'provsql.least (or the min / max aggregates); summarise numerically with '
6527 'expected / variance / support.',
6528 DETAIL = 'provsql-reason: rv-comparison; scope: out-of-scope';
6529END
6530$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
6531
6532-- DEFAULT btree operator class over the (planner-hook-lifted) comparison
6533-- operators. Its only purpose is to make GREATEST / LEAST over random_variable
6534-- parse; every actual comparison it would drive (ORDER BY, DISTINCT, an
6535-- un-rewritten GREATEST) funnels through random_variable_btree_cmp above and
6536-- raises the "meaningless" diagnostic.
6537CREATE OPERATOR CLASS random_variable_ops
6538 DEFAULT FOR TYPE random_variable USING btree AS
6539 OPERATOR 1 <,
6540 OPERATOR 2 <=,
6541 OPERATOR 3 =,
6542 OPERATOR 4 >=,
6543 OPERATOR 5 >,
6544 FUNCTION 1 random_variable_btree_cmp(random_variable, random_variable);
6545
6546/**
6547 * @brief Condition a random variable on an event: @c "X | C".
6548 *
6549 * Returns a conditioned distribution that flows onward like any other
6550 * @c random_variable: it can be stored, re-conditioned, and queried with
6551 * @c expected / @c variance / @c moment / @c support, which then report the
6552 * conditional distribution. @p cond is a Boolean-event provenance token,
6553 * typically a comparison over the variable itself (@c "X | rv_cmp_gt(X,
6554 * as_random(3))" -- a truncation) or any external event.
6555 *
6556 * Unlike the UUID carrier's terminal @c cond, the random-variable form is a
6557 * composable two-child @c gate_conditioned @c [target, condition]: the moment
6558 * / support dispatchers unpack it and route through the existing conditional
6559 * evaluator (@c rv_moment over the joint of the target and the condition).
6560 * Nested conditioning folds: @c "(X|A)|B = X|(A∧B)".
6561 */
6562CREATE OR REPLACE FUNCTION random_variable_cond(rv random_variable, cond UUID)
6563 RETURNS random_variable AS
6564$$
6565DECLARE
6566 tgt UUID;
6567 ev UUID;
6568 result UUID;
6569 ch UUID[];
6570BEGIN
6571 IF cond IS NULL OR cond = gate_one() THEN
6572 RETURN rv;
6573 END IF;
6574
6575 -- A point-equality "Y = c" on a bare random-variable leaf is an
6576 -- OBSERVATION, not a truncation: rewrite it to the internal likelihood-
6577 -- weighting evidence (its density / mass at c). This is what lets
6578 -- "X | (normal(mu,1) = 8)" (a continuous point event, measure-zero as a
6579 -- Boolean selection) condition as the disintegration rather than fold to
6580 -- an infeasible event.
6581 cond := provsql.evidence_as_observation(cond);
6582
6583 tgt := (rv)::UUID;
6584 IF get_gate_type(tgt) = 'conditioned'
6585 AND array_length(get_children(tgt), 1) = 2 THEN
6586 -- Fold (X|A)|B = X|(A∧B): the rv-carrier conditioned gate is the
6587 -- two-child [target, condition] shape; accumulate the new event.
6588 ch := get_children(tgt);
6589 tgt := ch[1];
6590 ev := provenance_times(ch[2], cond);
6591 ELSE
6592 ev := cond;
6593 END IF;
6594
6595 result := public.uuid_generate_v5(uuid_ns_provsql(),
6596 concat('conditioned', tgt, ev));
6597 PERFORM create_gate(result, 'conditioned', ARRAY[tgt, ev]);
6598 RETURN (result)::random_variable;
6599END
6600$$ LANGUAGE plpgsql VOLATILE SET search_path=provsql,pg_temp,public
6601 SECURITY DEFINER PARALLEL UNSAFE;
6602
6603CREATE OPERATOR | (
6604 LEFTARG = random_variable,
6605 RIGHTARG = UUID,
6606 PROCEDURE = random_variable_cond
6607);
6608
6609/**
6610 * @brief Placeholder for @c "X | (predicate)" -- conditioning a random
6611 * variable on a Boolean comparison written naturally.
6613 * Lets one write @c "X | (X > 3)" instead of
6614 * @c "X | rv_cmp_gt(X, as_random(3))". Never executes: the ProvSQL planner
6615 * hook rewrites the Boolean operand (a combination of random_variable
6616 * comparisons) into the corresponding condition gate and emits
6617 * @c random_variable_cond. Reaching it at runtime means the rewriter was
6618 * inactive or the predicate was not a random_variable comparison.
6619 */
6620CREATE OR REPLACE FUNCTION random_variable_cond_predicate(
6621 rv random_variable, predicate BOOLEAN) RETURNS random_variable AS
6622$$
6623BEGIN
6624 RAISE EXCEPTION 'random_variable | (predicate) must be rewritten by the '
6625 'ProvSQL planner hook: the right operand must be a Boolean combination '
6626 'of random_variable comparisons (is provsql.active off?)'
6627 USING ERRCODE = 'feature_not_supported',
6628 DETAIL = 'provsql-reason: rv-operator-not-rewritten; scope: out-of-scope';
6630$$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
6631
6632CREATE OPERATOR | (
6633 LEFTARG = random_variable,
6634 RIGHTARG = BOOLEAN,
6635 PROCEDURE = random_variable_cond_predicate
6636);
6637
6638/**
6639 * @brief Unpack the target of a random-variable conditioning gate.
6640 *
6641 * For a two-child @c gate_conditioned @c [target, condition] (the @c "X | C"
6642 * shape) returns @p target; for any other token returns it unchanged. Used
6643 * by the moment / support dispatchers to route a conditioned distribution
6644 * through the existing conditional evaluator.
6645 */
6646CREATE OR REPLACE FUNCTION rv_conditioned_target(token UUID) RETURNS UUID AS
6647$$
6648 SELECT CASE
6649 WHEN provsql.get_gate_type(token) = 'conditioned'
6650 AND array_length(provsql.get_children(token), 1) = 2
6651 THEN (provsql.get_children(token))[1]
6652 ELSE token
6653 END;
6654$$ LANGUAGE sql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
6655
6656/**
6657 * @brief Combine a conditioning gate's event with an explicit @p prov.
6658 *
6659 * For a two-child @c gate_conditioned @c [target, condition] returns
6660 * @c "condition ∧ prov"; otherwise returns @p prov unchanged. Lets a stored
6661 * @c "X | C" be queried as @c expected(X|C) (prov defaulting to one) or have
6662 * an extra condition conjoined as @c expected(X|C, extra_prov).
6663 */
6664CREATE OR REPLACE FUNCTION rv_conditioned_prov(token UUID, prov UUID)
6665 RETURNS UUID AS
6666$$
6667 SELECT CASE
6668 WHEN provsql.get_gate_type(token) = 'conditioned'
6669 AND array_length(provsql.get_children(token), 1) = 2
6670 THEN provsql.provenance_times((provsql.get_children(token))[2], prov)
6671 ELSE prov
6672 END;
6673$$ LANGUAGE sql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
6674
6675/*
6676 * Latent-variable posterior inference.
6677 *
6678 * Likelihood weighting (self-normalised importance sampling): bind an
6679 * observed datum to a latent-dependent random-variable leaf with observe,
6680 * conjoin the per-observation evidence with and_agg into a single evidence
6681 * token, and pass it as the prov conditioning argument of any moment /
6682 * quantile / sample readout. Latents are drawn from the prior (the
6683 * existing forward recursion) and each draw is weighted by the observed
6684 * leaves' densities at the data; the readouts then report the posterior.
6685 * It is the continuous generalisation of the rejection-based conditioning:
6686 * a Boolean event in the evidence contributes a 0/1 weight, an observe
6687 * contributes a pdf weight -- same evidence conjunction, same
6688 * "P(query AND evidence)/P(evidence)" normaliser, now weighted.
6689 */
6690
6691/**
6692 * @brief Internal: rewrite a point-equality conditioning event into an
6693 * observation. If @p ev is a @c gate_cmp with the @c "=" operator,
6694 * one side a bare @c gate_rv leaf and the other a constant, return
6695 * @c observe(leaf, const); otherwise return @p ev unchanged.
6696 *
6697 * This is the bridge that makes the natural equality form the surface for
6698 * likelihood-weighting conditioning: @c "X | (Y = c)" and @c "given(Y = c)"
6699 * both produce a @c gate_cmp, which this turns into density evidence. A
6700 * point event on a bare leaf is only meaningful as an observation (a
6701 * continuous @c "Y = c" is measure-zero as a Boolean selection), so the
6702 * rewrite is unambiguous. Non-equality / non-leaf events pass through as
6703 * ordinary Boolean conditioning.
6704 */
6705CREATE OR REPLACE FUNCTION evidence_as_observation(ev UUID) RETURNS UUID AS
6706$$
6707DECLARE
6708 ch UUID[];
6709 i1 INTEGER;
6710 leaf UUID;
6711 datum_gate UUID;
6712BEGIN
6713 IF ev IS NULL OR provsql.get_gate_type(ev) <> 'cmp' THEN
6714 RETURN ev;
6715 END IF;
6716 ch := provsql.get_children(ev);
6717 IF array_length(ch, 1) <> 2 THEN
6718 RETURN ev;
6719 END IF;
6720 -- The cmp stores the comparison OPERATOR's OID in info1; match on its name
6721 -- '=' the same way the C-side cmpOpFromOid does (get_opname), rather than a
6722 -- fixed operator OID (which varies per install / carrier type).
6723 SELECT info1 INTO i1 FROM provsql.get_infos(ev);
6724 IF (SELECT oprname FROM pg_catalog.pg_operator WHERE oid = i1) IS DISTINCT FROM '=' THEN
6725 RETURN ev; -- not an equality
6726 END IF;
6727 IF provsql.get_gate_type(ch[1]) = 'rv'
6728 AND provsql.get_gate_type(ch[2]) = 'value' THEN
6729 leaf := ch[1]; datum_gate := ch[2];
6730 ELSIF provsql.get_gate_type(ch[2]) = 'rv'
6731 AND provsql.get_gate_type(ch[1]) = 'value' THEN
6732 leaf := ch[2]; datum_gate := ch[1];
6733 ELSE
6734 RETURN ev; -- not a bare-leaf-vs-constant point event
6735 END IF;
6736 RETURN provsql.observe((leaf)::random_variable,
6737 provsql.get_extra(datum_gate)::double precision);
6738END
6739$$ LANGUAGE plpgsql VOLATILE
6740 SET search_path=provsql,pg_temp,public SECURITY DEFINER PARALLEL UNSAFE;
6741
6742/**
6743 * @brief Internal: bind an observed datum to a random-variable leaf --
6744 * the likelihood-weighting evidence behind @c "X | (Y = d)".
6745 *
6746 * @p x MUST be a bare @c gate_rv leaf (typically a latent-parameterised
6747 * one, e.g. @c normal(mu, 1) sharing a latent @c mu across rows).
6748 * Returns an @b evidence UUID -- a @c gate_observe wrapping the leaf with
6749 * the datum in @c extra -- that composes with other evidence through
6750 * @c and_agg (a @c gate_times conjunction) and is consumed by the
6751 * importance-sampling weight walk, contributing the factor @c f_X(d).
6752 *
6753 * Internal: the user-facing surface is the equality form @c "X | (Y = d)"
6754 * (single conditioning) and @c "given(Y = d)" (per-row evidence for
6755 * @c and_agg), both of which route here through @c evidence_as_observation.
6756 *
6757 * A fresh gate is minted per call (each observation is a distinct
6758 * evidence atom, so a repeated @c (leaf, datum) contributes its density
6759 * factor once per row -- and each is a separate Shapley atom). Observing
6760 * a derived quantity (@c observe(X+Y, d)) is out of scope: it needs a
6761 * change-of-variables density; a non-leaf argument is refused.
6762 */
6763CREATE OR REPLACE FUNCTION observe(x random_variable, datum double precision)
6764 RETURNS UUID AS
6765$$
6766DECLARE
6767 leaf UUID := (x)::UUID;
6768 result UUID;
6769BEGIN
6770 IF provsql.get_gate_type(leaf) <> 'rv' THEN
6771 RAISE EXCEPTION 'provsql.observe: the argument must be a bare '
6772 'random-variable leaf (a gate_rv), got a % gate', provsql.get_gate_type(leaf)
6773 USING HINT = 'observe binds a datum to a single distribution leaf; '
6774 'observing a derived quantity (a sum, product, or comparison) needs '
6775 'a change-of-variables density and is out of scope.',
6776 DETAIL = 'provsql-reason: observe-argument-kind; scope: out-of-scope';
6777 END IF;
6778 IF NOT provsql.is_finite_float8(datum) THEN
6779 RAISE EXCEPTION 'provsql.observe: datum must be finite (got %)', datum;
6780 END IF;
6781 result := public.uuid_generate_v4();
6782 PERFORM provsql.create_gate(result, 'observe', ARRAY[leaf], NULL, NULL, datum::TEXT);
6783 RETURN result;
6784END
6785$$ LANGUAGE plpgsql VOLATILE
6786 SET search_path=provsql,pg_temp,public SECURITY DEFINER PARALLEL UNSAFE;
6787
6788/**
6789 * @brief Conjunction state function for @c and_agg (evidence @c gate_times).
6790 *
6791 * Not @c STRICT: @c provenance_times maps a @c NULL operand to the times
6792 * neutral, so an empty group leaves the state @c NULL (no evidence) and a
6793 * first row seeds it with that row's evidence.
6794 */
6795CREATE OR REPLACE FUNCTION and_agg_sfunc(state UUID, ev UUID)
6796 RETURNS UUID AS
6797$$
6798 SELECT provsql.provenance_times(state, ev);
6799$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
6800
6801/**
6802 * @brief Conjoin per-row evidence tokens into one evidence circuit.
6803 *
6804 * The evidence-conjunction counterpart used to fold one @c observe (or any
6805 * Boolean conditioning event) per row into a single @c gate_times root, to
6806 * be passed as the @c prov argument of the moment / quantile / sample
6807 * readouts. An empty group yields @c NULL (no evidence).
6809CREATE AGGREGATE and_agg(UUID) (
6810 SFUNC = and_agg_sfunc,
6811 STYPE = UUID
6812);
6813
6814/**
6815 * @brief Marginal likelihood @c P(data) of an evidence circuit.
6816 *
6817 * The mean raw importance weight over @c provsql.rv_mc_samples prior draws
6818 * -- the same quantity rejection conditioning computes as @c P(C), now the
6819 * product of the observations' densities. @p evidence is an @c and_agg
6820 * conjunction of @c observe tokens (and/or Boolean events).
6821 */
6822CREATE OR REPLACE FUNCTION evidence(evidence UUID)
6823 RETURNS double precision
6824 AS 'provsql','rv_evidence' LANGUAGE C STRICT PARALLEL SAFE;
6825
6826/**
6827 * @brief The @c observe atoms of an evidence circuit.
6828 *
6829 * Collects every @c gate_observe leaf reachable through the @c gate_times
6830 * conjunction spine (the shape @c and_agg builds -- a possibly left-nested
6831 * tree, since @c provenance_times does not flatten). Used by
6832 * @c shapley_observe to recover the flat observation set regardless of the
6833 * conjunction's nesting.
6835CREATE OR REPLACE FUNCTION observe_atoms(evidence UUID)
6836 RETURNS UUID[] AS
6838 WITH RECURSIVE walk(tok) AS (
6839 SELECT evidence
6840 UNION
6841 SELECT c
6842 FROM walk, LATERAL unnest(provsql.get_children(walk.tok)) AS c
6843 WHERE provsql.get_gate_type(walk.tok) = 'times'
6844 )
6845 SELECT array_agg(tok ORDER BY tok)
6846 FROM walk
6847 WHERE provsql.get_gate_type(tok) = 'observe';
6848$$ LANGUAGE sql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
6849
6850/**
6851 * @brief Shapley attribution of each observation to a posterior moment.
6852 *
6853 * "Which observation most shifted my posterior?" Because the importance
6854 * weight is a product of per-observation density factors, dropping an
6855 * observation is dropping one factor: the classical Shapley value of each
6856 * @c gate_observe atom over the coalitional value function
6857 * @c "v(S) = payoff(target | observations in S)" is the attribution, a
6858 * byproduct of the same likelihood-weighting machinery (see the
6859 * explainable-inference angle in the continuous-distributions notes).
6860 *
6861 * @p target is the latent (its @c UUID); @p evidence is the @c and_agg
6862 * conjunction of @c observe atoms; @p payoff is @c 'expected' or
6863 * @c 'variance'. Returns each observation atom with its Shapley value; the
6864 * values sum to @c "payoff(target | all data) - payoff(target)" (Shapley
6865 * efficiency: the total shift from prior to posterior).
6866 *
6867 * Exact enumeration over the @c 2^n observation subsets, so it is capped at
6868 * @c n = 12 observations (sampling-based attribution for larger sets is
6869 * future work); pin @c provsql.monte_carlo_seed so the coalitional value
6870 * functions share common random numbers (lower-variance differences).
6871 */
6872CREATE OR REPLACE FUNCTION shapley_observe(
6873 target UUID, evidence UUID, payoff TEXT DEFAULT 'expected')
6874 RETURNS TABLE(observation UUID, value double precision) AS
6875$$
6876DECLARE
6877 atoms UUID[];
6878 n INT;
6879 nmasks INT;
6880 pv double precision[];
6881 popc INT[];
6882 fact double precision[];
6883 mask INT;
6884 i INT;
6885 j INT;
6886 cnt INT;
6887 subset UUID[];
6888 ev_s UUID;
6889 sh double precision;
6890 bit INT;
6891 s_size INT;
6892BEGIN
6893 IF payoff NOT IN ('expected', 'variance') THEN
6894 RAISE EXCEPTION 'provsql.shapley_observe: payoff must be ''expected'' or '
6895 '''variance'' (got %)', payoff;
6896 END IF;
6897 atoms := provsql.observe_atoms(evidence);
6898 n := coalesce(array_length(atoms, 1), 0);
6899 IF n = 0 THEN
6900 RAISE EXCEPTION 'provsql.shapley_observe: evidence contains no observe() '
6901 'atoms (got a % gate)', provsql.get_gate_type(evidence)
6902 USING ERRCODE = 'feature_not_supported',
6903 DETAIL = 'provsql-reason: shapley-observe-no-evidence; scope: out-of-scope';
6904 END IF;
6905 IF n > 12 THEN
6906 RAISE EXCEPTION 'provsql.shapley_observe: exact attribution over % '
6907 'observations is exponential; capped at 12 (sampling-based '
6908 'attribution is future work)', n
6909 USING ERRCODE = 'feature_not_supported',
6910 DETAIL = 'provsql-reason: shapley-observe-too-many; scope: out-of-scope';
6911 END IF;
6912
6913 -- factorials 0!..n! (fact[k+1] = k!)
6914 fact := ARRAY[1::double precision];
6915 FOR i IN 1..n LOOP fact := fact || (fact[i] * i); END LOOP;
6916
6917 nmasks := (1 << n);
6918 pv := array_fill(NULL::double precision, ARRAY[nmasks]);
6919 popc := array_fill(0, ARRAY[nmasks]);
6921 -- Payoff value function for every subset of observations.
6922 FOR mask IN 0 .. nmasks - 1 LOOP
6923 subset := ARRAY[]::UUID[];
6924 cnt := 0;
6925 FOR i IN 0 .. n - 1 LOOP
6926 IF (mask >> i) & 1 = 1 THEN
6927 subset := subset || atoms[i + 1];
6928 cnt := cnt + 1;
6929 END IF;
6930 END LOOP;
6931 popc[mask + 1] := cnt;
6932 IF cnt = 0 THEN
6933 ev_s := provsql.gate_one(); -- prior (no evidence)
6934 ELSE
6935 ev_s := provsql.provenance_times(VARIADIC subset);
6936 END IF;
6937 IF payoff = 'expected' THEN
6938 pv[mask + 1] := provsql.rv_moment(target, 1, false, ev_s);
6939 ELSE
6940 pv[mask + 1] := provsql.rv_moment(target, 2, true, ev_s);
6941 END IF;
6942 END LOOP;
6943
6944 -- Shapley value of each observation atom.
6945 FOR i IN 0 .. n - 1 LOOP
6946 sh := 0;
6947 bit := (1 << i);
6948 FOR mask IN 0 .. nmasks - 1 LOOP
6949 IF (mask >> i) & 1 = 0 THEN -- subsets S not containing i
6950 s_size := popc[mask + 1];
6951 -- weight |S|! (n-|S|-1)! / n!
6952 sh := sh + (fact[s_size + 1] * fact[n - s_size] / fact[n + 1])
6953 * (pv[(mask | bit) + 1] - pv[mask + 1]);
6954 END IF;
6955 END LOOP;
6956 observation := atoms[i + 1];
6957 value := sh;
6958 RETURN NEXT;
6959 END LOOP;
6960END
6961$$ LANGUAGE plpgsql VOLATILE
6962 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
6963
6964/**
6965 * @name Order statistics over random_variable
6966 *
6967 * Same-row @c greatest / @c least over @c random_variable arguments: the
6968 * order-statistic counterpart of the element-wise @c "+ - * /" operators.
6969 * They lower to a single @c gate_arith with the @c MAX / @c MIN opcode over
6970 * the argument circuits, the same n-ary shape the @c max / @c min aggregates
6971 * build. Evaluation is Monte-Carlo-correct out of the box (@c std::max /
6972 * @c std::min over the jointly-sampled children, so shared base RVs stay
6973 * coupled); closed forms for i.i.d. families come from the analytic
6974 * order-statistic pass.
6975 *
6976 * PostgreSQL's built-in @c GREATEST / @c LEAST are dedicated syntax (a
6977 * @c MinMaxExpr requiring a btree comparison), not overloadable functions, so
6978 * the surface is the schema-qualified @c provsql.greatest(...) /
6979 * @c provsql.least(...). @c NULL arguments are ignored, matching the built-in
6980 * (an all-@c NULL / empty call returns @c NULL).
6981 * @{
6983
6984-- "greatest" / "least" are col_name keywords, so the CREATE FUNCTION name
6985-- must be quoted; callers reach them qualified as provsql.greatest(...).
6986-- Idempotence: max / min ignore repeats, so identical children (same gate)
6987-- are de-duplicated -- greatest(x, x, y) == greatest(x, y) -- and a single
6988-- surviving child collapses to itself -- greatest(x) == x. DISTINCT also sorts
6989-- the children, so the argument order does not matter for gate sharing. (Two
6990-- independent draws of the same distribution are distinct gates and are NOT
6991-- de-duplicated.)
6992CREATE OR REPLACE FUNCTION "greatest"(VARIADIC args random_variable[])
6993 RETURNS random_variable AS
6994$$
6995DECLARE
6996 children UUID[];
6997BEGIN
6998 IF args IS NULL THEN
6999 RETURN NULL;
7000 END IF;
7001 SELECT array_agg(DISTINCT (a)::UUID) INTO children
7002 FROM unnest(args) a WHERE a IS NOT NULL;
7003 IF children IS NULL OR array_length(children, 1) IS NULL THEN
7004 RETURN NULL;
7005 END IF;
7006 IF array_length(children, 1) = 1 THEN
7007 RETURN provsql.random_variable_make(children[1]);
7008 END IF;
7009 RETURN provsql.random_variable_make(
7010 provsql.provenance_arith(5, children)); -- 5 = PROVSQL_ARITH_MAX
7011END
7012$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7013
7014CREATE OR REPLACE FUNCTION "least"(VARIADIC args random_variable[])
7015 RETURNS random_variable AS
7016$$
7017DECLARE
7018 children UUID[];
7019BEGIN
7020 IF args IS NULL THEN
7021 RETURN NULL;
7022 END IF;
7023 SELECT array_agg(DISTINCT (a)::UUID) INTO children
7024 FROM unnest(args) a WHERE a IS NOT NULL;
7025 IF children IS NULL OR array_length(children, 1) IS NULL THEN
7026 RETURN NULL;
7027 END IF;
7028 IF array_length(children, 1) = 1 THEN
7029 RETURN provsql.random_variable_make(children[1]);
7030 END IF;
7031 RETURN provsql.random_variable_make(
7032 provsql.provenance_arith(6, children)); -- 6 = PROVSQL_ARITH_MIN
7033END
7034$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7035
7037 * @brief Build a @c random_variable from a guarded-selection @c gate_case.
7038 *
7039 * Thin @c random_variable wrapper over @c provenance_case (defined with the
7040 * other gate builders, since it is UUID-only), the target of the planner-hook
7041 * @c CASE-over-RV rewrite: the hook flattens the branches into
7042 * @c [guard_1, value_1, ..., default] and emits this call so an RV-typed
7043 * @c CASE surfaces as a first-class @c random_variable.
7045CREATE OR REPLACE FUNCTION rv_case(
7046 children UUID[]
7047)
7048RETURNS random_variable AS
7049$$
7050 SELECT provsql.random_variable_make(provsql.provenance_case(children));
7051$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7052
7053/**
7054 * @brief Build an @c AGG_TOKEN from a guarded-selection @c gate_case.
7055 *
7056 * The aggregate-carrier analogue of @c rv_case: a thin @c AGG_TOKEN wrapper
7057 * over the carrier-agnostic @c provenance_case, the target of the planner-hook
7058 * lowering of a searched @c CASE whose guards are aggregate comparisons and
7059 * whose branches are aggregates. The branches (and default) are already
7060 * flattened into @c [guard_1, value_1, ..., default] UUIDs. The display cell
7061 * carries the actual-world CASE value -- the branch selected on the actual
7062 * data, resolved by @c agg_gate_value, exactly as a bare aggregate's cell
7063 * carries its actual-world value. The probabilistic result is produced by
7064 * the measure evaluators (``expected`` / ``probability`` / possible-worlds /
7065 * Monte Carlo) from the gate, not the token's cell.
7066 */
7067CREATE OR REPLACE FUNCTION agg_case(
7068 children UUID[]
7069)
7070RETURNS AGG_TOKEN AS
7071$$
7072 SELECT format('( %s , %s )', t::TEXT,
7073 coalesce(provsql.agg_gate_value(t)::TEXT, ''))::provsql.AGG_TOKEN
7074 FROM (SELECT provsql.provenance_case(children) AS t) AS s;
7075$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7076
7077/** @} */
7078
7079/**
7080 * @name Aggregates over random_variable
7081 *
7082 * An overload of the standard
7083 * @c sum aggregate that takes a @c random_variable per row and returns
7084 * the @c random_variable representing the (provenance-weighted) sum.
7085 * Lives in the @c provsql schema so a @c sum(random_variable) call
7086 * resolves to it without colliding with the built-in NUMERIC @c sum
7087 * overloads in @c pg_catalog.
7088 *
7089 * Direct calls outside a provenance-tracked query treat each row's
7090 * contribution unconditionally (no per-row Boolean selector). When
7091 * the planner hook sees a @c provsql.sum @c Aggref over a
7092 * provenance-tracked query, it wraps the per-row argument @c x in
7093 * <tt>provsql.mixture(prov_token, x, provsql.as_random(0))</tt> so the
7094 * aggregate's effective semantics become
7095 * @f$\mathrm{SUM}(x) = \sum_i \mathbf{1}\{\varphi_i\} \cdot X_i@f$,
7096 * the natural extension of semimodule-provenance to RV-valued M.
7097 *
7098 * The internal state is the array of UUIDs of the per-row mixtures.
7099 * The final function builds a single @c gate_arith @c PLUS over them
7100 * (or returns @c as_random(0) for an empty group, the additive
7101 * identity). Sharing on @c provenance_arith's v5 hash means two
7102 * @c sum invocations over the same set of rows collide on the same
7103 * gate.
7104 *
7105 * @{
7106 */
7108/**
7109 * @brief Per-row helper: wrap an RV in @c mixture(prov, rv, as_random(0)).
7110 *
7111 * Internal helper used by the planner-hook rewriter to lift a
7112 * @c sum(random_variable) argument into its provenance-aware form.
7113 * Encodes one row's contribution to the SUM as a Bernoulli mixture
7114 * over the row's provenance: with probability @c P(prov) the mixture
7115 * samples @c rv, otherwise it samples the additive identity
7116 * @c as_random(0). Exposed as a regular SQL function so the planner
7117 * can construct a @c FuncExpr by name without needing to disambiguate
7118 * @c mixture / @c as_random overloads at OID-lookup time.
7119 */
7120CREATE OR REPLACE FUNCTION rv_aggregate_semimod(
7121 prov UUID, rv random_variable)
7122 RETURNS random_variable AS
7123$$
7124 SELECT provsql.mixture(prov, rv, provsql.as_random(0::double precision));
7125$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7126
7127/**
7128 * @brief Identity-parameterised per-row wrap for an RV-returning aggregate.
7130 * Generalises the two-argument @ref rv_aggregate_semimod. The else-branch
7131 * (a row's contribution when its provenance is false) is
7132 * @c as_random(@p identity) instead of the additive @c as_random(0). The
7133 * planner-hook rewrite bakes each aggregate's own identity element into the
7134 * wrap -- @c 1 for @c product, @f$-\infty@f$ / @f$+\infty@f$ for @c max /
7135 * @c min -- so the aggregate's final function is a plain fold over the
7136 * per-row mixtures with no gate inspection. @c sum keeps the two-argument
7137 * form (@c identity @c = @c 0).
7138 */
7139CREATE OR REPLACE FUNCTION rv_aggregate_semimod(
7140 prov UUID, rv random_variable, identity double precision)
7141 RETURNS random_variable AS
7142$$
7143 SELECT provsql.mixture(prov, rv, provsql.as_random(identity));
7144$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7145
7146/**
7147 * @brief Per-row denominator wrap for @c avg(random_variable): the
7148 * provenance indicator @f$\mathbf{1}\{\varphi\}@f$.
7149 *
7150 * The row contributes @c 1 to the running count when present and @c 0 when
7151 * absent, so @c sum over these wraps is the provenance-weighted count
7152 * @f$\sum_i \mathbf{1}\{\varphi_i\}@f$. The planner-hook rewrites
7153 * @c avg(x) into @c rv_sum_or_null(rv_aggregate_semimod(prov, x)) @c /
7154 * @c sum(rv_aggregate_indicator(prov)) -- the "@c AVG @c = @c SUM @c /
7155 * @c COUNT" identity lifted into the @c random_variable algebra -- so
7156 * @c avg rides entirely on @c sum's fold and never inspects a gate.
7157 */
7158CREATE OR REPLACE FUNCTION rv_aggregate_indicator(prov UUID)
7159 RETURNS random_variable AS
7161 SELECT provsql.rv_aggregate_semimod(prov, provsql.as_random(1::double precision));
7162$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7163
7164/**
7165 * @brief Value-aware presence indicator: NULL when the row's aggregated
7166 * value is NULL.
7167 *
7168 * SQL aggregates skip NULL inputs, so a NULL @c random_variable cell must
7169 * not count in @c avg's denominator: the wrap yields NULL (which the
7170 * @c sum fold skips) exactly when the value is NULL, and the plain
7171 * one-argument indicator otherwise. The planner-hook @c avg rewrite
7172 * emits this form; the one-argument indicator remains for the internal
7173 * public-form defaults.
7174 */
7175CREATE OR REPLACE FUNCTION rv_aggregate_indicator(prov UUID, rv random_variable)
7176 RETURNS random_variable AS
7177$$
7178 SELECT CASE WHEN rv IS NULL THEN NULL
7179 ELSE provsql.rv_aggregate_indicator(prov) END;
7180$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7181
7182/**
7183 * @brief State-transition function for @c sum(random_variable).
7184 *
7185 * Appends the input RV's UUID to the running array. NULL inputs are
7186 * skipped (matching standard SUM semantics). The aggregate's INITCOND
7187 * is @c '{}' so the FINALFUNC always runs and can tell an empty group
7188 * (state @c '{}') apart from a group whose every input was NULL -- both
7189 * of which SQL reports as @c NULL.
7190 */
7191CREATE OR REPLACE FUNCTION sum_rv_sfunc(
7192 state UUID[], rv random_variable)
7193 RETURNS UUID[] AS
7194$$
7195 SELECT CASE
7196 WHEN rv IS NULL THEN state
7197 ELSE array_append(state, (rv)::UUID)
7198 END;
7199$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7200
7201/**
7202 * @brief Final function for @c sum(random_variable): build a
7203 * @c gate_arith PLUS root.
7204 *
7205 * Empty group (@c state = @c '{}'): return @c NULL, as SQL's @c sum
7206 * does over zero rows -- the same answer the @c AGG_TOKEN path gives
7207 * for @c sum over an empty aggregation.
7208 *
7209 * Singleton group: return the single child directly without minting a
7210 * useless single-child @c gate_arith.
7211 *
7212 * Otherwise: build @c gate_arith(PLUS, state) via @c provenance_arith.
7213 */
7214CREATE OR REPLACE FUNCTION sum_rv_ffunc(state UUID[])
7215 RETURNS random_variable AS
7216$$
7217DECLARE
7218 arith_token UUID;
7219BEGIN
7220 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7221 RETURN NULL;
7222 END IF;
7223 IF array_length(state, 1) = 1 THEN
7224 RETURN provsql.random_variable_make(state[1]);
7225 END IF;
7226 arith_token := provsql.provenance_arith(0, state); -- 0 = PROVSQL_ARITH_PLUS
7227 RETURN provsql.random_variable_make(arith_token);
7228END
7229$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7230
7231CREATE AGGREGATE sum(random_variable) (
7232 SFUNC = sum_rv_sfunc,
7233 STYPE = UUID[],
7234 INITCOND = '{}',
7235 FINALFUNC = sum_rv_ffunc
7236);
7237
7238/**
7239 * @brief Numerator final function for the @c avg rewrite: @c sum,
7240 * @c NULL on an empty group.
7241 *
7242 * Behaviourally identical to @ref sum_rv_ffunc; kept as a separate
7243 * catalog entry because the @c avg rewrite names it explicitly. The
7244 * planner-hook @c avg rewrite emits
7245 * @c rv_sum_or_null(rv_aggregate_semimod(prov, x)) @c /
7246 * @c sum(rv_aggregate_indicator(prov)); @c random_variable_div is
7247 * @c STRICT, so an empty group propagates the numerator's @c NULL and
7248 * @c avg is @c NULL -- the standard SQL @c AVG convention -- while a
7249 * non-empty group behaves exactly like @c sum.
7250 */
7251CREATE OR REPLACE FUNCTION rv_sum_or_null_ffunc(state UUID[])
7252 RETURNS random_variable AS
7254BEGIN
7255 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7256 RETURN NULL;
7257 END IF;
7258 IF array_length(state, 1) = 1 THEN
7259 RETURN provsql.random_variable_make(state[1]);
7260 END IF;
7261 RETURN provsql.random_variable_make(
7262 provsql.provenance_arith(0, state)); -- 0 = PROVSQL_ARITH_PLUS
7263END
7264$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7265
7266CREATE AGGREGATE rv_sum_or_null(random_variable) (
7267 SFUNC = sum_rv_sfunc,
7268 STYPE = UUID[],
7269 INITCOND = '{}',
7270 FINALFUNC = rv_sum_or_null_ffunc
7271);
7272
7273/**
7274 * @brief Final function for @c avg(random_variable).
7275 *
7276 * @c avg lifts the "@c AVG @c = @c SUM @c / @c COUNT" identity into the
7277 * @c random_variable algebra:
7278 * @f[
7279 * \mathrm{AVG}(x) \;=\; \frac{\sum_i \mathbf{1}\{\varphi_i\} \cdot X_i}
7280 * {\sum_i \mathbf{1}\{\varphi_i\}}.
7281 * @f]
7282 * In a provenance-tracked query the planner-hook rewrites @c avg(x) into
7283 * @c rv_sum_or_null(rv_aggregate_semimod(prov, x)) @c /
7284 * @c sum(rv_aggregate_indicator(prov)) (see
7285 * @c make_rv_aggregate_expression), so both the numerator and the
7286 * provenance-weighted count denominator are built by @c sum's fold and no
7287 * gate is inspected. This FFUNC is therefore reached only on an
7288 * @em untracked call, where every row is unconditionally present: the
7289 * numerator is @c sum over the raw per-row RVs and the denominator is the
7290 * plain row count @c n (each row contributing @c as_random(1)).
7291 *
7292 * Empty group: returns @c NULL, matching standard SQL @c AVG (and unlike
7293 * @c sum, whose empty group is the additive identity @c as_random(0)):
7294 * the caller cannot otherwise disambiguate "0 rows" from "rows summing
7295 * to 0".
7296 */
7297CREATE OR REPLACE FUNCTION avg_rv_ffunc(state UUID[])
7298 RETURNS random_variable AS
7299$$
7300DECLARE
7301 n INTEGER;
7302 i INTEGER;
7303 num_token UUID;
7304 denom_token UUID;
7305 denom_state UUID[] := '{}';
7306 one_uuid UUID;
7307BEGIN
7308 IF state IS NULL THEN
7309 RETURN NULL;
7310 END IF;
7311 n := array_length(state, 1);
7312 IF n IS NULL THEN
7313 RETURN NULL;
7314 END IF;
7315
7316 one_uuid := (provsql.as_random(1::double precision))::UUID;
7317 FOR i IN 1..n LOOP
7318 denom_state := array_append(denom_state, one_uuid);
7319 END LOOP;
7320
7321 IF n = 1 THEN
7322 num_token := state[1];
7323 denom_token := denom_state[1];
7324 ELSE
7325 num_token := provsql.provenance_arith(0, state); -- 0 = PLUS
7326 denom_token := provsql.provenance_arith(0, denom_state); -- 0 = PLUS
7327 END IF;
7328
7329 RETURN provsql.random_variable_make(
7330 provsql.provenance_arith(
7331 3, -- 3 = PROVSQL_ARITH_DIV
7332 ARRAY[num_token, denom_token]));
7333END
7334$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7335
7336CREATE AGGREGATE avg(random_variable) (
7337 SFUNC = sum_rv_sfunc,
7338 STYPE = UUID[],
7339 INITCOND = '{}',
7340 FINALFUNC = avg_rv_ffunc
7342
7343/**
7344 * @brief Final function for @c product(random_variable): fold a
7345 * @c gate_arith TIMES root over the per-row contributions.
7346 *
7347 * Multiplicative analogue of @c sum(random_variable):
7348 * @f[
7349 * \mathrm{PRODUCT}(x) \;=\; \prod_i \big(\mathbf{1}\{\varphi_i\} \cdot X_i
7350 * + \mathbf{1}\{\neg\varphi_i\} \cdot 1\big)
7351 * \;=\; \prod_{i : \varphi_i} X_i.
7352 * @f]
7353 * Each per-row contribution already carries the multiplicative identity
7354 * as its absent-row value: a provenance-tracked query wraps the argument
7355 * as @c mixture(prov_i, X_i, as_random(1)) (identity baked in by the
7356 * three-argument @ref rv_aggregate_semimod), and an untracked call passes
7357 * the raw RV through. So the FFUNC is a plain fold with no gate
7358 * inspection: @c gate_arith(TIMES, state).
7359 *
7360 * Reuses @c sum_rv_sfunc as the state-transition function. Empty group:
7361 * @c NULL, by symmetry with @c sum / @c avg / @c min / @c max, which take
7362 * it from their standard-SQL counterparts. The multiplicative identity
7363 * @c as_random(1) stays the absent-row value inside the fold, where it
7364 * belongs; a group containing no row has no product to report.
7365 * Singleton group: the single child directly, without a one-child TIMES
7366 * root.
7367 */
7368CREATE OR REPLACE FUNCTION product_rv_ffunc(state UUID[])
7369 RETURNS random_variable AS
7370$$
7371BEGIN
7372 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7373 RETURN NULL;
7374 END IF;
7375 IF array_length(state, 1) = 1 THEN
7376 RETURN provsql.random_variable_make(state[1]);
7377 END IF;
7378 RETURN provsql.random_variable_make(
7379 provsql.provenance_arith(1, state)); -- 1 = PROVSQL_ARITH_TIMES
7380END
7381$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7383CREATE AGGREGATE product(random_variable) (
7384 SFUNC = sum_rv_sfunc,
7385 STYPE = UUID[],
7386 INITCOND = '{}',
7387 FINALFUNC = product_rv_ffunc
7388);
7389
7390/**
7391 * @brief Final function for @c max(random_variable) / @c min(random_variable):
7392 * fold a @c gate_arith MAX / MIN root over the per-row contributions.
7393 *
7394 * The order-statistic analogues of @c sum / @c product:
7395 * @f[
7396 * \mathrm{MAX}(x) = \max_{i : \varphi_i} X_i, \qquad
7397 * \mathrm{MIN}(x) = \min_{i : \varphi_i} X_i.
7398 * @f]
7399 * A row absent in a world (its provenance @f$\varphi_i@f$ false) must not
7400 * perturb the extremum, so it contributes the order-statistic identity
7401 * @f$\mp\infty@f$. That identity is baked into each per-row contribution
7402 * upstream: a provenance-tracked query wraps the argument as
7403 * @c mixture(prov_i, X_i, as_random(∓∞)) (via the three-argument
7404 * @ref rv_aggregate_semimod), and an untracked call passes the raw RV
7405 * through. So the FFUNC is a plain fold with no gate inspection:
7406 * @c gate_arith(@p op, state).
7407 *
7408 * Empty group: @c NULL, as SQL's @c min / @c max report over zero rows.
7409 * @p identity belongs to the catalog signature and describes the per-row
7410 * absent contribution baked in upstream; the empty group does not consult
7411 * it, since @f$\mp\infty@f$ is an artefact of the fold rather than a value
7412 * the group actually contains.
7413 * Singleton group: the single child directly.
7414 */
7415CREATE OR REPLACE FUNCTION extremum_rv_ffunc(
7416 state UUID[], op INTEGER, identity double precision)
7417 RETURNS random_variable AS
7418$$
7419BEGIN
7420 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7421 RETURN NULL;
7422 END IF;
7423 IF array_length(state, 1) = 1 THEN
7424 RETURN provsql.random_variable_make(state[1]);
7425 END IF;
7426 RETURN provsql.random_variable_make(
7427 provsql.provenance_arith(op, state));
7428END
7429$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
7430
7431CREATE OR REPLACE FUNCTION max_rv_ffunc(state UUID[])
7432 RETURNS random_variable AS
7433$$
7434 -- 5 = PROVSQL_ARITH_MAX; empty-group / row-absent identity -inf.
7435 SELECT provsql.extremum_rv_ffunc(state, 5, '-Infinity'::double precision);
7436$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7437
7438CREATE OR REPLACE FUNCTION min_rv_ffunc(state UUID[])
7439 RETURNS random_variable AS
7440$$
7441 -- 6 = PROVSQL_ARITH_MIN; empty-group / row-absent identity +inf.
7442 SELECT provsql.extremum_rv_ffunc(state, 6, 'Infinity'::double precision);
7443$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7444
7445CREATE AGGREGATE max(random_variable) (
7446 SFUNC = sum_rv_sfunc,
7447 STYPE = UUID[],
7448 INITCOND = '{}',
7449 FINALFUNC = max_rv_ffunc
7450);
7451
7452CREATE AGGREGATE min(random_variable) (
7453 SFUNC = sum_rv_sfunc,
7454 STYPE = UUID[],
7455 INITCOND = '{}',
7456 FINALFUNC = min_rv_ffunc
7457);
7458
7459-- ---------------------------------------------------------------------
7460-- SQL-standard statistic aggregates over random_variable rows:
7461-- covar_pop / covar_samp / corr (two-argument), stddev_pop / stddev_samp
7462-- (one-argument), and the ordered-set percentile_cont.
7463--
7464-- Row presence is carried by a per-row 0/1 indicator RV: the public
7465-- aggregates use the certain indicator as_random(1) (every row present),
7466-- and a provenance-tracked query is rewritten by the planner hook
7467-- (make_rv_aggregate_expression) to the rv_*_impl aggregates whose extra
7468-- leading argument is rv_aggregate_indicator(prov), so a row absent in a
7469-- world drops out of every sum, the count, and the percentile member set.
7470-- The moment statistics are built from indicator-weighted power sums with
7471-- existing gate_arith opcodes (e.g. covar_pop = SXY/N - (SX/N)(SY/N)); a
7472-- world where the statistic is undefined (N = 0, or N = 1 for the sample
7473-- forms) divides by zero, which leaves the world without a value, as SQL
7474-- gives NULL there; the moment estimators skip such worlds. percentile_cont is the one gate the arithmetic
7475-- cannot express: it mints the PROVSQL_ARITH_PERCENTILE gate_arith
7476-- (interleaved [ind_1, x_1, ...] wires, fraction in extra) that the Monte
7477-- Carlo sampler evaluates by sorting each draw's present values and
7478-- interpolating.
7479-- ---------------------------------------------------------------------
7480
7481/** @brief State transition for the one-argument RV statistic aggregates
7482 * (@c stddev_pop / @c stddev_samp): append the certain indicator and the
7483 * row's RV as a pair. NULL rows are skipped (standard SQL). */
7484CREATE OR REPLACE FUNCTION rv_stat1_sfunc(state UUID[], x random_variable)
7485 RETURNS UUID[] AS
7486$$
7487 SELECT CASE
7488 WHEN x IS NULL THEN state
7489 ELSE state || ARRAY[(provsql.as_random(1::double precision))::UUID,
7490 (x)::UUID]
7491 END;
7492$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7493
7494/** @brief State transition for the two-argument RV statistic aggregates
7495 * (@c covar_pop / @c covar_samp / @c corr): append the certain indicator
7496 * and the row's RV pair as a triple. Rows with either side NULL are
7497 * skipped (standard SQL covariance semantics). */
7498CREATE OR REPLACE FUNCTION rv_stat2_sfunc(
7499 state UUID[], x random_variable, y random_variable)
7500 RETURNS UUID[] AS
7501$$
7502 SELECT CASE
7503 WHEN x IS NULL OR y IS NULL THEN state
7504 ELSE state || ARRAY[(provsql.as_random(1::double precision))::UUID,
7505 (x)::UUID, (y)::UUID]
7506 END;
7507$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7508
7509/** @brief Indicator-carrying state transition for the one-argument
7510 * @c rv_*_impl statistic aggregates: the planner-hook rewrite passes the
7511 * row's provenance indicator @c rv_aggregate_indicator(prov) as @p ind. */
7512CREATE OR REPLACE FUNCTION rv_stat1_impl_sfunc(
7513 state UUID[], ind random_variable, x random_variable)
7514 RETURNS UUID[] AS
7515$$
7516 SELECT CASE
7517 WHEN x IS NULL THEN state
7518 ELSE state || ARRAY[coalesce((ind)::UUID,
7519 (provsql.as_random(1::double precision))::UUID),
7520 (x)::UUID]
7521 END;
7522$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7523
7524/** @brief Indicator-carrying state transition for the two-argument
7525 * @c rv_*_impl statistic aggregates. */
7526CREATE OR REPLACE FUNCTION rv_stat2_impl_sfunc(
7527 state UUID[], ind random_variable, x random_variable, y random_variable)
7528 RETURNS UUID[] AS
7529$$
7530 SELECT CASE
7531 WHEN x IS NULL OR y IS NULL THEN state
7532 ELSE state || ARRAY[coalesce((ind)::UUID,
7533 (provsql.as_random(1::double precision))::UUID),
7534 (x)::UUID, (y)::UUID]
7535 END;
7536$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7537
7538/**
7539 * @brief Mint the indicator-weighted power-sum gates shared by the
7540 * covariance / stddev final functions.
7541 *
7542 * @p state is the flat interleaved aggregate state -- pairs
7543 * @c [ind, x, ...] (@p stride 2) or triples @c [ind, x, y, ...]
7544 * (@p stride 3). Emits @c gate_arith tokens for
7545 * @f$N = \sum_i \mathbf{1}_i@f$, @f$SX = \sum_i \mathbf{1}_i x_i@f$,
7546 * @f$SXX = \sum_i \mathbf{1}_i x_i^2@f$ and, at stride 3, @f$SY@f$,
7547 * @f$SXY@f$, @f$SYY@f$. The per-row indicator gate is shared between
7548 * @f$N@f$ and every product it weighs, so the Monte Carlo per-iteration
7549 * cache keeps the row's presence coupled across all the sums (and a
7550 * repeated child @c [ind, x, x] reuses the same draw of @c x, giving
7551 * @f$x^2@f$, not two independent draws).
7552 */
7553CREATE OR REPLACE FUNCTION rv_stat_sum_tokens(
7554 state UUID[], stride INTEGER,
7555 OUT n_tok UUID, OUT sx_tok UUID, OUT sxx_tok UUID,
7556 OUT sy_tok UUID, OUT sxy_tok UUID, OUT syy_tok UUID)
7557AS
7558$$
7559DECLARE
7560 nrows INTEGER := coalesce(array_length(state, 1), 0) / stride;
7561 inds UUID[] := '{}';
7562 xs UUID[] := '{}';
7563 xxs UUID[] := '{}';
7564 ys UUID[] := '{}';
7565 xys UUID[] := '{}';
7566 yys UUID[] := '{}';
7567 ind UUID;
7568 x UUID;
7569 y UUID;
7570BEGIN
7571 FOR i IN 1..nrows LOOP
7572 ind := state[(i-1) * stride + 1];
7573 x := state[(i-1) * stride + 2];
7574 inds := array_append(inds, ind);
7575 xs := array_append(xs, provenance_arith(1, ARRAY[ind, x]));
7576 xxs := array_append(xxs, provenance_arith(1, ARRAY[ind, x, x]));
7577 IF stride = 3 THEN
7578 y := state[(i-1) * stride + 3];
7579 ys := array_append(ys, provenance_arith(1, ARRAY[ind, y]));
7580 xys := array_append(xys, provenance_arith(1, ARRAY[ind, x, y]));
7581 yys := array_append(yys, provenance_arith(1, ARRAY[ind, y, y]));
7582 END IF;
7583 END LOOP;
7584 n_tok := provenance_arith(0, inds);
7585 sx_tok := provenance_arith(0, xs);
7586 sxx_tok := provenance_arith(0, xxs);
7587 IF stride = 3 THEN
7588 sy_tok := provenance_arith(0, ys);
7589 sxy_tok := provenance_arith(0, xys);
7590 syy_tok := provenance_arith(0, yys);
7591 END IF;
7593$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7594 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7595
7596/** @brief Population-variance gate @f$SXX/N - (SX/N)^2@f$ from the
7597 * power-sum tokens. */
7598CREATE OR REPLACE FUNCTION rv_stat_var_pop_token(
7599 n_tok UUID, s_tok UUID, ss_tok UUID)
7600 RETURNS UUID AS
7601$$
7602 SELECT provsql.provenance_arith(2, ARRAY[
7603 provsql.provenance_arith(3, ARRAY[ss_tok, n_tok]),
7604 provsql.provenance_arith(1, ARRAY[
7605 provsql.provenance_arith(3, ARRAY[s_tok, n_tok]),
7606 provsql.provenance_arith(3, ARRAY[s_tok, n_tok])])]);
7607$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7608
7609/** @brief Sample-variance gate @f$(SXX - SX^2/N) / (N - 1)@f$ from the
7610 * power-sum tokens (no value in a world with @f$N \le 1@f$, where it
7611 * divides by zero, as SQL gives NULL there). */
7612CREATE OR REPLACE FUNCTION rv_stat_var_samp_token(
7613 n_tok UUID, s_tok UUID, ss_tok UUID)
7614 RETURNS UUID AS
7615$$
7616 SELECT provsql.provenance_arith(3, ARRAY[
7617 provsql.provenance_arith(2, ARRAY[
7618 ss_tok,
7619 provsql.provenance_arith(3, ARRAY[
7620 provsql.provenance_arith(1, ARRAY[s_tok, s_tok]), n_tok])]),
7621 provsql.provenance_arith(2, ARRAY[
7622 n_tok, (provsql.as_random(1::double precision))::UUID])]);
7623$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7624
7625/** @brief @f$\sqrt{\max(v, 0)}@f$ gate over a variance token: the max-clamp
7626 * removes the tiny negative values float error can produce (variance is
7627 * mathematically non-negative), so the POW domain guard never fires. */
7628CREATE OR REPLACE FUNCTION rv_stat_sqrt_token(v_tok UUID)
7629 RETURNS UUID AS
7630$$
7631 SELECT provsql.provenance_arith(7, ARRAY[
7632 provsql.provenance_arith(5, ARRAY[
7633 v_tok, (provsql.as_random(0::double precision))::UUID]),
7634 (provsql.as_random(0.5::double precision))::UUID]);
7635$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7636
7637/** @brief Population-covariance gate @f$SXY/N - (SX/N)(SY/N)@f$ from the
7638 * power-sum tokens. */
7639CREATE OR REPLACE FUNCTION rv_stat_covar_pop_token(
7640 n_tok UUID, sx_tok UUID, sy_tok UUID, sxy_tok UUID)
7641 RETURNS UUID AS
7642$$
7643 SELECT provsql.provenance_arith(2, ARRAY[
7644 provsql.provenance_arith(3, ARRAY[sxy_tok, n_tok]),
7645 provsql.provenance_arith(1, ARRAY[
7646 provsql.provenance_arith(3, ARRAY[sx_tok, n_tok]),
7647 provsql.provenance_arith(3, ARRAY[sy_tok, n_tok])])]);
7648$$ LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE;
7649
7650/** @brief Final function for @c covar_pop(random_variable, random_variable). */
7651CREATE OR REPLACE FUNCTION covar_pop_rv_ffunc(state UUID[])
7652 RETURNS random_variable AS
7653$$
7654DECLARE
7655 t RECORD;
7656BEGIN
7657 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7658 RETURN NULL;
7659 END IF;
7660 SELECT * INTO t FROM rv_stat_sum_tokens(state, 3);
7661 RETURN random_variable_make(
7662 rv_stat_covar_pop_token(t.n_tok, t.sx_tok, t.sy_tok, t.sxy_tok));
7663END
7664$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7665 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7666
7667/** @brief Final function for @c covar_samp(random_variable, random_variable):
7668 * @f$(SXY - SX\,SY/N) / (N-1)@f$. */
7669CREATE OR REPLACE FUNCTION covar_samp_rv_ffunc(state UUID[])
7670 RETURNS random_variable AS
7671$$
7672DECLARE
7673 t RECORD;
7674BEGIN
7675 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7676 RETURN NULL;
7677 END IF;
7678 SELECT * INTO t FROM rv_stat_sum_tokens(state, 3);
7679 RETURN random_variable_make(
7680 provenance_arith(3, ARRAY[
7681 provenance_arith(2, ARRAY[
7682 t.sxy_tok,
7683 provenance_arith(3, ARRAY[
7684 provenance_arith(1, ARRAY[t.sx_tok, t.sy_tok]), t.n_tok])]),
7685 provenance_arith(2, ARRAY[
7686 t.n_tok, (as_random(1::double precision))::UUID])]));
7687END
7688$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7689 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7690
7691/** @brief Final function for @c corr(random_variable, random_variable):
7692 * @f$\mathrm{covar\_pop} / \sqrt{\max(v_x v_y, 0)}@f$ (a zero-variance
7693 * world divides by zero and has no value, matching SQL's NULL for a
7694 * zero-stddev input). */
7695CREATE OR REPLACE FUNCTION corr_rv_ffunc(state UUID[])
7696 RETURNS random_variable AS
7697$$
7698DECLARE
7699 t RECORD;
7700 vx UUID;
7701 vy UUID;
7702BEGIN
7703 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7704 RETURN NULL;
7705 END IF;
7706 SELECT * INTO t FROM rv_stat_sum_tokens(state, 3);
7707 vx := rv_stat_var_pop_token(t.n_tok, t.sx_tok, t.sxx_tok);
7708 vy := rv_stat_var_pop_token(t.n_tok, t.sy_tok, t.syy_tok);
7709 RETURN random_variable_make(
7710 provenance_arith(3, ARRAY[
7711 rv_stat_covar_pop_token(t.n_tok, t.sx_tok, t.sy_tok, t.sxy_tok),
7712 rv_stat_sqrt_token(provenance_arith(1, ARRAY[vx, vy]))]));
7713END
7714$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7715 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7716
7717/** @brief Final function for @c stddev_pop(random_variable). */
7718CREATE OR REPLACE FUNCTION stddev_pop_rv_ffunc(state UUID[])
7719 RETURNS random_variable AS
7720$$
7721DECLARE
7722 t RECORD;
7723BEGIN
7724 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7725 RETURN NULL;
7726 END IF;
7727 SELECT * INTO t FROM rv_stat_sum_tokens(state, 2);
7728 RETURN random_variable_make(
7729 rv_stat_sqrt_token(
7730 rv_stat_var_pop_token(t.n_tok, t.sx_tok, t.sxx_tok)));
7731END
7732$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7733 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7734
7735/** @brief Final function for @c stddev_samp(random_variable). */
7736CREATE OR REPLACE FUNCTION stddev_samp_rv_ffunc(state UUID[])
7737 RETURNS random_variable AS
7738$$
7739DECLARE
7740 t RECORD;
7741BEGIN
7742 IF state IS NULL OR array_length(state, 1) IS NULL THEN
7743 RETURN NULL;
7744 END IF;
7745 SELECT * INTO t FROM rv_stat_sum_tokens(state, 2);
7746 RETURN random_variable_make(
7747 rv_stat_sqrt_token(
7748 rv_stat_var_samp_token(t.n_tok, t.sx_tok, t.sxx_tok)));
7750$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7751 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7752
7753CREATE AGGREGATE covar_pop(random_variable, random_variable) (
7754 SFUNC = rv_stat2_sfunc,
7755 STYPE = UUID[],
7756 INITCOND = '{}',
7757 FINALFUNC = covar_pop_rv_ffunc
7758);
7759
7760CREATE AGGREGATE covar_samp(random_variable, random_variable) (
7761 SFUNC = rv_stat2_sfunc,
7762 STYPE = UUID[],
7763 INITCOND = '{}',
7764 FINALFUNC = covar_samp_rv_ffunc
7765);
7766
7767CREATE AGGREGATE corr(random_variable, random_variable) (
7768 SFUNC = rv_stat2_sfunc,
7769 STYPE = UUID[],
7770 INITCOND = '{}',
7771 FINALFUNC = corr_rv_ffunc
7772);
7774CREATE AGGREGATE stddev_pop(random_variable) (
7775 SFUNC = rv_stat1_sfunc,
7776 STYPE = UUID[],
7777 INITCOND = '{}',
7778 FINALFUNC = stddev_pop_rv_ffunc
7779);
7780
7781CREATE AGGREGATE stddev_samp(random_variable) (
7782 SFUNC = rv_stat1_sfunc,
7783 STYPE = UUID[],
7784 INITCOND = '{}',
7785 FINALFUNC = stddev_samp_rv_ffunc
7786);
7787
7788-- The indicator-carrying rewrite targets (planner hook only; never called
7789-- directly by users).
7790
7791CREATE AGGREGATE rv_covar_pop_impl(
7792 random_variable, random_variable, random_variable) (
7793 SFUNC = rv_stat2_impl_sfunc,
7794 STYPE = UUID[],
7795 INITCOND = '{}',
7796 FINALFUNC = covar_pop_rv_ffunc
7797);
7798
7799CREATE AGGREGATE rv_covar_samp_impl(
7800 random_variable, random_variable, random_variable) (
7801 SFUNC = rv_stat2_impl_sfunc,
7802 STYPE = UUID[],
7803 INITCOND = '{}',
7804 FINALFUNC = covar_samp_rv_ffunc
7805);
7806
7807CREATE AGGREGATE rv_corr_impl(
7808 random_variable, random_variable, random_variable) (
7809 SFUNC = rv_stat2_impl_sfunc,
7810 STYPE = UUID[],
7811 INITCOND = '{}',
7812 FINALFUNC = corr_rv_ffunc
7813);
7814
7815CREATE AGGREGATE rv_stddev_pop_impl(random_variable, random_variable) (
7816 SFUNC = rv_stat1_impl_sfunc,
7817 STYPE = UUID[],
7818 INITCOND = '{}',
7819 FINALFUNC = stddev_pop_rv_ffunc
7820);
7821
7822CREATE AGGREGATE rv_stddev_samp_impl(random_variable, random_variable) (
7823 SFUNC = rv_stat1_impl_sfunc,
7824 STYPE = UUID[],
7825 INITCOND = '{}',
7826 FINALFUNC = stddev_samp_rv_ffunc
7827);
7828
7829/**
7830 * @brief Mint the @c PROVSQL_ARITH_PERCENTILE gate: the continuous
7831 * percentile (SQL @c percentile_cont) over a group of RV rows.
7832 *
7833 * @p pairs is the interleaved wire list @c [ind_1, x_1, ..., ind_n, x_n]
7834 * (each @p ind_i a 0/1 presence-indicator RV). The @p fraction is
7835 * TEXT-encoded in the gate's @c extra and participates in the token UUID
7836 * (two percentiles of the same group at different fractions are distinct
7837 * gates). Per Monte Carlo draw, the sampler collects the values whose
7838 * indicator draws 1, sorts them, and linearly interpolates at the
7839 * fraction; a draw with no present value has no value (SQL's NULL).
7840 */
7841CREATE OR REPLACE FUNCTION rv_percentile_make(fraction double precision,
7842 pairs UUID[])
7843 RETURNS random_variable AS
7844$$
7845DECLARE
7846 token UUID;
7847BEGIN
7848 IF fraction IS NULL THEN
7849 RETURN NULL;
7850 END IF;
7851 IF fraction < 0 OR fraction > 1 THEN
7852 RAISE EXCEPTION
7853 'percentile_cont: fraction must be between 0 and 1 (got %)', fraction;
7854 END IF;
7855 token := public.uuid_generate_v5(
7856 uuid_ns_provsql(),
7857 concat('arith', '10', pairs::TEXT, fraction::TEXT));
7858 -- 10 = PROVSQL_ARITH_PERCENTILE
7859 PERFORM create_gate(token, 'arith', pairs, 10, NULL, fraction::TEXT);
7860 RETURN random_variable_make(token);
7861END
7862$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE
7863 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
7864
7865/** @brief State transition for the public ordered-set
7866 * @c percentile_cont(float8) WITHIN GROUP (ORDER BY random_variable):
7867 * append the certain indicator and the row's RV. Only reachable on
7868 * untracked input (a provenance-tracked query is rewritten to
7869 * @c rv_percentile_impl before planning), where the sort over
7870 * @c random_variable raises the ordering-is-meaningless diagnostic
7871 * first -- so in practice this runs only for empty input. */
7872CREATE OR REPLACE FUNCTION percentile_cont_rv_sfunc(
7873 state UUID[], x random_variable)
7874 RETURNS UUID[] AS
7875$$
7876 SELECT provsql.rv_stat1_sfunc(state, x);
7877$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7878
7879/** @brief Final function for the public ordered-set @c percentile_cont:
7880 * receives the direct @p fraction argument after the state. */
7881CREATE OR REPLACE FUNCTION percentile_cont_rv_ffunc(
7882 state UUID[], fraction double precision)
7883 RETURNS random_variable AS
7884$$
7885 SELECT CASE
7886 WHEN state IS NULL OR array_length(state, 1) IS NULL THEN NULL
7887 ELSE provsql.rv_percentile_make(fraction, state)
7888 END;
7889$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7890
7891CREATE AGGREGATE percentile_cont(double precision ORDER BY random_variable) (
7892 SFUNC = percentile_cont_rv_sfunc,
7893 STYPE = UUID[],
7894 INITCOND = '{}',
7895 FINALFUNC = percentile_cont_rv_ffunc
7896);
7897
7898/** @brief Transition state for @c rv_percentile_impl: the fraction (from
7899 * the first row) plus the interleaved indicator/value token pairs. */
7900CREATE TYPE rv_percentile_state AS (
7901 fraction double precision,
7902 tokens UUID[]
7903);
7904
7905/** @brief State transition for @c rv_percentile_impl, the planner-hook
7906 * rewrite target of a provenance-tracked @c percentile_cont: stashes the
7907 * (group-constant) fraction and appends the indicator/value pair. */
7908CREATE OR REPLACE FUNCTION rv_percentile_impl_sfunc(
7909 state rv_percentile_state, fraction double precision,
7910 ind random_variable, x random_variable)
7911 RETURNS rv_percentile_state AS
7912$$
7913 SELECT ROW(
7914 coalesce((state).fraction, fraction),
7915 CASE
7916 WHEN x IS NULL THEN (state).tokens
7917 ELSE (state).tokens ||
7918 ARRAY[coalesce((ind)::UUID,
7919 (provsql.as_random(1::double precision))::UUID),
7920 (x)::UUID]
7921 END)::provsql.rv_percentile_state;
7922$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7923
7924/** @brief Final function for @c rv_percentile_impl. */
7925CREATE OR REPLACE FUNCTION rv_percentile_impl_ffunc(state rv_percentile_state)
7926 RETURNS random_variable AS
7927$$
7928 SELECT CASE
7929 WHEN state IS NULL OR array_length((state).tokens, 1) IS NULL THEN NULL
7930 ELSE provsql.rv_percentile_make((state).fraction, (state).tokens)
7931 END;
7932$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
7933
7934CREATE AGGREGATE rv_percentile_impl(
7935 double precision, random_variable, random_variable) (
7936 SFUNC = rv_percentile_impl_sfunc,
7937 STYPE = rv_percentile_state,
7938 INITCOND = '(,"{}")',
7939 FINALFUNC = rv_percentile_impl_ffunc
7940);
7941
7942/** @} */
7943
7944/** @} */
7945
7946/** @} */
7947
7948/** @defgroup aggregate_provenance Aggregate provenance
7949 * Functions for building and evaluating aggregate (GROUP BY) provenance,
7950 * including the δ-semiring operator and semimodule multiplication.
7951 * @{
7952 */
7953
7954/**
7955 * @brief Create a δ-semiring gate wrapping a provenance token
7956 *
7957 * Used internally for aggregate provenance. Returns the token unchanged
7958 * if it is gate_zero() or gate_one(), and gate_one() if the token is NULL.
7959 *
7960 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
7961 * PL/pgSQL function it was, so that plans stay the same.
7962 */
7963CREATE OR REPLACE FUNCTION provenance_delta
7964 (token UUID)
7965 RETURNS UUID AS
7966 'provsql','provenance_delta' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
7967
7968/**
7969 * @brief Build an aggregate provenance gate from grouped tokens
7970 *
7971 * Called internally by the query rewriter for GROUP BY queries.
7972 * Creates an agg gate linking all contributing tokens and records
7973 * the aggregate function OID and the computed scalar value. The gate's
7974 * address hashes everything it records, result type and value included:
7975 * what is recorded is written once, and two aggregations that differ only
7976 * there (a polymorphic aggregate over two types with the same texts, a
7977 * floating-point sum rounded differently by two plans) must be two gates.
7978 *
7979 * @param aggfnoid OID of the SQL aggregate function
7980 * @param aggtype OID of the aggregate result type
7981 * @param val computed aggregate value
7982 * @param tokens array of provenance tokens being aggregated
7983 * @param is_scalar true for a scalar (no GROUP BY) aggregation, whose
7984 * output row exists even when no tuple is present; stored in the
7985 * high bit of info2
7986 *
7987 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
7988 * PL/pgSQL function it was, so that plans stay the same.
7989 */
7990CREATE OR REPLACE FUNCTION provenance_aggregate(
7991 aggfnoid INTEGER,
7992 aggtype INTEGER,
7993 val ANYELEMENT,
7994 tokens UUID[],
7995 is_scalar BOOLEAN DEFAULT false)
7996 RETURNS AGG_TOKEN AS
7997 'provsql','provenance_aggregate' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
7998
7999/**
8000 * @brief Create a semimodule scalar multiplication gate
8001 *
8002 * Pairs a scalar value with a provenance token, used internally by
8003 * the query rewriter for aggregate provenance.
8004 *
8005 * @param val the scalar value
8006 * @param token the provenance token to multiply
8007 *
8008 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
8009 * PL/pgSQL function it was, so that plans stay the same.
8010 */
8011CREATE OR REPLACE FUNCTION provenance_semimod(val ANYELEMENT, token UUID)
8012 RETURNS UUID AS
8013 'provsql','provenance_semimod' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
8014
8015/**
8016 * @brief The contribution of an aggregate result to an aggregate of another
8017 * kind over it (internal)
8018 *
8019 * For a row of token @p token whose value @p val is the result of an
8020 * aggregate of another kind than the one aggregating it (an @c avg of a
8021 * @c count, a @c max of a @c sum, an aggregate of an arithmetic expression
8022 * over aggregates): @c semimod(g, token), where @c g is the inner
8023 * aggregate's own gate. Its value is one per possible world, not one value
8024 * of the database, so the evaluators that read a value per world resolve it
8025 * and the closed forms decline it.
8026 */
8027CREATE FUNCTION provenance_semimod_nested(val AGG_TOKEN, token UUID)
8028 RETURNS UUID AS
8029 'provsql','provenance_semimod_nested' LANGUAGE C PARALLEL SAFE IMMUTABLE;
8030
8031/**
8032 * @brief The contributions of an aggregate result to an aggregate of the
8033 * same kind over it (internal)
8034 *
8035 * For a row of token @p token whose value @p val is the result of
8036 * @c sum / @c count / @c max / @c min over a group, aggregated again by
8037 * @c sum / @c max / @c min: the contributions @c semimod(v_i, token ⊗ k_i)
8038 * of the group's own contributions @c semimod(v_i, k_i), so that
8039 * @c sum(sum(x)) is @c sum(x) over the rows of the groups -- semimodule
8040 * scalar multiplication, in every semiring. Collected by
8041 * @c provenance_contributions_cat.
8042 */
8043CREATE FUNCTION provenance_semimod_flat(val AGG_TOKEN, token UUID)
8044 RETURNS UUID[] AS
8045 'provsql','provenance_semimod_flat' LANGUAGE C PARALLEL SAFE IMMUTABLE;
8046
8047/** @brief Concatenation of the arrays of contributions of
8048 * @c provenance_semimod_flat (internal) */
8049CREATE AGGREGATE provenance_contributions_cat(UUID[]) (
8050 SFUNC = array_cat,
8051 STYPE = UUID[],
8052 INITCOND = '{}'
8053);
8054
8055/**
8056 * @brief Semimodule gate for an aggregate that sees its NULL inputs
8057 *
8058 * Variant of provenance_semimod() used by the query rewriter for
8059 * <tt>array_agg</tt>, <tt>json_agg</tt> and the like, whose result lists
8060 * every input, NULLs included: a NULL value still yields a semimod gate,
8061 * over the constant value gate gate_null().
8062 *
8063 * @param val the scalar value, possibly NULL
8064 * @param token the provenance token to multiply
8065 *
8066 * Implemented in C (<tt>gate_builders.c</tt>), with the declared cost of the
8067 * PL/pgSQL function it was, so that plans stay the same.
8068 */
8069CREATE OR REPLACE FUNCTION provenance_semimod_nullable(val ANYELEMENT, token UUID)
8070 RETURNS UUID AS
8071 'provsql','provenance_semimod_nullable' LANGUAGE C COST 100 PARALLEL SAFE IMMUTABLE;
8072
8073/**
8074 * @brief The rank of a row standing for its row number (internal)
8075 *
8076 * Called by the query rewriter for <tt>row_number() OVER (…)</tt> over
8077 * provenance-tracked relations, which is tracked as <tt>rank()</tt>: the two
8078 * are equal when the <tt>ORDER BY</tt> of the window leaves no ties. Returns
8079 * @p rank, with a warning, once per statement, when @p row_number differs
8080 * from it.
8081 *
8082 * @param rank the AGG_TOKEN of the rank of the row
8083 * @param row_number the row number of the row among those of the database
8084 * as it is, or NULL for a row absent from it (no check then)
8085 * @param tied whether the row ties on the <tt>ORDER BY</tt> with another row
8086 * of any world, which warns as well
8087 */
8088CREATE OR REPLACE FUNCTION row_number_as_rank(rank AGG_TOKEN, row_number bigint,
8089 tied BOOLEAN DEFAULT false)
8090 RETURNS AGG_TOKEN
8091 AS 'provsql','row_number_as_rank' LANGUAGE C VOLATILE PARALLEL SAFE;
8092
8093/** @brief Transition function of order_determined (internal) */
8094CREATE OR REPLACE FUNCTION order_determined_transfn(internal, INTEGER, VARIADIC "any")
8095 RETURNS internal
8096 AS 'provsql','order_determined_transfn' LANGUAGE C PARALLEL SAFE;
8097
8098/** @brief Final function of order_determined (internal) */
8099CREATE OR REPLACE FUNCTION order_determined_finalfn(internal)
8100 RETURNS BOOLEAN
8101 AS 'provsql','order_determined_finalfn' LANGUAGE C PARALLEL SAFE;
8102
8103/**
8104 * @brief Whether an order-dependent aggregate reads its rows in an order the
8105 * query determines (internal)
8106 *
8107 * Called by the query rewriter beside @c array_agg, @c string_agg, the
8108 * @c json_agg family and @c xmlagg over provenance-tracked relations, with
8109 * the aggregate's own arguments (the first @p nvals ones) and @c ORDER
8110 * @c BY, over every row of the group, those present only in other worlds
8111 * included: false when two rows tie on the @c ORDER @c BY (or there is
8112 * none) with different values.
8113 */
8114CREATE AGGREGATE order_determined(nvals INTEGER, VARIADIC "any") (
8115 SFUNC = order_determined_transfn,
8116 STYPE = internal,
8117 FINALFUNC = order_determined_finalfn
8118);
8119
8120/**
8121 * @brief The value of an order-dependent aggregate, with a warning where its
8122 * order is not determined (internal)
8123 *
8124 * Returns @p val, with a warning, once per statement, when @p determined
8125 * (from @c order_determined) is false: the order of the rows in the
8126 * database as it is is the one read in every world. @p is_window for a
8127 * window function (@c lag, @c first_value, ...), which warns as such.
8128 */
8129CREATE OR REPLACE FUNCTION order_checked(val ANYELEMENT, determined BOOLEAN,
8130 is_window BOOLEAN DEFAULT false)
8131 RETURNS ANYELEMENT
8132 AS 'provsql','order_checked' LANGUAGE C VOLATILE PARALLEL SAFE;
8133
8134/**
8135 * @brief The bucket of a row read over its rank, for @c ntile() (internal)
8136 *
8137 * Called by the query rewriter for <tt>ntile(n) OVER (…)</tt> over
8138 * provenance-tracked relations, whose bucket is computed from the rank of the
8139 * row: rows that tie on the <tt>ORDER BY</tt> share a bucket, where SQL may
8140 * split them. Returns @p bucket, with a warning, once per statement, when
8141 * @p sql_bucket differs from it.
8142 *
8143 * @param bucket the AGG_TOKEN of the tracked bucket
8144 * @param sql_bucket the bucket PostgreSQL gave the row
8145 */
8146CREATE OR REPLACE FUNCTION ntile_as_rank(bucket AGG_TOKEN, sql_bucket bigint)
8147 RETURNS AGG_TOKEN
8148 AS 'provsql','ntile_as_rank' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
8149
8150/**
8151 * @brief The event that an aggregate result is NULL, or is not (internal)
8152 *
8153 * Called by the query rewriter for an <tt>IS [NOT] NULL</tt> on an aggregate
8154 * column of a subquery, where the aggregate's own call is not at hand. A
8155 * row whose value is NULL contributes nothing to the aggregate's gate, so,
8156 * the row of the aggregate being there, its value is NULL exactly when none
8157 * of the rows its gate holds is: <tt>1 ⊖ ⊕K</tt> over their tokens, and
8158 * <tt>⊕K</tt> for IS NOT NULL. A NULL @p aggtok (a padded row) is NULL.
8159 *
8160 * @param aggtok the aggregate result
8161 * @param want_null true for IS NULL, false for IS NOT NULL
8162 */
8163CREATE OR REPLACE FUNCTION agg_token_null_event(aggtok AGG_TOKEN, want_null BOOLEAN)
8164 RETURNS UUID AS
8165$$
8166DECLARE
8167 g UUID;
8168 p UUID;
8169BEGIN
8170 IF aggtok IS NULL THEN
8171 RETURN CASE WHEN want_null THEN provsql.gate_one() ELSE provsql.gate_zero() END;
8172 END IF;
8173 RETURN provsql.agg_gate_null_event(provsql.agg_token_uuid(aggtok), want_null);
8174END
8175$$ LANGUAGE plpgsql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
8176
8177/**
8178 * @brief Whether a count may be 0 where its group is there (internal)
8179 *
8180 * The companion count(arg) the explosion of an aggregate value gives a
8181 * grouped aggregate has one contribution per row of the group, 1 where arg
8182 * has a value and 0 where it is NULL: the aggregate can be NULL only if one
8183 * row contributes 0. Its rows are all there, those the query keeps only for
8184 * their provenance included, which a count of the data would miss.
8185 *
8186 * @param cnt the count
8187 */
8188CREATE OR REPLACE FUNCTION agg_count_can_be_zero(cnt AGG_TOKEN)
8189 RETURNS BOOLEAN AS
8190$$
8191 SELECT cnt IS NULL OR provsql.get_gate_type(provsql.agg_token_uuid(cnt)) <> 'agg'
8192 OR NOT EXISTS (SELECT 1 FROM unnest(provsql.get_children(provsql.agg_token_uuid(cnt))) c
8193 WHERE provsql.get_gate_type(c) = 'semimod')
8194 OR EXISTS (SELECT 1
8195 FROM unnest(provsql.get_children(provsql.agg_token_uuid(cnt))) c
8196 WHERE provsql.get_gate_type(c) = 'semimod'
8197 AND provsql.get_extra((provsql.get_children(c))[2]) = '0')
8198$$ LANGUAGE sql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
8199
8200/**
8201 * @brief The event that the value of gate @p g is NULL, or is not (internal)
8202 *
8203 * An aggregate is NULL where none of the rows its gate holds is there (a row
8204 * whose value is NULL contributes nothing); arithmetic is NULL where one of
8205 * its operands is; a value, where it is NULL. See @c agg_token_null_event.
8206 *
8207 * @param g the gate
8208 * @param want_null true for IS NULL, false for IS NOT NULL
8209 */
8210CREATE OR REPLACE FUNCTION agg_gate_null_event(g UUID, want_null BOOLEAN)
8211 RETURNS UUID AS
8212$$
8213DECLARE
8214 t provsql.PROVENANCE_GATE;
8215 p UUID;
8216 parts UUID[];
8217 prev UUID[];
8218 ch UUID[];
8219 region UUID;
8220 arm UUID;
8221BEGIN
8222 t := provsql.get_gate_type(g);
8223 IF t = 'agg' THEN
8224 SELECT provsql.provenance_plus(coalesce(array_agg((provsql.get_children(c))[1]),
8225 ARRAY[]::UUID[]))
8226 INTO p
8227 FROM unnest(provsql.get_children(g)) AS c
8228 WHERE provsql.get_gate_type(c) = 'semimod';
8229 RETURN CASE WHEN want_null THEN provsql.provenance_monus(provsql.gate_one(), p)
8230 ELSE p END;
8231 ELSIF t = 'arith' THEN
8232 SELECT array_agg(provsql.agg_gate_null_event(c, want_null))
8233 INTO parts
8234 FROM unnest(provsql.get_children(g)) AS c;
8235 IF parts IS NULL THEN
8236 RETURN CASE WHEN want_null THEN provsql.gate_zero() ELSE provsql.gate_one() END;
8237 END IF;
8238 /* NULL where one operand is; not NULL where every one is not */
8239 RETURN CASE WHEN want_null THEN provsql.provenance_plus(parts)
8240 ELSE provsql.provenance_times(VARIADIC parts) END;
8241 ELSIF t = 'value' THEN
8242 RETURN CASE WHEN (coalesce(provsql.get_extra(g), '') IN ('', 'NULL')) = want_null
8243 THEN provsql.gate_one() ELSE provsql.gate_zero() END;
8244 ELSIF t = 'case' THEN
8245 /* A guarded selection, [guard_1, value_1, ..., default]: NULL (not NULL)
8246 * where the arm it selects is -- the arm's region, its guard and none of
8247 * the earlier ones (the default: none of them), times the arm's own
8248 * event. COALESCE(sum(x), 0) selects the sum where it has a value and 0
8249 * elsewhere, so is NULL nowhere. */
8250 parts := ARRAY[]::UUID[];
8251 prev := ARRAY[]::UUID[];
8252 ch := provsql.get_children(g);
8253 FOR i IN 1 .. coalesce(array_length(ch, 1), 0) BY 2 LOOP
8254 IF i = array_length(ch, 1) THEN
8255 region := CASE WHEN cardinality(prev) = 0 THEN provsql.gate_one()
8256 ELSE provsql.provenance_monus(provsql.gate_one(),
8257 provsql.provenance_plus(prev))
8258 END;
8259 arm := ch[i];
8260 ELSE
8261 region := CASE WHEN cardinality(prev) = 0 THEN ch[i]
8262 ELSE provsql.provenance_times(
8263 ch[i],
8264 provsql.provenance_monus(provsql.gate_one(),
8265 provsql.provenance_plus(prev)))
8266 END;
8267 arm := ch[i + 1];
8268 prev := prev || ch[i];
8269 END IF;
8270 parts := parts || provsql.provenance_times(
8271 region, provsql.agg_gate_null_event(arm, want_null));
8272 END LOOP;
8273 RETURN provsql.provenance_plus(parts);
8274 END IF;
8275 RAISE EXCEPTION USING
8276 MESSAGE = 'ProvSQL: IS [NOT] NULL on this expression over aggregates, read '
8277 'from a subquery, is not supported',
8278 DETAIL = 'provsql-reason: nulltest-not-aggregate; scope: gap',
8279 ERRCODE = 'feature_not_supported';
8280END
8281$$ LANGUAGE plpgsql STABLE PARALLEL SAFE SET search_path=provsql,pg_temp,public;
8282
8283/**
8284 * @brief The contributions of the distinct values of a window frame
8285 * (internal)
8286 *
8287 * Called by the query rewriter for <tt>dense_rank() OVER (…)</tt> over
8288 * provenance-tracked relations, which counts the distinct ordering values
8289 * before the current row: one <tt>provenance_semimod(1, ⊕ tokens)</tt> per
8290 * distinct value of @p vals, the ⊕ of the tokens of the rows that have it,
8291 * which is present when one of them is. Values are compared with the
8292 * equality of their type, as the peers of a window are, NULLs being equal.
8293 *
8294 * @param vals the ordering values of the rows of the frame
8295 * @param tokens the provenance tokens of these rows, in the same order
8296 */
8297CREATE OR REPLACE FUNCTION window_distinct_tokens(vals anyarray, tokens UUID[])
8298 RETURNS UUID[] AS
8299$$
8300 SELECT array_agg(s ORDER BY s)
8301 FROM (SELECT provsql.provenance_semimod(1, provsql.provenance_plus(array_agg(tokens[i]))) AS s
8302 FROM generate_subscripts(vals, 1) AS i GROUP BY vals[i]) g
8303$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
8304
8305/**
8306 * @brief Mark a part of a query to be evaluated as plain SQL, not tracked
8307 *
8308 * Over provenance-tracked relations, <tt>ORDER BY … LIMIT k</tt> keeps, in
8309 * each possible world, the rows that fewer than @p k present rows precede:
8310 * every row that may be among them is output, annotated with that condition.
8311 * <tt>LIMIT plain(k)</tt> (<tt>FETCH FIRST plain(k) ROWS</tt>,
8312 * <tt>OFFSET plain(m)</tt>) instead truncates the result as computed on the
8313 * actual data, and each row kept carries its provenance in the full result.
8314 * The function returns its argument.
8315 *
8316 * @param value the marked value
8317 */
8318CREATE OR REPLACE FUNCTION plain(value ANYELEMENT)
8319 RETURNS ANYELEMENT AS
8320$$ SELECT value $$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
8321
8322/** @} */
8323
8324/** @defgroup probability Probability and Shapley values
8325 * Functions for computing probabilities, expected values, and
8326 * game-theoretic contribution measures (Shapley/Banzhaf values)
8327 * from provenance circuits.
8328 * @{
8329 */
8330
8331/**
8332 * @brief Compute the probability of a provenance token
8333 *
8334 * Compiles the provenance circuit to d-DNNF and evaluates the
8335 * probability. The compilation method can be selected explicitly.
8336 *
8337 * @ref probability() "probability" is a shorter alias bound to the same C symbol, so
8338 * @c probability(token) is exactly @c probability_evaluate(token); it is
8339 * usually preferable, and additionally carries a @c (BOOLEAN) predicate
8340 * overload (e.g. @c probability(x @c > @c y)).
8341 *
8342 * @param token provenance token to evaluate
8343 * @param method knowledge compilation method (NULL for default)
8344 * @param arguments additional arguments for the method
8345 */
8346CREATE OR REPLACE FUNCTION probability_evaluate(
8347 token UUID,
8348 method TEXT = NULL,
8349 arguments TEXT = NULL)
8350 RETURNS DOUBLE PRECISION AS
8351 'provsql','probability_evaluate' LANGUAGE C VOLATILE PARALLEL UNSAFE;
8352
8353/**
8354 * @brief Short alias of @ref probability_evaluate.
8355 *
8356 * Bound to the same C symbol as @ref probability_evaluate, so
8357 * @c probability(token) is exactly @c probability_evaluate(token).
8358 * Provided to match the concise polymorphic surface of @ref expected,
8359 * @ref variance, and @ref support "support": callers are not forced to
8360 * spell out @c probability_evaluate.
8361 *
8362 * @param token provenance token to evaluate
8363 * @param method knowledge compilation method (NULL for default)
8364 * @param arguments additional arguments for the method
8365 */
8366CREATE OR REPLACE FUNCTION probability(
8367 token UUID,
8368 method TEXT = NULL,
8369 arguments TEXT = NULL)
8370 RETURNS DOUBLE PRECISION AS
8371 'provsql','probability_evaluate' LANGUAGE C VOLATILE PARALLEL UNSAFE;
8372
8373/**
8374 * @brief Probability of a Boolean event over random variables.
8375 *
8376 * The @c (BOOLEAN) overload of @c probability lets a query ask for the
8377 * probability of an event with the natural infix grammar, e.g.
8378 * @c probability(x @c > @c y @c AND @c x @c < @c z). When the argument
8379 * carries a probabilistic (random_variable / aggregate) comparison, the
8380 * planner hook intercepts the call and rewrites it into
8381 * @c probability_evaluate over the argument's event token (a @c gate_cmp /
8382 * Boolean combination); the body below is then never reached.
8383 *
8384 * When the argument is a purely deterministic Boolean (no probabilistic
8385 * comparison) the hook leaves the call alone and the body runs, so the
8386 * probability of a definite event is simply @c 1 when it holds and @c 0 when
8387 * it does not (@c NULL propagates). This makes @c probability total over
8388 * Booleans -- @c probability(1 @c > @c 0) is @c 1, @c probability(region @c =
8389 * @c 'north') is a per-row @c 0/1 -- and it works even with
8390 * @c provsql.active off. @c NOT strict so a default-NULL @c method does not
8391 * short-circuit the cast.
8392 *
8393 * The predicate surface deliberately lives only on the short @c probability
8394 * name, not on @c probability_evaluate: a Boolean overload of the latter
8395 * would make @c probability_evaluate('<UUID-as-TEXT>') ambiguous (an unknown
8396 * literal matches both the @c UUID and the @c BOOLEAN overload), breaking
8397 * existing string-literal callers. @c probability is new, so it carries the
8398 * predicate overload without that hazard.
8399 */
8400CREATE OR REPLACE FUNCTION probability(
8401 predicate BOOLEAN,
8402 method TEXT = NULL,
8403 arguments TEXT = NULL)
8404 RETURNS DOUBLE PRECISION AS
8405$$
8406 SELECT predicate::INTEGER::double precision;
8407$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE;
8408
8409/**
8410 * @brief Cheap certified probability interval of a DNF-shaped circuit.
8411 *
8412 * Returns @c [lower,upper] with @c lower <= probability_evaluate(token) <=
8413 * @c upper, computed without compiling the circuit (the Olteanu-Huang d-tree
8414 * leaf bound). Errors when @p token is not a monotone DNF over input leaves.
8415 */
8416CREATE OR REPLACE FUNCTION probability_bounds(
8417 token UUID,
8418 OUT lower DOUBLE PRECISION,
8419 OUT upper DOUBLE PRECISION) AS
8420 'provsql','probability_bounds' LANGUAGE C STABLE;
8421
8422/**
8423 * @brief Compute the expected value of a probabilistic scalar
8424 *
8425 * Computes E[input | prov] for either an @c AGG_TOKEN (discrete
8426 * SUM/MIN/MAX aggregation over Boolean-input gate_agg circuits, with
8427 * @c prov as the Boolean conditioning event) or a @c random_variable
8428 * (continuous distribution, traversed by the analytical / MC
8429 * evaluator from @c Expectation.cpp).
8430 *
8431 * Implementation: thin wrapper over @c moment(input, 1, prov, method,
8432 * arguments). Both branches converge on the same machinery; the
8433 * AGG_TOKEN side computes E[X] as the @f$k=1@f$ instance of the
8434 * @f$n^k@f$-tuple enumeration in @c agg_raw_moment, the
8435 * random_variable side calls @c compute_expectation through
8436 * @c rv_moment.
8437 *
8438 * @param input aggregate expression or random variable to compute E[·] of
8439 * @param prov provenance condition (defaults to gate_one(), i.e., unconditional)
8440 * @param method knowledge compilation method (AGG_TOKEN path only)
8441 * @param arguments additional arguments for the method (AGG_TOKEN path only)
8442 */
8443CREATE OR REPLACE FUNCTION expected(
8444 input ANYELEMENT,
8445 prov UUID = gate_one(),
8446 method TEXT = NULL,
8447 arguments TEXT = NULL)
8448 RETURNS DOUBLE PRECISION AS $$
8449 SELECT moment(input, 1, prov, method, arguments);
8450$$ LANGUAGE sql PARALLEL UNSAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
8451
8452/**
8453 * @brief Internal: shared C entry point for variance / moment / central_moment.
8454 *
8455 * The @c expected() SQL function reaches the Expectation evaluator
8456 * through @c provenance_evaluate_compiled(..., 'expectation', ...).
8457 * The variance / raw-moment / central-moment SQL functions need an
8458 * extra @p k INTEGER argument that does not fit that dispatcher's
8459 * signature, so they go through this dedicated entry point. Returns
8460 * E[X^k] when @p central is FALSE, or E[(X - E[X])^k] when TRUE; NULL
8461 * when the value is defined in no world.
8462 */
8463CREATE OR REPLACE FUNCTION rv_moment(
8464 token UUID, k INTEGER, central BOOLEAN,
8465 prov UUID DEFAULT gate_one())
8466 RETURNS double precision
8467 AS 'provsql','rv_moment' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
8468
8469/** @brief Exact E[AVG^k | COUNT >= 1] over independent rows (the joint
8470 * (sum, count) fold); NULL when the shape is out of scope (shared
8471 * leaves, compound contributors), signalling @c agg_raw_moment's avg
8472 * arm to fall back to the Monte-Carlo scalar path. */
8473CREATE OR REPLACE FUNCTION agg_avg_moment_exact(token UUID, k INTEGER)
8474 RETURNS double precision
8475 AS 'provsql','agg_avg_moment_exact' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
8476
8477/** @brief Collapsed (Rao-Blackwellised) raw moment E[C^k] of a correlated
8478 * COUNT / SUM whose per-row selection events are coupled through a single
8479 * shared continuous latent: 1-D quadrature over the latent, closed-form
8480 * per-row CDF given it (O(G·n), exact up to the grid). NULL when the
8481 * circuit does not match the shared-latent pattern (caller falls back to
8482 * the exact n^k enumeration). k in {1, 2}. */
8483CREATE OR REPLACE FUNCTION agg_collapsed_moment(token UUID, k INTEGER)
8484 RETURNS double precision
8485 AS 'provsql','agg_collapsed_moment' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
8486
8487/** @brief Both collapsed raw moments {E[C], E[C^2]} of a correlated COUNT / SUM
8488 * from a single circuit load and plan build; NULL when the shared-latent
8489 * pattern does not match. @c variance() uses this so a mean+variance readout
8490 * traverses the circuit once rather than calling @c agg_collapsed_moment twice
8491 * (the load and O(n) plan build dominate once the grid loop is arithmetic). */
8492CREATE OR REPLACE FUNCTION agg_collapsed_moments(token UUID)
8493 RETURNS double precision[]
8494 AS 'provsql','agg_collapsed_moments' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
8495
8496/** @brief For each contribution of an aggregation, in the order of its
8497 * children, the number of its independence component: contributions reaching
8498 * a common source of randomness (an input, a block of a multivalued input, a
8499 * random-variable leaf or the parameters of a latent one) share one, and
8500 * contributions of different components are independent. NULL for a gate
8501 * that is no aggregation (internal, used by agg_raw_moment). */
8502CREATE OR REPLACE FUNCTION agg_row_components(token UUID)
8503 RETURNS INTEGER[]
8504 AS 'provsql','agg_row_components' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
8505
8506/**
8507 * @brief Boolean event "this aggregate-carrying gate's value is defined
8508 * (non-NULL) in the world".
8509 *
8510 * Backs the conditional-on-defined convention of the aggregate moment
8511 * readouts: a scalar @c count (no @c GROUP BY) and constants have a value
8512 * in every world -- a scalar count over no row is the real value @c 0 --
8513 * so their defined event is @c gate_one(); every other aggregate (a
8514 * @c sum over no row is SQL @c NULL, a grouped one has no row at all) is
8515 * defined only where "some contributing row is present", the OR of the
8516 * semimod children's row tokens; a @c case gate's value is defined iff its first-match
8517 * selected branch's value is (the same region walk as the moment
8518 * evaluator, conjoined per branch). Anything else (an @c arith
8519 * composite, whose AGG_TOKEN running value is total) counts as always
8520 * defined.
8521 */
8522CREATE OR REPLACE FUNCTION agg_defined_event(token UUID)
8523 RETURNS UUID AS $$
8524DECLARE
8525 gt PROVENANCE_GATE := get_gate_type(token);
8526 fname varchar;
8527 toks UUID[];
8528 wires UUID[];
8529 nw INTEGER;
8530 m INTEGER;
8531 i INTEGER;
8532 running_neg UUID := gate_one();
8533 parts UUID[] := '{}';
8534BEGIN
8535 IF token = gate_null() THEN
8536 RETURN gate_zero(); -- the NULL value: never defined
8537 END IF;
8538 IF gt = 'agg' THEN
8539 SELECT proname INTO fname
8540 FROM pg_proc WHERE oid = (get_infos(token)).info1;
8541 -- A scalar COUNT has a row in every world, counting a real 0 over none;
8542 -- every other aggregate (a SUM over no row is SQL NULL, a grouped one has
8543 -- no row at all) is defined only where a contributing row is.
8544 IF fname = 'count' AND (get_infos(token)).info2 < 0 THEN
8545 RETURN gate_one();
8546 END IF;
8547 SELECT array_agg((get_children(c))[1]) INTO toks
8548 FROM unnest(get_children(token)) AS c;
8549 IF toks IS NULL THEN
8550 RETURN gate_zero(); -- structurally empty aggregate: never defined
8551 END IF;
8552 RETURN provenance_plus(toks);
8553 ELSIF gt = 'case' THEN
8554 wires := get_children(token);
8555 nw := array_length(wires, 1);
8556 m := (nw - 1) / 2;
8557 FOR i IN 1..m LOOP
8558 parts := parts || provenance_times(
8559 running_neg, wires[2 * i - 1],
8560 agg_defined_event(wires[2 * i]));
8561 running_neg := provenance_times(running_neg,
8562 provenance_not(wires[2 * i - 1]));
8563 END LOOP;
8564 parts := parts || provenance_times(running_neg,
8565 agg_defined_event(wires[nw]));
8566 RETURN provenance_plus(parts);
8567 ELSIF gt = 'arith' THEN
8568 -- Arithmetic is STRICT: a value exists where every operand's does. Saying
8569 -- gate_one here made a var_pop moment count the world where the group has
8570 -- no row. Its CASE guards a count against 0 and against 1, and a
8571 -- comparison over an aggregate that has no value holds in no world, so in
8572 -- the empty world neither guard fires and the FORMULA arm is the one
8573 -- selected -- an arith over the sums, whose operands have no value there.
8574 -- Declared defined, that world was counted, and expected(var_pop(x)) came
8575 -- out NaN for a one-row group whose value is 0 wherever it exists.
8576 SELECT array_agg(agg_defined_event(c)) INTO parts
8577 FROM unnest(get_children(token)) AS c;
8578 IF parts IS NULL OR array_length(parts, 1) IS NULL THEN
8579 RETURN gate_one();
8580 END IF;
8581 RETURN provenance_times(VARIADIC parts);
8582 END IF;
8583 -- value / anything else: a value exists in every world (gate_null, the one
8584 -- value that never does, is answered at the top).
8585 RETURN gate_one();
8586END
8587$$ LANGUAGE plpgsql STABLE STRICT PARALLEL SAFE
8588 SET search_path=provsql,pg_temp,public SECURITY DEFINER;
8589
8590/**
8591 * @brief Compute the raw moment E[X^k | prov] of an AGG_TOKEN aggregate
8592 *
8593 * Sister of @c expected() for the AGG_TOKEN side of the polymorphic
8594 * @c moment / @c variance / @c central_moment dispatch. Supports the
8595 * same aggregation functions as @c expected: SUM (which COUNT
8596 * normalises to at the gate level via @c Aggregation.cpp:322), MIN,
8597 * MAX, and AVG (exact over independent / laminar rows via the joint
8598 * (sum, count) distribution, Monte-Carlo scalar fallback otherwise).
8599 * MIN / MAX / AVG are NULL on an empty group, so their moments are
8600 * CONDITIONAL on the aggregate being defined -- NULL only when it never
8601 * is; SUM / COUNT treat the empty world as the real value 0.
8602 *
8603 * Strategy:
8604 * - <b>SUM</b>: with X = Σᵢ Iᵢ·vᵢ (Iᵢ the per-row inclusion indicator,
8605 * vᵢ the row's value), expanding X^k and taking expectation gives
8606 * @f$E[X^k] = \sum_{(i_1,\ldots,i_k) \in \{1..n\}^k} v_{i_1}\cdots v_{i_k}
8607 * \cdot P(\bigwedge_{i \in \TEXT{distinct}(i_1..i_k)} I_i)@f$.
8608 * We enumerate the @f$n^k@f$ tuples, conjoin the distinct inclusion
8609 * tokens (and @p prov when conditioning), and evaluate the
8610 * probability via @c probability_evaluate.
8611 * - <b>MIN / MAX</b>: replace @c v with @c v^k in the rank-based
8612 * enumeration that @c expected already uses; @c MAX is handled by
8613 * sign-flipping per the existing trick (negate vs. rerank), with
8614 * the outer multiplier becoming @f$(-1)^k@f$ instead of just @f$-1@f$.
8615 *
8616 * Cost: SUM is @f$O(n^k)@f$ probability evaluations -- tractable for
8617 * small @p k or small @p n; for larger sizes, prefer reaching for the
8618 * sampler. MIN / MAX stay linear in @p n.
8619 */
8620CREATE OR REPLACE FUNCTION agg_raw_moment(
8621 token AGG_TOKEN,
8622 k INTEGER,
8623 prov UUID = gate_one(),
8624 method TEXT = NULL,
8625 arguments TEXT = NULL)
8626 RETURNS DOUBLE PRECISION AS $$
8627DECLARE
8628 aggregation_function VARCHAR;
8629 child_pairs UUID[];
8630 pair_children UUID[];
8631 n INTEGER;
8632 i INTEGER;
8633 j INTEGER;
8634 vals float8[];
8635 toks UUID[];
8636 total float8;
8637 total_probability float8;
8638 tup INTEGER[];
8639 d INTEGER;
8640 prod_v float8;
8641 distinct_tok UUID[];
8642 conj_token UUID;
8643 prob float8;
8644 sign_max float8;
8645 is_scalar BOOLEAN;
8646 defined_tok UUID;
8647BEGIN
8648 IF token IS NULL OR k IS NULL THEN
8649 RETURN NULL;
8650 END IF;
8651 IF k < 0 THEN
8652 RAISE EXCEPTION 'agg_raw_moment(): k must be non-negative (got %)', k;
8653 END IF;
8654
8655 -- Aggregate-carrier CASE (a gate_case over aggregate branches): a first-match
8656 -- guarded selection. The moment is CONDITIONAL on the CASE's value being
8657 -- defined (NULL only when it never is, mirroring the MIN/MAX convention):
8658 -- E[pick^k | defined ∧ prov]
8659 -- = Σ_i P(region_i ∧ def_i) · E[value_i^k | region_i ∧ def_i]
8660 -- / Σ_i P(region_i ∧ def_i),
8661 -- where region_i = (¬g_1 ∧ … ∧ ¬g_{i-1}) ∧ g_i ∧ prov is the world set that
8662 -- selects branch i (the default's region is "all guards false") and def_i is
8663 -- the branch's defined event (agg_defined_event: gate_one for sum / count /
8664 -- constants, "some row present" for min / max / avg, recursive for a nested
8665 -- CASE). Both factors are exact: probability() over the region ∧ def event,
8666 -- and the conditional aggregate moment (a recursive agg_raw_moment on the
8667 -- branch aggregate, which conditions on its own definedness within the
8668 -- region, so the two factors weigh the same worlds). The regions are
8669 -- mutually exclusive, so the terms sum with no inclusion-exclusion, and
8670 -- correlation between a guard and its branch (shared input tuples) is
8671 -- carried by the conditioning, exactly as HAVING carries it. When every
8672 -- branch is defined everywhere, the defined mass equals P(prov) and the
8673 -- formula reduces to the plain region-weighted sum.
8674 IF get_gate_type(token) = 'case' THEN
8675 IF k = 0 THEN
8676 RETURN 1;
8677 END IF;
8678 DECLARE
8679 wires UUID[] := get_children(token);
8680 nw INTEGER := array_length(get_children(token), 1);
8681 m INTEGER := (array_length(get_children(token), 1) - 1) / 2;
8682 running_neg UUID := gate_one();
8683 region_full UUID;
8684 prov_p float8;
8685 p float8;
8686 total float8 := 0;
8687 def_mass float8 := 0;
8688 ci INTEGER;
8689 vuid UUID;
8690 bm float8;
8691 BEGIN
8692 prov_p := probability(prov);
8693 IF prov_p IS NULL OR prov_p <= 0 THEN
8694 RETURN NULL; -- impossible conditioning event
8695 END IF;
8696 -- Branches 1..m are the guarded WHENs; branch m+1 is the ELSE default,
8697 -- whose region is "all guards false".
8698 FOR ci IN 1 .. m + 1 LOOP
8699 IF ci <= m THEN
8700 region_full := provenance_times(running_neg, wires[2 * ci - 1], prov);
8701 vuid := wires[2 * ci];
8702 running_neg :=
8703 provenance_times(running_neg, provenance_not(wires[2 * ci - 1]));
8704 ELSE
8705 region_full := provenance_times(running_neg, prov);
8706 vuid := wires[nw];
8707 END IF;
8708 p := probability(provenance_times(region_full,
8709 agg_defined_event(vuid)));
8710 IF p > 0 THEN
8711 -- E[value_i^k | region_i ∧ def_i]: a constant branch is a Dirac
8712 -- (c^k, exact); a single aggregate or nested CASE is exact via
8713 -- agg_raw_moment (whose MIN/MAX/CASE arms condition on their own
8714 -- definedness within the region); an arithmetic / composite branch
8715 -- takes the Monte-Carlo scalar path (which composes with the
8716 -- aggregate leaves).
8717 IF get_gate_type(vuid) = 'value' THEN
8718 bm := power(CAST(get_extra(vuid) AS float8), k);
8719 ELSIF get_gate_type(vuid) IN ('agg', 'case') THEN
8720 bm := agg_raw_moment(agg_token_make(vuid, 0), k, region_full,
8721 method, arguments);
8722 ELSE
8723 bm := rv_moment(vuid, k, false, region_full);
8724 END IF;
8725 total := total + p * bm;
8726 def_mass := def_mass + p;
8727 END IF;
8728 END LOOP;
8729 IF def_mass <= 0 THEN
8730 RETURN NULL; -- the CASE's value is never defined under prov
8731 END IF;
8732 RETURN total / def_mass;
8733 END;
8734 END IF;
8735
8736 IF get_gate_type(token) <> 'agg' THEN
8737 IF get_gate_type(token) IN ('arith', 'conditioned') THEN
8738 -- An arithmetic combination of aggregates (SUM(x) + SUM(y), SUM(x) / 2),
8739 -- or a conditioning of one: the scalar evaluator, exact over the
8740 -- possible worlds of few inputs, sampled otherwise
8741 RETURN rv_moment((token)::UUID, k, false, prov);
8742 ELSE
8743 RAISE EXCEPTION USING MESSAGE='Wrong gate type for agg_raw_moment computation',
8744 DETAIL = 'provsql-reason: moment-not-an-aggregate; scope: deliberate';
8745 END IF;
8746 END IF;
8747 IF k = 0 THEN
8748 RETURN 1;
8749 END IF;
8750
8751 SELECT pp.proname::varchar FROM pg_proc pp
8752 WHERE oid=(get_infos(token)).info1
8753 INTO aggregation_function;
8754
8755 child_pairs := get_children(token);
8756 n := COALESCE(array_length(child_pairs, 1), 0);
8757
8758 -- A contribution whose value is itself an aggregate (an avg of a count, a
8759 -- max of a sum, an aggregate of an arithmetic expression over aggregates:
8760 -- provenance_semimod_nested) takes one value per possible world, not a
8761 -- constant read off its gate, so none of the closed forms below applies to
8762 -- it. The scalar evaluator reads such a value in every world.
8763 IF EXISTS (SELECT 1 FROM unnest(child_pairs) AS c
8764 WHERE get_gate_type((get_children(c))[2]) <> 'value') THEN
8765 RETURN rv_moment((token)::UUID, k, false, prov);
8766 END IF;
8767
8768 IF aggregation_function = 'sum' OR aggregation_function = 'count' THEN
8769 -- count(*) and count(col) both keep the COUNT identity at the gate level,
8770 -- their value being the SUM of per-row 1 / 0-or-1 indicators, so their
8771 -- moments are computed exactly like SUM.
8772 --
8773 -- The value exists only where a contributing row does: SUM over no row is
8774 -- SQL NULL, and a grouped aggregation has no row there at all. So the
8775 -- moment conditions on that event, as the MIN / MAX arms do, and
8776 -- @c expected(sum(x)) of a group equals @c expected(sum(x), provenance()).
8777 -- A scalar COUNT is the exception: its row is always there and counts a
8778 -- real 0 over no row.
8779 is_scalar := (get_infos(token)).info2 < 0; -- the scalar flag, high bit
8780
8781 -- Extract per-child token + value arrays.
8782 vals := ARRAY[]::float8[];
8783 toks := ARRAY[]::UUID[];
8784 FOR i IN 1..n LOOP
8785 pair_children := get_children(child_pairs[i]);
8786 toks := toks || pair_children[1];
8787 vals := vals || CAST(get_extra(pair_children[2]) AS float8);
8788 END LOOP;
8789 defined_tok := CASE
8790 WHEN aggregation_function = 'count' AND is_scalar THEN gate_one()
8791 WHEN n = 0 THEN gate_zero()
8792 ELSE provenance_plus(toks) END;
8793
8794 IF n = 0 THEN
8795 -- No contributing row at all: a real 0 for a scalar COUNT, SQL NULL
8796 -- (never defined) otherwise.
8797 RETURN CASE WHEN defined_tok = gate_one() THEN 0 ELSE NULL END;
8798 END IF;
8799
8800 -- Collapsed fast path: a correlated COUNT / SUM whose per-row selection
8801 -- events share a single continuous latent has an O(G·n) 1-D quadrature,
8802 -- vastly cheaper than the O(n^k) tuple enumeration below (which is the
8803 -- O(n^2) pair-probability bottleneck for the variance). Only fires
8804 -- unconditionally (prov = one) and for k in {1, 2}; agg_collapsed_moment
8805 -- returns NULL when the shared-latent pattern does not match, and we
8806 -- fall through to the exact enumeration. Its moment counts the worlds
8807 -- without a row as 0, which contribute nothing, so it only needs the
8808 -- conditional normalisation below.
8809 IF prov = gate_one() AND k <= 2 THEN
8810 total := agg_collapsed_moment((token)::UUID, k);
8811 IF total IS NOT NULL THEN
8812 IF defined_tok = gate_one() THEN
8813 RETURN total;
8814 END IF;
8815 prob := probability_evaluate(defined_tok, method, arguments);
8816 IF prob IS NULL OR prob <= 0 THEN
8817 RETURN NULL;
8818 END IF;
8819 RETURN total / prob;
8820 END IF;
8821 END IF;
8822
8823 -- Independent rows: the first two moments from one probability per row.
8824 -- Rows of different independence components (agg_row_components: no
8825 -- source of randomness in common) are independent, so a pair of them is
8826 -- present with the product of their probabilities, and
8827 -- E[S] = sum_i v_i p_i,
8828 -- E[S^2] = sum_i v_i^2 p_i + (sum_i v_i p_i)^2 - sum_c (sum_{i in c} v_i p_i)^2
8829 -- + sum_{i <> j in one component} v_i v_j P(t_i and t_j):
8830 -- n probability evaluations, plus one per pair within a component,
8831 -- instead of one per pair -- n^2, each a Monte Carlo estimate when the
8832 -- rows' events compare random variables. Unconditional only (an outer
8833 -- event couples the rows).
8834 IF prov = gate_one() AND k <= 2 THEN
8835 DECLARE
8836 comp INTEGER[] := agg_row_components((token)::UUID);
8837 p float8[] := ARRAY[]::float8[];
8838 s1 float8 := 0;
8839 sc float8[];
8840 ncomp INTEGER;
8841 pair_tok UUID[];
8842 BEGIN
8843 FOR i IN 1..n LOOP
8844 p := p || probability_evaluate(toks[i], method, arguments);
8845 s1 := s1 + vals[i] * p[i];
8846 END LOOP;
8847 IF k = 1 THEN
8848 total := s1;
8849 ELSE
8850 ncomp := (SELECT max(c) FROM unnest(comp) AS c);
8851 sc := array_fill(0::float8, ARRAY[ncomp]);
8852 total := 0;
8853 FOR i IN 1..n LOOP
8854 total := total + vals[i] * vals[i] * p[i];
8855 sc[comp[i]] := sc[comp[i]] + vals[i] * p[i];
8856 END LOOP;
8857 total := total + s1 * s1;
8858 FOR i IN 1..ncomp LOOP
8859 total := total - sc[i] * sc[i];
8860 END LOOP;
8861 FOR i IN 1..n LOOP
8862 FOR j IN 1..n LOOP
8863 CONTINUE WHEN i = j OR comp[i] <> comp[j];
8864 pair_tok := ARRAY(SELECT DISTINCT unnest(ARRAY[toks[i], toks[j]]));
8865 total := total + vals[i] * vals[j] * CASE
8866 WHEN array_length(pair_tok, 1) = 1 THEN p[i]
8867 ELSE probability_evaluate(provenance_times(VARIADIC pair_tok),
8868 method, arguments) END;
8869 END LOOP;
8870 END LOOP;
8871 END IF;
8872 IF defined_tok = gate_one() THEN
8873 RETURN total;
8874 END IF;
8875 prob := probability_evaluate(defined_tok, method, arguments);
8876 IF prob IS NULL OR prob <= 0 THEN
8877 RETURN NULL; -- never defined: SQL NULL
8878 END IF;
8879 RETURN total / prob;
8880 END;
8881 END IF;
8882 -- Enumerate all k-tuples (i_1, ..., i_k) in {1..n}^k. tup is the
8883 -- current tuple; we step through them in lexicographic order.
8884 total := 0;
8885 tup := array_fill(1, ARRAY[k]);
8886 LOOP
8887 prod_v := 1;
8888 FOR j IN 1..k LOOP
8889 prod_v := prod_v * vals[tup[j]];
8890 END LOOP;
8891
8892 SELECT array_agg(DISTINCT toks[idx]) INTO distinct_tok
8893 FROM unnest(tup) AS idx;
8894
8895 IF prov <> gate_one() THEN
8896 distinct_tok := distinct_tok || prov;
8897 END IF;
8898 conj_token := provenance_times(VARIADIC distinct_tok);
8899 prob := probability_evaluate(conj_token, method, arguments);
8900
8901 total := total + prod_v * prob;
8902
8903 d := k;
8904 WHILE d >= 1 AND tup[d] = n LOOP
8905 tup[d] := 1;
8906 d := d - 1;
8907 END LOOP;
8908 EXIT WHEN d = 0;
8909 tup[d] := tup[d] + 1;
8910 END LOOP;
8911
8912 -- Conditional on the value existing (and on prov): every k-tuple of the
8913 -- sum above names a row, so the worlds without one contribute 0 and only
8914 -- the normalisation is left.
8915 IF defined_tok <> gate_one() THEN
8916 IF prov <> gate_one() THEN
8917 defined_tok := provenance_times(prov, defined_tok);
8918 END IF;
8919 prob := probability_evaluate(defined_tok, method, arguments);
8920 IF prob IS NULL OR prob <= 0 THEN
8921 RETURN NULL; -- never defined: SQL NULL
8922 END IF;
8923 RETURN total / prob; -- already conditional; skip the generic norm
8924 END IF;
8925 ELSIF aggregation_function = 'min' OR aggregation_function = 'max' THEN
8926 -- Rank enumeration: per distinct value v, P(MIN = v) is the
8927 -- probability that some t_i with v_i=v is true and all t_j with
8928 -- smaller v are false. For MAX we negate values so the same
8929 -- "smaller-than" rank logic computes MIN-of-negated, then flip.
8930 -- The outer multiplier picks up the right sign for the k-th moment
8931 -- of MAX: E[MAX^k] = (-1)^k * E[MIN(-v)^k], so sign_max = (-1)^k.
8932 sign_max := CASE
8933 WHEN aggregation_function = 'max'
8934 THEN power(-1::float8, k)
8935 ELSE 1
8936 END;
8937
8938 -- MIN/MAX over the empty input world are NULL (no elements), not ±Infinity:
8939 -- SQL returns one row with a NULL value. The moment is therefore CONDITIONAL
8940 -- on the aggregate being defined (non-empty) -- the empty world is excluded
8941 -- and the result renormalised by P(prov AND non-empty). (count, whose empty
8942 -- value 0 is a real value, keeps the empty world; sum keeps it too, as 0.)
8943 IF n = 0 THEN
8944 RETURN NULL; -- structurally empty: MIN/MAX undefined
8945 END IF;
8946
8947 -- Numerator E[MIN^k . 1{prov AND non-empty}] (the rank sum naturally omits
8948 -- the empty world, since every term requires a present token).
8949 WITH tok_value AS (
8950 SELECT (get_children(c))[1] AS tok,
8951 (CASE WHEN aggregation_function='max' THEN -1 ELSE 1 END)
8952 * CAST(get_extra((get_children(c))[2]) AS DOUBLE PRECISION) AS v
8953 FROM UNNEST(child_pairs) AS c
8954 ) SELECT sign_max * COALESCE(SUM(p * power(v, k)), 0) FROM (
8955 SELECT t1.v AS v,
8956 probability_evaluate(
8957 CASE WHEN prov = gate_one()
8958 THEN provenance_monus(provenance_plus(ARRAY_AGG(t1.tok)),
8959 provenance_plus(ARRAY_AGG(t2.tok)))
8960 ELSE provenance_times(prov,
8961 provenance_monus(provenance_plus(ARRAY_AGG(t1.tok)),
8962 provenance_plus(ARRAY_AGG(t2.tok)))) END,
8963 method, arguments) AS p
8964 FROM tok_value t1 LEFT OUTER JOIN tok_value t2 ON t1.v > t2.v
8965 GROUP BY t1.v) tmp
8966 INTO total;
8967
8968 -- Denominator P(prov AND non-empty) = P(prov (x) (+) tokens).
8969 SELECT probability_evaluate(
8970 CASE WHEN prov = gate_one()
8971 THEN provenance_plus(ARRAY_AGG(tok))
8972 ELSE provenance_times(prov, provenance_plus(ARRAY_AGG(tok))) END,
8973 method, arguments)
8974 FROM (SELECT (get_children(c))[1] AS tok FROM UNNEST(child_pairs) AS c) s
8975 INTO total_probability;
8976
8977 IF total_probability <= 0 THEN
8978 RETURN NULL; -- never defined under prov: MIN/MAX undefined
8979 END IF;
8980 RETURN total / total_probability; -- already conditional; skip generic norm
8981 ELSIF aggregation_function = 'avg' THEN
8982 -- AVG = SUM/COUNT is a ratio of two correlated world-dependent
8983 -- quantities, so the k-tuple expansion above does not apply. Like
8984 -- MIN/MAX, AVG over the empty world is NULL, so its moment conditions
8985 -- on the aggregate being defined (COUNT >= 1), NULL when it never is.
8986 -- Two routes:
8987 -- * EXACT (independent rows, unconditional): the joint (sum, count)
8988 -- PMF folded in C by agg_avg_moment_exact --
8989 -- E[AVG^k | COUNT>=1] = Σ_{(s,c), c>=1} (s/c)^k pmf(s,c) / P(c>=1).
8990 -- * Monte-Carlo scalar fallback otherwise (an outer conditioning
8991 -- event, shared leaves, compound contributors): rv_moment samples
8992 -- the agg gate per world; its NaN-skip on empty draws implements
8993 -- the same conditional-on-defined convention, at the
8994 -- provsql.rv_mc_samples budget (0 raises, per convention).
8995 IF n = 0 THEN
8996 RETURN NULL; -- structurally empty: AVG undefined
8997 END IF;
8998 -- Conditioning on an event that AVG being defined implies -- some row
8999 -- among a set holding AVG's rows present, as provenance() of a GROUP BY
9000 -- row is, the group possibly having rows whose value is NULL -- is what
9001 -- the moment already does: the exact route applies.
9002 IF prov <> gate_one() THEN
9003 DECLARE
9004 inner_prov UUID := prov;
9005 prov_toks UUID[];
9006 agg_toks UUID[];
9007 BEGIN
9008 IF get_gate_type(inner_prov) = 'delta' THEN
9009 inner_prov := (get_children(inner_prov))[1];
9010 END IF;
9011 IF get_gate_type(inner_prov) = 'plus' THEN
9012 prov_toks := get_children(inner_prov);
9013 ELSE
9014 prov_toks := ARRAY[inner_prov];
9015 END IF;
9016 SELECT array_agg((get_children(c))[1]) INTO agg_toks
9017 FROM unnest(child_pairs) AS c;
9018 IF agg_toks <@ prov_toks THEN
9019 prov := gate_one();
9020 END IF;
9021 END;
9022 END IF;
9023 IF prov = gate_one() THEN
9024 total := agg_avg_moment_exact((token)::UUID, k);
9025 IF total IS NOT NULL THEN
9026 RETURN total;
9027 END IF;
9028 END IF;
9029 RETURN rv_moment((token)::UUID, k, false, prov);
9030 ELSE
9031 RAISE EXCEPTION USING MESSAGE=
9032 'Cannot compute moment for aggregation function ' || aggregation_function,
9033 DETAIL = 'provsql-reason: moment-aggregate-kind; scope: gap';
9034 END IF;
9035
9036 -- Conditional normalisation: E[X^k · 1_A] / P(A) = E[X^k | A].
9037 IF prov <> gate_one()
9038 AND total <> 0
9039 AND total <> 'Infinity'::float8
9040 AND total <> '-Infinity'::float8 THEN
9041 total := total / probability_evaluate(prov, method, arguments);
9042 END IF;
9043
9044 RETURN total;
9045END
9046$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE SET search_path=provsql SECURITY DEFINER;
9047
9048/**
9049 * @brief Compute the variance Var[X | prov] of a probabilistic scalar
9050 *
9051 * Polymorphic dispatcher that mirrors @c expected: @c random_variable
9052 * inputs go through the analytical / MC evaluator
9053 * (@c rv_moment(UUID, 2, true)); @c AGG_TOKEN inputs go through the
9054 * @c agg_raw_moment helper, computing
9055 * @f$\mathrm{Var}[X|A] = E[X^2|A] - E[X|A]^2@f$. Conditioning on
9056 * @c prov is supported for @c AGG_TOKEN (matching @c expected) but
9057 * not yet for @c random_variable.
9058 */
9059CREATE OR REPLACE FUNCTION variance(
9060 input ANYELEMENT,
9061 prov UUID = gate_one(),
9062 method TEXT = NULL,
9063 arguments TEXT = NULL)
9064 RETURNS DOUBLE PRECISION AS $$
9065DECLARE
9066 m1 float8;
9067 m2 float8;
9068BEGIN
9069 IF pg_typeof(input) = 'random_variable'::REGTYPE THEN
9070 IF input IS NULL THEN
9071 RETURN NULL;
9072 END IF;
9073 -- Conditioning on prov is handled inside rv_moment: when prov
9074 -- resolves to gate_one() (the default, or load-time
9075 -- simplification of any always-true sub-circuit) the
9076 -- unconditional analytical path runs unchanged; otherwise the
9077 -- joint-circuit loader unifies shared gate_rv leaves between
9078 -- input and prov, and the conditional path runs either
9079 -- truncated-distribution closed form or MC rejection.
9080 RETURN provsql.rv_moment(
9081 rv_conditioned_target((input::random_variable)::UUID), 2, true,
9082 rv_conditioned_prov((input::random_variable)::UUID, prov));
9083 END IF;
9084
9085 IF pg_typeof(input) = 'AGG_TOKEN'::REGTYPE THEN
9086 IF input IS NULL THEN
9087 RETURN NULL;
9088 END IF;
9089 -- Collapsed fast path: E[C] and E[C^2] from a single circuit load and plan
9090 -- build, instead of two agg_raw_moment() calls that each reload. Mirrors
9091 -- the guard in agg_raw_moment (unconditional only, prov = one); on any
9092 -- mismatch agg_collapsed_moments returns NULL and we fall through to the
9093 -- generic per-order path (which handles conditioning, SUM enumeration, ...).
9094 IF rv_conditioned_prov(input::UUID, prov) = gate_one() THEN
9095 DECLARE ms float8[];
9096 BEGIN
9097 ms := agg_collapsed_moments(
9098 (agg_conditioned_target(input::AGG_TOKEN))::UUID);
9099 IF ms IS NOT NULL THEN
9100 RETURN ms[2] - ms[1] * ms[1];
9101 END IF;
9102 END;
9103 END IF;
9104 m1 := agg_raw_moment(agg_conditioned_target(input::AGG_TOKEN), 1,
9105 rv_conditioned_prov(input::UUID, prov), method, arguments);
9106 m2 := agg_raw_moment(agg_conditioned_target(input::AGG_TOKEN), 2,
9107 rv_conditioned_prov(input::UUID, prov), method, arguments);
9108 IF m1 IS NULL OR m2 IS NULL THEN
9109 RETURN NULL;
9110 END IF;
9111 RETURN m2 - m1 * m1;
9112 END IF;
9113
9114 -- Bernoulli event token (see moment()): Var[X] = p(1 - p).
9115 IF pg_typeof(input) = 'UUID'::REGTYPE THEN
9116 IF input IS NULL THEN
9117 RETURN NULL;
9118 END IF;
9119 m1 := provsql.probability_evaluate(provsql.cond(input::UUID, prov),
9120 method, arguments);
9121 RETURN m1 * (1 - m1);
9122 END IF;
9123
9124 RAISE EXCEPTION 'variance() is not yet supported for input type %', pg_typeof(input)
9125 USING ERRCODE = 'feature_not_supported',
9126 DETAIL = 'provsql-reason: moment-input-type; scope: gap';
9127END
9128$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE SET search_path=provsql SECURITY DEFINER;
9129
9130/**
9131 * @brief Compute the raw moment E[X^k | prov] of a probabilistic scalar
9132 *
9133 * @c k must be a non-negative INTEGER. @c k = 0 returns 1; @c k = 1
9134 * is equivalent to @c expected(input). Polymorphic dispatcher: routes
9135 * @c random_variable through @c rv_moment (analytical / MC) and
9136 * @c AGG_TOKEN through @c agg_raw_moment (SUM via tuple enumeration,
9137 * MIN / MAX via rank enumeration, AVG via the joint (sum, count)
9138 * distribution over independent / laminar rows with a Monte-Carlo
9139 * fallback).
9140 */
9141CREATE OR REPLACE FUNCTION moment(
9142 input ANYELEMENT,
9143 k INTEGER,
9144 prov UUID = gate_one(),
9145 method TEXT = NULL,
9146 arguments TEXT = NULL)
9147 RETURNS DOUBLE PRECISION AS $$
9148BEGIN
9149 IF pg_typeof(input) = 'random_variable'::REGTYPE THEN
9150 IF input IS NULL OR k IS NULL THEN
9151 RETURN NULL;
9152 END IF;
9153 -- See variance() above: rv_moment handles the conditional/unconditional
9154 -- dispatch internally based on the resolved prov gate type.
9155 RETURN provsql.rv_moment(
9156 rv_conditioned_target((input::random_variable)::UUID), k, false,
9157 rv_conditioned_prov((input::random_variable)::UUID, prov));
9158 END IF;
9159
9160 IF pg_typeof(input) = 'AGG_TOKEN'::REGTYPE THEN
9161 RETURN agg_raw_moment(agg_conditioned_target(input::AGG_TOKEN), k,
9162 rv_conditioned_prov(input::UUID, prov), method, arguments);
9163 END IF;
9164
9165 -- A bare provenance event token (a gate_cmp lifted from an RV comparison,
9166 -- e.g. expected(x <= c)) is a Bernoulli indicator: X in {0,1}, so every raw
9167 -- moment E[X^k] with k >= 1 equals P(event), and E[X^0] = 1. cond() applies
9168 -- the optional conditioning prov (a no-op for the default gate_one()).
9169 IF pg_typeof(input) = 'UUID'::REGTYPE THEN
9170 IF input IS NULL OR k IS NULL THEN
9171 RETURN NULL;
9172 END IF;
9173 IF k = 0 THEN
9174 RETURN 1;
9175 END IF;
9176 RETURN provsql.probability_evaluate(provsql.cond(input::UUID, prov),
9177 method, arguments);
9178 END IF;
9179
9180 RAISE EXCEPTION 'moment() is not yet supported for input type %', pg_typeof(input)
9181 USING ERRCODE = 'feature_not_supported',
9182 DETAIL = 'provsql-reason: moment-input-type; scope: gap';
9183END
9184$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE SET search_path=provsql SECURITY DEFINER;
9185
9186/**
9187 * @brief Internal: rv-side quantile computation.
9188 *
9189 * C entry point behind the polymorphic @c quantile dispatcher.
9190 * Closed-form inverse CDF where the family has one (Normal via
9191 * Beasley-Springer-Moro polished by Newton steps, Uniform and
9192 * Exponential by algebraic inversion), generic monotone-CDF bisection
9193 * otherwise (Erlang, Gamma), exact generalised inverse for categorical
9194 * mixtures, and the empirical Monte Carlo quantile for compound scalar
9195 * circuits. A non-trivial @p prov conditions (truncates) the
9196 * distribution first, in closed form when the event reduces to an
9197 * interval on a bare @c gate_rv.
9198 */
9199CREATE OR REPLACE FUNCTION rv_quantile(
9200 token UUID, p double precision,
9201 prov UUID DEFAULT gate_one())
9202 RETURNS double precision
9203 AS 'provsql','rv_quantile' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
9204
9205/**
9206 * @brief Compute the p-quantile (inverse CDF) of a probabilistic scalar
9207 *
9208 * @f$F^{-1}(p) = \min\{x : P(X \le x) \ge p\}@f$ for @f$p \in [0,1]@f$:
9209 * medians (@c p = 0.5), percentiles, Value-at-Risk, and credible
9210 * intervals. @c p = 0 / @c p = 1 return the (possibly infinite)
9211 * support edges. Polymorphic dispatcher mirroring @c expected /
9212 * @c moment: @c random_variable routes through @c rv_quantile
9213 * (analytical inverse CDF / MC), plain numerics are their own quantile
9214 * (a Dirac's inverse CDF is constant), and the optional @p prov
9215 * argument conditions on a provenance event, e.g.
9216 * <tt>quantile(x | (x > 0), 0.5)</tt> for the median of a truncated
9217 * distribution.
9218 */
9219CREATE OR REPLACE FUNCTION quantile(
9220 input ANYELEMENT,
9221 p double precision,
9222 prov UUID = gate_one(),
9223 method TEXT = NULL,
9224 arguments TEXT = NULL)
9225 RETURNS DOUBLE PRECISION AS $$
9226BEGIN
9227 IF p IS NULL THEN
9228 RETURN NULL;
9229 END IF;
9230 IF p <> p OR p < 0 OR p > 1 THEN
9231 RAISE EXCEPTION 'quantile: p must be in [0, 1] (got %)', p;
9232 END IF;
9233
9234 IF pg_typeof(input) = 'random_variable'::REGTYPE THEN
9235 IF input IS NULL THEN
9236 RETURN NULL;
9237 END IF;
9238 -- See variance(): rv_quantile handles the conditional/unconditional
9239 -- dispatch internally based on the resolved prov gate type.
9240 RETURN provsql.rv_quantile(
9241 rv_conditioned_target((input::random_variable)::UUID), p,
9242 rv_conditioned_prov((input::random_variable)::UUID, prov));
9243 END IF;
9244
9245 IF pg_typeof(input) IN ('smallint'::REGTYPE, 'INTEGER'::REGTYPE,
9246 'bigint'::REGTYPE, 'NUMERIC'::REGTYPE,
9247 'real'::REGTYPE, 'double precision'::REGTYPE) THEN
9248 -- A deterministic scalar is a Dirac: every quantile is the value.
9249 RETURN input::double precision;
9250 END IF;
9251
9252 RAISE EXCEPTION 'quantile() is not yet supported for input type %', pg_typeof(input)
9253 USING ERRCODE = 'feature_not_supported',
9254 DETAIL = 'provsql-reason: quantile-input-type; scope: gap';
9255END
9256$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE SET search_path=provsql SECURITY DEFINER;
9257
9258/**
9259 * @brief Internal: rv-side support computation
9260 *
9261 * Lifts @c provsql.compute_support out of @c RangeCheck.cpp -- the
9262 * same interval-arithmetic propagation @c runRangeCheck uses to
9263 * decide @c gate_cmps. Returns @c [-Infinity, +Infinity] when the
9264 * tightest bound is the conservative all-real interval (e.g. for a
9265 * normal RV, or any sub-circuit that mixes a normal in).
9266 */
9267CREATE OR REPLACE FUNCTION rv_support(
9268 token UUID, prov UUID DEFAULT gate_one(),
9269 OUT lo float8, OUT hi float8)
9270 AS 'provsql','rv_support' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
9271
9272/**
9273 * @brief Compute the support interval @c [lo, hi] of a probabilistic
9274 * (or deterministic) scalar
9275 *
9276 * Polymorphic dispatcher mirroring @c expected / @c variance /
9277 * @c moment / @c central_moment, with two extra "free" branches:
9278 *
9279 * - <b>Plain NUMERIC</b> (@c smallint / @c INTEGER / @c bigint /
9280 * @c NUMERIC / @c real / @c double @c precision): degenerate
9281 * point support @f$[c, c]@f$. Lets callers ask for the support
9282 * of a literal without round-tripping through @c as_random.
9283 * - <b>@c random_variable / bare @c UUID</b> (any provenance gate
9284 * token; the @c random_variable branch reinterprets the value via
9285 * the binary-coercible @c random_variable @c -> @c UUID cast):
9286 * routes to @c rv_support, which propagates distribution
9287 * supports (uniform exact, exponential @c [0,+∞), normal
9288 * @c (-∞,+∞)) through @c gate_arith via interval arithmetic.
9289 * @c gate_value gives the same @f$[c, c]@f$ point support as the
9290 * NUMERIC branch; any non-scalar gate (Boolean gates, aggregates,
9291 * ...) safely falls back to the conservative all-real interval
9292 * without raising. Conditioning on @c prov is not yet supported.
9293 *
9294 * - @c AGG_TOKEN: closed-form per aggregation function, over the worlds
9295 * where the aggregate has a value (an empty group has none, except for
9296 * a scalar @c COUNT, which is 0 there):
9297 * - @c SUM and @c COUNT (the sum of per-row 1s, or 0s for @c NULL
9298 * counted columns): @f$[\sum_i \min(0,v_i), \sum_i \max(0,v_i)]@f$,
9299 * with a row always present adding @f$v_i@f$ itself (every other row
9300 * is independently in or out of the included set; the extreme sums
9301 * include only its positive or only its negative values). Unless a
9302 * row is always present or the empty world counts, a bound moves in
9303 * from 0 to @f$\min_i v_i@f$ when every @f$v_i > 0@f$, and to
9304 * @f$\max_i v_i@f$ when every @f$v_i < 0@f$.
9305 * - @c MIN : @f$[\min_i v_i, \max_i v_i]@f$ in the non-empty
9306 * subsets, plus @c +Infinity if the empty subset has positive
9307 * probability under @c prov.
9308 * - @c MAX : symmetric -- @c -Infinity if empty has positive
9309 * probability under @c prov, otherwise @c min_i v_i; @c hi is
9310 * always @c max_i v_i.
9311 *
9312 * Other aggregation functions raise.
9313 *
9314 * Returns the composite RECORD @c (lo, hi) via the function's
9315 * @c OUT parameters, with @c -Infinity / @c +Infinity marking
9316 * unbounded ends.
9317 */
9318CREATE OR REPLACE FUNCTION support(
9319 input ANYELEMENT,
9320 prov UUID = gate_one(),
9321 method TEXT = NULL,
9322 arguments TEXT = NULL,
9323 OUT lo float8,
9324 OUT hi float8)
9325 AS $$
9326DECLARE
9327 aggregation_function VARCHAR;
9328 child_pairs UUID[];
9329 values_arr float8[];
9330 total_probability float8;
9331 vmin float8;
9332 vmax float8;
9333 some_always BOOLEAN;
9334BEGIN
9335 IF input IS NULL THEN
9336 lo := NULL; hi := NULL; RETURN;
9337 END IF;
9338
9339 -- Plain NUMERIC: degenerate point support. Lets `support(2.5)` /
9340 -- `support(42)` / etc. return (2.5, 2.5) without making the user
9341 -- wrap in `as_random`.
9342 IF pg_typeof(input) IN (
9343 'smallint'::REGTYPE, 'INTEGER'::REGTYPE, 'bigint'::REGTYPE,
9344 'NUMERIC'::REGTYPE, 'real'::REGTYPE, 'double precision'::REGTYPE) THEN
9345 lo := input::double precision;
9346 hi := input::double precision;
9347 RETURN;
9348 END IF;
9349
9350 -- random_variable is binary-coercible to UUID (explicit cast
9351 -- below), so a single rv_support call covers both shapes.
9352 -- rv_support handles
9353 -- gate_value (point), gate_rv (distribution), gate_arith
9354 -- (propagated), and falls back to the conservative all-real
9355 -- interval for any other gate kind. Conditioning on prov is not
9356 -- supported (would require restricting the underlying joint
9357 -- distribution by the indicator of prov, which has no closed form
9358 -- for the basic distributions we ship).
9359 IF pg_typeof(input) IN ('random_variable'::REGTYPE, 'UUID'::REGTYPE) THEN
9360 -- Conditional support: rv_support folds the AND-conjunct interval
9361 -- constraints from prov into the unconditional support. When
9362 -- prov is gate_one() the unconditional support is returned
9363 -- unchanged.
9364 SELECT r.lo, r.hi INTO lo, hi
9365 FROM provsql.rv_support(
9366 rv_conditioned_target(input::UUID),
9367 rv_conditioned_prov(input::UUID, prov)) r;
9368 RETURN;
9369 END IF;
9370
9371 IF pg_typeof(input) = 'AGG_TOKEN'::REGTYPE THEN
9372 -- A conditioned aggregate SUM(x)|C: the value-range support is that of
9373 -- the target aggregate (conditioning can only tighten it; the
9374 -- conservative range stays valid), so unpack to the target gate.
9375 DECLARE
9376 atok AGG_TOKEN := agg_conditioned_target(input::AGG_TOKEN);
9377 BEGIN
9378 IF get_gate_type(atok) <> 'agg' THEN
9379 RAISE EXCEPTION USING MESSAGE='Wrong gate type for support computation',
9380 DETAIL = 'provsql-reason: support-not-an-aggregate; scope: deliberate';
9381 END IF;
9382 SELECT pp.proname::varchar FROM pg_proc pp
9383 WHERE oid=(get_infos(atok)).info1
9384 INTO aggregation_function;
9385 child_pairs := get_children(atok);
9386
9387 IF aggregation_function = 'sum' OR aggregation_function = 'count' THEN
9388 -- COUNT is the SUM of its per-row values: 1, or 0 for a row whose
9389 -- counted column is NULL. A row always present adds its value; any
9390 -- other adds it or nothing.
9391 IF COALESCE(array_length(child_pairs, 1), 0) = 0 THEN
9392 lo := 0; hi := 0; RETURN;
9393 END IF;
9394 SELECT sum(CASE WHEN always THEN v ELSE LEAST(v, 0::float8) END),
9395 sum(CASE WHEN always THEN v ELSE GREATEST(v, 0::float8) END),
9396 min(v), max(v), bool_or(always)
9397 INTO lo, hi, vmin, vmax, some_always
9398 FROM (SELECT CAST(get_extra((get_children(c))[2]) AS float8) AS v,
9399 get_gate_type((get_children(c))[1]) = 'one' AS always
9400 FROM unnest(child_pairs) AS c) sub;
9401 -- The support covers the worlds where the aggregate has a value. An
9402 -- empty group has none for SUM, and none for a grouped COUNT either,
9403 -- there being no row to carry it; only a scalar COUNT (the top bit of
9404 -- info2) is 0 there. Unless a row is always present or the empty world
9405 -- counts, at least one row is, so a bound moves in from 0 when every
9406 -- value is on the same side of it.
9407 IF NOT some_always
9408 AND NOT (aggregation_function = 'count' AND (get_infos(atok)).info2 < 0) THEN
9409 IF vmin > 0 THEN lo := vmin; END IF;
9410 IF vmax < 0 THEN hi := vmax; END IF;
9411 END IF;
9412 ELSIF aggregation_function = 'min' OR aggregation_function = 'max' THEN
9413 -- MIN/MAX over the empty input world are NULL, not ±Infinity (matching the
9414 -- moment surface): the empty world carries no value, so the support is just
9415 -- the range of the per-row values [min(v), max(v)]. A structurally empty
9416 -- aggregate has no defined value at all -> NULL support.
9417 IF COALESCE(array_length(child_pairs, 1), 0) = 0 THEN
9418 lo := NULL; hi := NULL; RETURN;
9419 END IF;
9420
9421 SELECT min(v), max(v)
9422 INTO lo, hi
9423 FROM (SELECT CAST(get_extra((get_children(c))[2]) AS float8) AS v
9424 FROM UNNEST(child_pairs) AS c) sub;
9425 ELSE
9426 RAISE EXCEPTION USING MESSAGE=
9427 'Cannot compute support for aggregation function ' || aggregation_function,
9428 DETAIL = 'provsql-reason: support-aggregate-kind; scope: gap';
9429 END IF;
9430 RETURN;
9431 END;
9432 END IF;
9433
9434 RAISE EXCEPTION 'support() is not yet supported for input type %', pg_typeof(input)
9435 USING ERRCODE = 'feature_not_supported',
9436 DETAIL = 'provsql-reason: support-input-type; scope: gap';
9437END
9438$$ LANGUAGE plpgsql STABLE PARALLEL SAFE SET search_path=provsql SECURITY DEFINER;
9439
9440/**
9441 * @brief Compute the central moment E[(X - E[X|prov])^k | prov]
9442 *
9443 * @c k = 0 returns 1; @c k = 1 returns 0; @c k = 2 is equivalent to
9444 * @c variance(input, prov, ...). Polymorphic dispatcher: routes
9445 * @c random_variable through @c rv_moment, and @c AGG_TOKEN through
9446 * the binomial expansion
9447 * @f$E[(X-\mu)^k|A] = \sum_{i=0}^{k} \binom{k}{i} (-\mu)^{k-i} E[X^i|A]@f$
9448 * with @f$\mu = E[X|A]@f$, where each @f$E[X^i|A]@f$ comes from
9449 * @c agg_raw_moment.
9450 */
9451CREATE OR REPLACE FUNCTION central_moment(
9452 input ANYELEMENT,
9453 k INTEGER,
9454 prov UUID = gate_one(),
9455 method TEXT = NULL,
9456 arguments TEXT = NULL)
9457 RETURNS DOUBLE PRECISION AS $$
9458DECLARE
9459 mu float8;
9460 total float8;
9461 i INTEGER;
9462 raw_i float8;
9463 binom float8;
9464 -- iterative binomial coefficient C(k, i)
9465 k_double float8;
9466BEGIN
9467 IF pg_typeof(input) = 'random_variable'::REGTYPE THEN
9468 IF input IS NULL OR k IS NULL THEN
9469 RETURN NULL;
9470 END IF;
9471 -- See variance() above: rv_moment handles the conditional/unconditional
9472 -- dispatch internally based on the resolved prov gate type.
9473 RETURN provsql.rv_moment(
9474 rv_conditioned_target((input::random_variable)::UUID), k, true,
9475 rv_conditioned_prov((input::random_variable)::UUID, prov));
9476 END IF;
9477
9478 IF pg_typeof(input) = 'AGG_TOKEN'::REGTYPE THEN
9479 IF input IS NULL OR k IS NULL THEN
9480 RETURN NULL;
9481 END IF;
9482 IF k < 0 THEN
9483 RAISE EXCEPTION 'central_moment(): k must be non-negative (got %)', k;
9484 END IF;
9485 IF k = 0 THEN RETURN 1; END IF;
9486 IF k = 1 THEN RETURN 0; END IF;
9487
9488 mu := agg_raw_moment(agg_conditioned_target(input::AGG_TOKEN), 1,
9489 rv_conditioned_prov(input::UUID, prov), method, arguments);
9490 IF mu IS NULL THEN RETURN NULL; END IF;
9491 -- mu may be ±Infinity for empty MIN / MAX with positive empty
9492 -- probability; central_moment is undefined in that case.
9493 IF mu = 'Infinity'::float8 OR mu = '-Infinity'::float8 THEN
9494 RETURN mu;
9495 END IF;
9496
9497 total := 0;
9498 binom := 1; -- C(k, 0)
9499 k_double := k;
9500 FOR i IN 0..k LOOP
9501 raw_i := agg_raw_moment(agg_conditioned_target(input::AGG_TOKEN), i,
9502 rv_conditioned_prov(input::UUID, prov), method, arguments);
9503 IF raw_i IS NULL THEN RETURN NULL; END IF;
9504 total := total + binom * power(-mu, k - i) * raw_i;
9505 -- C(k, i+1) = C(k, i) * (k - i) / (i + 1)
9506 IF i < k THEN
9507 binom := binom * (k_double - i) / (i + 1);
9508 END IF;
9509 END LOOP;
9510 RETURN total;
9511 END IF;
9512
9513 -- Bernoulli event token (see moment()): with p = P(event),
9514 -- E[(X-p)^k] = (1-p)(-p)^k + p(1-p)^k; k = 0 -> 1, k = 1 -> 0.
9515 IF pg_typeof(input) = 'UUID'::REGTYPE THEN
9516 IF input IS NULL OR k IS NULL THEN
9517 RETURN NULL;
9518 END IF;
9519 IF k < 0 THEN
9520 RAISE EXCEPTION 'central_moment(): k must be non-negative (got %)', k;
9521 END IF;
9522 IF k = 0 THEN RETURN 1; END IF;
9523 IF k = 1 THEN RETURN 0; END IF;
9524 mu := provsql.probability_evaluate(provsql.cond(input::UUID, prov),
9525 method, arguments);
9526 RETURN (1 - mu) * power(-mu, k) + mu * power(1 - mu, k);
9527 END IF;
9528
9529 RAISE EXCEPTION 'central_moment() is not yet supported for input type %', pg_typeof(input)
9530 USING ERRCODE = 'feature_not_supported',
9531 DETAIL = 'provsql-reason: moment-input-type; scope: gap';
9532END
9533$$ LANGUAGE plpgsql VOLATILE PARALLEL UNSAFE SET search_path=provsql SECURITY DEFINER;
9534
9535/** @brief C entry point behind @ref covariance (UUID-level binding). */
9536CREATE OR REPLACE FUNCTION rv_covariance(x UUID, y UUID, prov UUID)
9537 RETURNS double precision
9538 AS 'provsql','rv_covariance' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
9539
9540/**
9541 * @brief Covariance Cov(X, Y) = E[XY] − E[X]·E[Y] of two random variables.
9542 *
9543 * The bivariate readout complementing the univariate moment surface
9544 * (@ref expected / @ref variance / @ref moment / @ref central_moment).
9545 * Exact tiers: an exact @c 0 when the two arguments' stochastic-leaf
9546 * footprints are structurally independent (given @p prov), a variance
9547 * readout when the two arguments coincide, and the closed-form
9548 * @c E[XY] − E[X]·E[Y] whenever every factor decomposes analytically.
9549 * When some factor has no closed form, a SINGLE coupled Monte-Carlo pass
9550 * over the joint circuit draws @c (x, y) pairs (shared leaves produce one
9551 * draw both observe) and returns the sample covariance -- the estimator's
9552 * noise then scales with the covariance signal itself, not with the
9553 * product of the means as the naive three-run E[XY] − E[X]·E[Y]
9554 * subtraction would.
9555 *
9556 * @param x the first random variable.
9557 * @param y the second random variable.
9558 * @param prov optional conditioning event (a provenance @c UUID); the
9559 * default @c gate_one() is the unconditional covariance. Conditioning
9560 * is applied jointly: the Monte-Carlo pass rejection-samples the pair on
9561 * @p prov, giving @c Cov(X, Y | prov).
9562 */
9563CREATE OR REPLACE FUNCTION covariance(
9564 x random_variable, y random_variable, prov UUID DEFAULT gate_one())
9565 RETURNS double precision AS $$
9566 SELECT provsql.rv_covariance((x)::UUID, (y)::UUID, prov);
9567$$ LANGUAGE sql PARALLEL SAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
9568
9569/**
9570 * @brief Standard deviation σ(X) = √Var(X) of a random variable.
9571 *
9572 * A thin NUMERIC readout over @ref variance. The square root is taken on
9573 * the scalar @c double result, so no RV-level @c sqrt is involved and this
9574 * carries no dependency on RV function application (@c pow / @c sqrt).
9575 * @c NULL propagates from a @c NULL input; the order-2 central moment is
9576 * non-negative by construction, so the root is always real.
9577 *
9578 * @param x the random variable.
9579 * @param prov optional conditioning event; default @c gate_one()
9580 * (unconditional).
9581 */
9582CREATE OR REPLACE FUNCTION stddev(
9583 x random_variable, prov UUID DEFAULT gate_one())
9584 RETURNS double precision AS $$
9585 SELECT sqrt(provsql.variance(x, prov));
9586$$ LANGUAGE sql PARALLEL UNSAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
9587
9588/** @brief C entry point behind @ref correlation (UUID-level binding). */
9589CREATE OR REPLACE FUNCTION rv_correlation(x UUID, y UUID, prov UUID)
9590 RETURNS double precision
9591 AS 'provsql','rv_correlation' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
9592
9593/**
9594 * @brief Pearson correlation ρ(X, Y) = Cov(X, Y) / (σ(X)·σ(Y)).
9595 *
9596 * Same exact tiers as @ref covariance; on the Monte-Carlo path the
9597 * covariance and BOTH standard deviations are read off the same coupled
9598 * pass, instead of stacking five independent estimates (three for the
9599 * covariance, one per standard deviation). Returns @c NULL when either
9600 * standard deviation is @c 0 (a degenerate / constant variable, for which
9601 * correlation is undefined) rather than raising a division-by-zero.
9602 *
9603 * @param x the first random variable.
9604 * @param y the second random variable.
9605 * @param prov optional conditioning event; default @c gate_one()
9606 * (unconditional).
9607 */
9608CREATE OR REPLACE FUNCTION correlation(
9609 x random_variable, y random_variable, prov UUID DEFAULT gate_one())
9610 RETURNS double precision AS $$
9611 SELECT provsql.rv_correlation((x)::UUID, (y)::UUID, prov);
9612$$ LANGUAGE sql PARALLEL SAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
9613
9614/** @brief C entry point behind @ref entropy (UUID-level binding). */
9615CREATE OR REPLACE FUNCTION rv_entropy(token UUID, prov UUID)
9616 RETURNS double precision
9617 AS 'provsql','rv_entropy' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
9618
9619/**
9620 * @brief Entropy H(X) of a random variable, in nats.
9621 *
9622 * Shannon entropy for a discrete distribution (a categorical / discrete
9623 * count / constant -- a point mass has entropy @c 0), differential
9624 * entropy for a continuous one (quadrature of @c -f ln f over the
9625 * family's integration range; also exact through independent-arm
9626 * Bernoulli mixture trees such as @ref gmm's). Shapes with no
9627 * closed density (arithmetic composites) and the conditional form fall
9628 * back to a Monte Carlo histogram plug-in estimate at the
9629 * @c provsql.rv_mc_samples budget.
9630 *
9631 * @param x the random variable.
9632 * @param prov optional conditioning event; default @c gate_one()
9633 * (unconditional).
9634 */
9635CREATE OR REPLACE FUNCTION entropy(
9636 x random_variable, prov UUID DEFAULT gate_one())
9637 RETURNS double precision AS $$
9638 SELECT provsql.rv_entropy((x)::UUID, prov);
9639$$ LANGUAGE sql PARALLEL SAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
9640
9641/** @brief C entry point behind @ref kl (UUID-level binding). */
9642CREATE OR REPLACE FUNCTION rv_kl(p UUID, q UUID)
9643 RETURNS double precision
9644 AS 'provsql','rv_kl' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
9645
9646/**
9647 * @brief Kullback-Leibler divergence KL(P || Q), in nats.
9648 *
9649 * Exact: the defining sum for two discrete distributions (matching
9650 * outcomes by value) and the defining integral (quadrature over P's
9651 * integration window) for two continuous ones, including
9652 * independent-arm mixture trees. Returns @c Infinity when P is not
9653 * absolutely continuous with respect to Q -- an outcome of P that Q
9654 * gives zero mass, mismatched kinds (discrete vs continuous), or a
9655 * region of P's support where Q's density (under)flows to zero. Both
9656 * arguments must resolve to closed-form densities; arithmetic
9657 * composites and conditioned variables raise.
9658 */
9659CREATE OR REPLACE FUNCTION kl(p random_variable, q random_variable)
9660 RETURNS double precision AS $$
9661 SELECT provsql.rv_kl((p)::UUID, (q)::UUID);
9662$$ LANGUAGE sql PARALLEL SAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
9663
9664/** @brief C entry point behind @ref mutual_information (UUID-level
9665 * binding). */
9666CREATE OR REPLACE FUNCTION rv_mutual_information(x UUID, y UUID)
9667 RETURNS double precision
9668 AS 'provsql','rv_mutual_information' LANGUAGE C VOLATILE STRICT PARALLEL SAFE;
9669
9670/**
9671 * @brief Mutual information I(X; Y), in nats.
9672 *
9673 * Exactly @c 0 for structurally independent variables (disjoint
9674 * stochastic-leaf footprints, the same test the moment evaluators use);
9675 * @c H(X) for a discrete variable paired with itself and @c Infinity
9676 * for a continuous one (I(X;X) diverges). A genuinely correlated pair
9677 * (shared leaves) is estimated by a 2-D histogram plug-in over coupled
9678 * joint Monte Carlo draws -- both roots evaluated against the same
9679 * per-iteration cache, so shared leaves keep their joint law -- at the
9680 * @c provsql.rv_mc_samples budget.
9681 */
9682CREATE OR REPLACE FUNCTION mutual_information(
9683 x random_variable, y random_variable)
9684 RETURNS double precision AS $$
9685 SELECT provsql.rv_mutual_information((x)::UUID, (y)::UUID);
9686$$ LANGUAGE sql PARALLEL SAFE VOLATILE SET search_path=provsql SECURITY DEFINER;
9687
9688/**
9689 * @brief Compute the Shapley value of an input variable
9690 *
9691 * Measures the contribution of a specific input variable to the
9692 * truth of a provenance expression, using game-theoretic Shapley values.
9693 *
9694 * @param token provenance token to evaluate
9695 * @param variable UUID of the input variable
9696 * @param method knowledge compilation method
9697 * @param arguments additional arguments for the method
9698 * @param banzhaf if true, compute the Banzhaf value instead
9699 */
9700CREATE OR REPLACE FUNCTION shapley(
9701 token UUID,
9702 variable UUID,
9703 method TEXT = NULL,
9704 arguments TEXT = NULL,
9705 banzhaf BOOLEAN = 'f')
9706 RETURNS DOUBLE PRECISION AS
9707 'provsql','shapley' LANGUAGE C STABLE;
9708
9709/** @brief Compute Shapley values for all input variables at once */
9710CREATE OR REPLACE FUNCTION shapley_all_vars(
9711 IN token UUID,
9712 IN method TEXT = NULL,
9713 IN arguments TEXT = NULL,
9714 IN banzhaf BOOLEAN = 'f',
9715 OUT variable UUID,
9716 OUT value DOUBLE PRECISION)
9717 RETURNS SETOF RECORD AS
9718 'provsql', 'shapley_all_vars'
9719 LANGUAGE C STABLE;
9720
9721/** @brief Compute the Banzhaf power index of an input variable */
9722CREATE OR REPLACE FUNCTION banzhaf(
9723 token UUID,
9724 variable UUID,
9725 method TEXT = NULL,
9726 arguments TEXT = NULL)
9727 RETURNS DOUBLE PRECISION AS
9728 $$ SELECT provsql.shapley(token, variable, method, arguments, 't') $$
9729 LANGUAGE SQL;
9730
9731/** @brief Compute Banzhaf power indices for all input variables at once */
9732CREATE OR REPLACE FUNCTION banzhaf_all_vars(
9733 IN token UUID,
9734 IN method TEXT = NULL,
9735 IN arguments TEXT = NULL,
9736 OUT variable UUID,
9737 OUT value DOUBLE PRECISION)
9738 RETURNS SETOF RECORD AS
9739 $$ SELECT * FROM provsql.shapley_all_vars(token, method, arguments, 't') $$
9740 LANGUAGE SQL;
9741
9742/**
9743 * @brief Exact reachability probability over bounded-treewidth data
9744 * (columnar form)
9745 *
9746 * Computes the probability that @p target is reachable from @p source in
9747 * the probabilistic graph given by the parallel edge arrays
9748 * (two-terminal network reliability). Unlike
9749 * @c probability_evaluate(), which compiles the provenance circuit
9750 * built along the relational query plan, this compiles the query
9751 * along a tree decomposition of the *data* graph (in the spirit of the
9752 * provenance refinement of Courcelle's theorem), producing a d-DNNF
9753 * whose size is linear in the number of edges for data of bounded
9754 * treewidth. Exact, and linear-time, on cyclic data as well -- where
9755 * the recursive-query fixpoint cannot terminate structurally.
9756 *
9757 * Edges are independent events. Two array positions may share a token
9758 * only if they are mutual reverses (the natural encoding of an
9759 * undirected edge in a directed edge relation); they are then treated
9760 * as a single bidirectional edge. This is an internal/testing surface:
9761 * the user-facing route is a plain @c WITH @c RECURSIVE reachability
9762 * query under the 'absorptive' (or 'BOOLEAN') provenance class, which
9763 * the query rewriter compiles through @c eval_reachability() /
9764 * @c reachability_materialize().
9765 *
9766 * @param sources source vertex of each edge (dense INTEGER IDs)
9767 * @param destinations destination vertex of each edge
9768 * @param tokens provenance token of each edge tuple
9769 * @param probabilities probability of each edge tuple
9770 * @param source the vertex reachability starts from
9771 * @param target the vertex whose reachability is evaluated
9772 * @param directed if false, each edge can be traversed both ways
9773 */
9774CREATE OR REPLACE FUNCTION reachability_evaluate(
9775 sources INT[],
9776 destinations INT[],
9777 tokens UUID[],
9778 probabilities DOUBLE PRECISION[],
9779 source INT,
9780 target INT,
9781 directed BOOLEAN)
9782 RETURNS DOUBLE PRECISION AS
9783 'provsql','reachability_evaluate' LANGUAGE C IMMUTABLE PARALLEL SAFE;
9784
9785/**
9786 * @brief Reachability probability plus compilation statistics
9787 * (columnar form)
9788 *
9789 * Same compilation as @c reachability_evaluate(), returning the
9790 * probability together with the structural statistics that
9791 * substantiate the bounded-treewidth guarantee: the treewidth of the
9792 * min-fill decomposition of the data graph, its number of bags, the
9793 * maximum number of dynamic-programming states at any decomposition
9794 * node, and the size of the emitted d-DNNF (linear in the number of
9795 * edges for fixed data treewidth).
9796 *
9797 * @param sources source vertex of each edge (dense INTEGER IDs)
9798 * @param destinations destination vertex of each edge
9799 * @param tokens provenance token of each edge tuple
9800 * @param probabilities probability of each edge tuple
9801 * @param source the vertex reachability starts from
9802 * @param target the vertex whose reachability is evaluated
9803 * @param directed if false, each edge can be traversed both ways
9804 * @param[out] probability the reachability probability
9805 * @param[out] data_treewidth treewidth of the min-fill decomposition of the
9806 * data graph
9807 * @param[out] nb_bags number of bags in the decomposition
9808 * @param[out] max_states maximum number of dynamic-programming states at any
9809 * decomposition node
9810 * @param[out] nb_gates number of gates in the emitted d-DNNF
9811 * @param[out] nb_variables number of variables in the emitted d-DNNF
9812 */
9813CREATE OR REPLACE FUNCTION reachability_compile_stats(
9814 IN sources INT[],
9815 IN destinations INT[],
9816 IN tokens UUID[],
9817 IN probabilities DOUBLE PRECISION[],
9818 IN source INT,
9819 IN target INT,
9820 IN directed BOOLEAN,
9821 OUT probability DOUBLE PRECISION,
9822 OUT data_treewidth INT,
9823 OUT nb_bags BIGINT,
9824 OUT max_states BIGINT,
9825 OUT nb_gates BIGINT,
9826 OUT nb_variables BIGINT)
9827 AS 'provsql','reachability_compile_stats'
9828 LANGUAGE C IMMUTABLE PARALLEL SAFE;
9829
9830
9831
9832/**
9833 * @brief Boolean UCQ probability plus compilation statistics
9834 * (columnar form, internal)
9835 *
9836 * Same compilation as @c ucq_joint_compile_stats(query jsonb, ...),
9837 * returning the probability together with the three width columns that
9838 * substantiate thesis Prop. 4.2.11 empirically -- the adversarial family
9839 * has small data and circuit widths but large joint width -- and the
9840 * structural statistics.
9841 *
9842 * @param disjunct_nvars number of query variables of each disjunct
9843 * @param atom_disjunct disjunct index of each atom (parallel to @p atom_rel)
9844 * @param atom_rel relation id of each atom
9845 * @param atom_vars query-variable indices of all atom columns, concatenated
9846 * @param atom_arity number of columns of each atom (slices @p atom_vars)
9847 * @param fact_rel relation id of each fact
9848 * @param fact_elems element ids of all fact columns, concatenated
9849 * @param fact_arity number of columns of each fact (slices @p fact_elems)
9850 * @param fact_tokens provenance token of each fact
9851 * @param fact_probs probability of each fact
9852 * @param[out] probability the exact UCQ probability
9853 * @param[out] joint_treewidth width of the min-fill decomposition found
9854 * @param[out] data_treewidth_lb degeneracy lower bound of the data-only graph
9855 * @param[out] circuit_treewidth_lb degeneracy lower bound of the slice-only graph
9856 * @param[out] n_bags number of bags in the decomposition
9857 * @param[out] max_states peak number of DP states at any node
9858 * @param[out] dd_size number of gates in the emitted d-D
9859 * @param[out] n_enumerating maximum number of essential (enumerating) query
9860 * variables over the disjuncts -- the @c e of the @f$2^{O(k^e)}@f$
9861 * bound, with variables functionally determined by others (via FDs
9862 * mined from the data) removed
9863 */
9864CREATE OR REPLACE FUNCTION ucq_joint_compile_stats(
9865 IN disjunct_nvars INT[],
9866 IN atom_disjunct INT[],
9867 IN atom_rel INT[],
9868 IN atom_vars INT[],
9869 IN atom_arity INT[],
9870 IN fact_rel INT[],
9871 IN fact_elems INT[],
9872 IN fact_arity INT[],
9873 IN fact_tokens UUID[],
9874 IN fact_probs DOUBLE PRECISION[],
9875 OUT probability DOUBLE PRECISION,
9876 OUT joint_treewidth INT,
9877 OUT data_treewidth_lb INT,
9878 OUT circuit_treewidth_lb INT,
9879 OUT n_bags BIGINT,
9880 OUT max_states BIGINT,
9881 OUT dd_size BIGINT,
9882 OUT n_enumerating INT)
9883 AS 'provsql','ucq_joint_compile_stats'
9884 LANGUAGE C IMMUTABLE PARALLEL SAFE;
9885
9886
9887/**
9888 * @brief Boolean UCQ probability plus statistics from a JSON specification
9889 *
9890 * JSON-spec wrapper over the columnar @c ucq_joint_compile_stats()
9891 * (see @c ucq_joint_evaluate(query jsonb, ...) for the JSON format).
9892 */
9893CREATE OR REPLACE FUNCTION ucq_joint_compile_stats(
9894 IN query JSONB,
9895 IN fact_rel INT[],
9896 IN fact_elems INT[],
9897 IN fact_arity INT[],
9898 IN fact_tokens UUID[],
9899 IN fact_probs DOUBLE PRECISION[],
9900 OUT probability DOUBLE PRECISION,
9901 OUT joint_treewidth INT,
9902 OUT data_treewidth_lb INT,
9903 OUT circuit_treewidth_lb INT,
9904 OUT n_bags BIGINT,
9905 OUT max_states BIGINT,
9906 OUT dd_size BIGINT,
9907 OUT n_enumerating INT)
9908 AS $$
9909DECLARE
9910 dnv INT[] := '{}'; adisj INT[] := '{}'; arel INT[] := '{}';
9911 avars INT[] := '{}'; aarity INT[] := '{}';
9912 d JSONB; a JSONB; v TEXT; didx INT := 0;
9913BEGIN
9914 FOR d IN SELECT * FROM jsonb_array_elements(query->'disjuncts') LOOP
9915 dnv := dnv || (d->>'n_vars')::INT;
9916 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
9917 adisj := adisj || didx;
9918 arel := arel || (a->>'rel')::INT;
9919 aarity := aarity || jsonb_array_length(a->'vars');
9920 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
9921 avars := avars || v::INT;
9922 END LOOP;
9923 END LOOP;
9924 didx := didx + 1;
9925 END LOOP;
9926 SELECT s.probability, s.joint_treewidth, s.data_treewidth_lb,
9927 s.circuit_treewidth_lb, s.n_bags, s.max_states, s.dd_size,
9928 s.n_enumerating
9929 INTO probability, joint_treewidth, data_treewidth_lb,
9930 circuit_treewidth_lb, n_bags, max_states, dd_size, n_enumerating
9931 FROM ucq_joint_compile_stats(dnv, adisj, arel, avars, aarity,
9932 fact_rel, fact_elems, fact_arity, fact_tokens, fact_probs) s;
9933END;
9934$$ LANGUAGE plpgsql IMMUTABLE PARALLEL SAFE;
9935
9936
9937
9938
9939
9940
9941
9942
9943
9944
9945
9946/**
9947 * @brief Correlated Boolean UCQ probability plus compilation statistics
9948 * (columnar form, internal)
9949 *
9950 * Same compilation as @c ucq_joint_evaluate_tracked(); the three width
9951 * columns substantiate thesis Prop. 4.2.11 on real correlated data (the
9952 * data-only and circuit-only degeneracy bounds can be small while the
9953 * joint width is large).
9954 */
9955CREATE OR REPLACE FUNCTION ucq_joint_compile_stats_tracked(
9956 IN disjunct_nvars INT[],
9957 IN atom_disjunct INT[],
9958 IN atom_rel INT[],
9959 IN atom_vars INT[],
9960 IN atom_arity INT[],
9961 IN fact_rel INT[],
9962 IN fact_elems INT[],
9963 IN fact_arity INT[],
9964 IN fact_tokens UUID[],
9965 OUT probability DOUBLE PRECISION,
9966 OUT joint_treewidth INT,
9967 OUT data_treewidth_lb INT,
9968 OUT circuit_treewidth_lb INT,
9969 OUT n_bags BIGINT,
9970 OUT max_states BIGINT,
9971 OUT dd_size BIGINT,
9972 OUT n_enumerating INT)
9973 AS 'provsql','ucq_joint_compile_stats_tracked'
9974 LANGUAGE C STABLE PARALLEL SAFE;
9975
9976
9977/**
9978 * @brief Correlated Boolean UCQ probability plus statistics from a JSON spec
9979 */
9980CREATE OR REPLACE FUNCTION ucq_joint_compile_stats_tracked(
9981 IN query JSONB,
9982 IN fact_rel INT[],
9983 IN fact_elems INT[],
9984 IN fact_arity INT[],
9985 IN fact_tokens UUID[],
9986 OUT probability DOUBLE PRECISION,
9987 OUT joint_treewidth INT,
9988 OUT data_treewidth_lb INT,
9989 OUT circuit_treewidth_lb INT,
9990 OUT n_bags BIGINT,
9991 OUT max_states BIGINT,
9992 OUT dd_size BIGINT,
9993 OUT n_enumerating INT)
9994 AS $$
9995DECLARE
9996 dnv INT[] := '{}'; adisj INT[] := '{}'; arel INT[] := '{}';
9997 avars INT[] := '{}'; aarity INT[] := '{}';
9998 d JSONB; a JSONB; v TEXT; didx INT := 0;
9999BEGIN
10000 FOR d IN SELECT * FROM jsonb_array_elements(query->'disjuncts') LOOP
10001 dnv := dnv || (d->>'n_vars')::INT;
10002 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
10003 adisj := adisj || didx;
10004 arel := arel || (a->>'rel')::INT;
10005 aarity := aarity || jsonb_array_length(a->'vars');
10006 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
10007 avars := avars || v::INT;
10008 END LOOP;
10009 END LOOP;
10010 didx := didx + 1;
10011 END LOOP;
10012 SELECT s.probability, s.joint_treewidth, s.data_treewidth_lb,
10013 s.circuit_treewidth_lb, s.n_bags, s.max_states, s.dd_size,
10014 s.n_enumerating
10015 INTO probability, joint_treewidth, data_treewidth_lb,
10016 circuit_treewidth_lb, n_bags, max_states, dd_size, n_enumerating
10017 FROM ucq_joint_compile_stats_tracked(dnv, adisj, arel, avars, aarity,
10018 fact_rel, fact_elems, fact_arity, fact_tokens) s;
10019END;
10020$$ LANGUAGE plpgsql STABLE PARALLEL SAFE;
10021
10022/**
10023 * @brief Compile a correlated UCQ and materialise its certified d-D,
10024 * returning the root provenance token (columnar form, internal)
10025 *
10026 * The architecturally-primary route: the compiler builds the
10027 * deterministic, decomposable circuit and materialises it as ordinary
10028 * @c plus / @c times / @c monus provenance gates (carrying the d-DNNF
10029 * certificate); the answer is then obtained through the standard entry
10030 * points on the returned token -- @c probability_evaluate(token),
10031 * @c shapley(token, ...), expectation -- so the joint-width path shares
10032 * the one evaluation pipeline. The token is the exact Boolean
10033 * provenance of the UCQ (no @c 'absorptive' marker).
10034 */
10035CREATE OR REPLACE FUNCTION ucq_joint_materialize_tracked(
10036 disjunct_nvars INT[],
10037 atom_disjunct INT[],
10038 atom_rel INT[],
10039 atom_vars INT[],
10040 atom_arity INT[],
10041 fact_rel INT[],
10042 fact_elems INT[],
10043 fact_arity INT[],
10044 fact_tokens UUID[])
10045 RETURNS UUID AS
10046 'provsql','ucq_joint_materialize_tracked' LANGUAGE C VOLATILE;
10047
10048/**
10049 * @brief Compile a correlated UCQ and materialise its certified d-D
10050 * from a JSON spec, returning the root provenance token
10051 *
10052 * JSON-spec wrapper over @c ucq_joint_materialize_tracked(). Evaluate
10053 * the answer with the standard surface, e.g.
10054 * @c probability_evaluate(ucq_joint_materialize_tracked(query, ...)).
10055 */
10056CREATE OR REPLACE FUNCTION ucq_joint_materialize_tracked(
10057 query JSONB,
10058 fact_rel INT[],
10059 fact_elems INT[],
10060 fact_arity INT[],
10061 fact_tokens UUID[])
10062 RETURNS UUID AS $$
10063DECLARE
10064 dnv INT[] := '{}'; adisj INT[] := '{}'; arel INT[] := '{}';
10065 avars INT[] := '{}'; aarity INT[] := '{}';
10066 d JSONB; a JSONB; v TEXT; didx INT := 0;
10067BEGIN
10068 FOR d IN SELECT * FROM jsonb_array_elements(query->'disjuncts') LOOP
10069 dnv := dnv || (d->>'n_vars')::INT;
10070 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
10071 adisj := adisj || didx;
10072 arel := arel || (a->>'rel')::INT;
10073 aarity := aarity || jsonb_array_length(a->'vars');
10074 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
10075 avars := avars || v::INT;
10076 END LOOP;
10077 END LOOP;
10078 didx := didx + 1;
10079 END LOOP;
10080 RETURN ucq_joint_materialize_tracked(dnv, adisj, arel, avars, aarity,
10081 fact_rel, fact_elems, fact_arity, fact_tokens);
10082END;
10083$$ LANGUAGE plpgsql VOLATILE;
10084
10085/**
10086 * @brief Compile a UCQ over named relations into a materialised certified
10087 * d-D, gathering the facts from the store -- the descriptor-driven engine
10088 *
10089 * The query-surface bridge for the joint-width compiler: instead of
10090 * hand-built columnar arrays, a JSON @p descriptor names the relations
10091 * and how their columns map to query variables, and this function
10092 * gathers the facts itself (the provenance rewriting is disabled around
10093 * the gather), builds the value-based element dictionary shared across
10094 * the relations (so equal join values get the same dense id), compiles
10095 * and materialises the certified d-D, and returns its provenance token.
10096 * The answer is then any standard evaluation on that token --
10097 * @c probability_evaluate(ucq_joint_provenance(...)),
10098 * @c shapley(...), expectation. This is also the engine the planner-time
10099 * query recogniser drives once it builds the descriptor from a query's
10100 * abstract syntax.
10101 *
10102 * Descriptor shape:
10103 * @verbatim
10104 * { "disjuncts": [ { "n_vars": k,
10105 * "atoms": [ {"rel": <relidx>, "vars": [..]}, ... ] }, ... ],
10106 * "relations": [ "schema.r", "schema.s", ... ], -- relidx -> relation
10107 * "elem_cols": [ ["x"], ["x","y"], ... ] } -- per relation: the
10108 * element columns, in
10109 * the atom's var order
10110 * @endverbatim
10111 *
10112 * @param descriptor the UCQ + the relations and their element columns
10113 * @param fallback token returned if the joint-width compiler declines
10114 * @return the materialised joint-width provenance token (NULL UUID-free
10115 * exact Boolean provenance of the UCQ)
10116 */
10117CREATE OR REPLACE FUNCTION ucq_joint_provenance(
10118 descriptor JSONB, fallback UUID DEFAULT NULL)
10119RETURNS UUID AS $$
10120DECLARE
10121 legs TEXT; sql TEXT; saved TEXT;
10122 fact_rel INT[]; fact_elems INT[]; fact_arity INT[]; fact_tokens UUID[];
10123 dnv INT[]:='{}'; adisj INT[]:='{}'; arel INT[]:='{}';
10124 avars INT[]:='{}'; aarity INT[]:='{}';
10125 d jsonb; a jsonb; v TEXT; didx INT:=0;
10126BEGIN
10127 -- Parse the UCQ structure into the columnar query arrays.
10128 FOR d IN SELECT * FROM jsonb_array_elements(descriptor->'disjuncts') LOOP
10129 dnv := dnv || (d->>'n_vars')::INT;
10130 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
10131 adisj := adisj || didx; arel := arel || (a->>'rel')::INT;
10132 aarity := aarity || jsonb_array_length(a->'vars');
10133 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
10134 avars := avars || v::INT;
10135 END LOOP;
10136 END LOOP;
10137 didx := didx + 1;
10138 END LOOP;
10139
10140 -- One UNION ALL leg per relation: (relation index, TEXT element array,
10141 -- provenance token). No temp tables: a single gather query, with the
10142 -- value-based dense element dictionary built inline.
10143 SELECT string_agg(
10144 format('SELECT %s, ARRAY[%s]::TEXT[], provsql FROM %s%s',
10145 rn - 1,
10146 (SELECT string_agg(format('(%I)::TEXT', c), ',')
10147 FROM jsonb_array_elements_text(descriptor->'elem_cols'->(rn-1)::INT) c),
10148 rel,
10149 -- the lifted single-relation selection (a pre-filter), already
10150 -- deparsed to SQL by the recogniser; '' / absent = unfiltered.
10151 CASE WHEN coalesce(descriptor->'rel_where'->>(rn-1)::INT,'') <> ''
10152 THEN ' WHERE '||(descriptor->'rel_where'->>(rn-1)::INT)
10153 ELSE '' END),
10154 ' UNION ALL ')
10155 INTO legs
10156 FROM jsonb_array_elements_text(descriptor->'relations') WITH ORDINALITY t(rel, rn);
10157
10158 sql := format($q$
10159 WITH facts(rel,elems,tok) AS (%s),
10160 ord AS (SELECT row_number() OVER () AS ord, rel, elems, tok FROM facts),
10161 dict AS (SELECT val, (dense_rank() OVER (ORDER BY val))-1 AS id
10162 FROM (SELECT DISTINCT unnest(elems) AS val FROM facts) u)
10163 SELECT (SELECT array_agg(rel ORDER BY ord) FROM ord),
10164 (SELECT array_agg(cardinality(elems) ORDER BY ord) FROM ord),
10165 (SELECT array_agg(tok ORDER BY ord) FROM ord),
10166 (SELECT array_agg(dd.id ORDER BY o.ord, e.k)
10167 FROM ord o, LATERAL unnest(o.elems) WITH ORDINALITY e(val,k)
10168 JOIN dict dd ON dd.val = e.val)
10169 $q$, legs);
10170
10171 -- Read the raw rows with provenance rewriting disabled (we only read
10172 -- the existing provsql column; this internal gather is not tracked).
10173 saved := current_setting('provsql.active', true);
10174 PERFORM set_config('provsql.active','off', true);
10175 EXECUTE sql INTO fact_rel, fact_arity, fact_tokens, fact_elems;
10176 PERFORM set_config('provsql.active', saved, true);
10177
10178 RETURN ucq_joint_materialize_tracked(dnv,adisj,arel,avars,aarity,
10179 fact_rel,fact_elems,fact_arity,fact_tokens);
10180EXCEPTION WHEN OTHERS THEN
10181 -- The joint-width compiler declined (unsupported gate type, joint
10182 -- width too large, ...): fall back to the normal provenance so the
10183 -- query never fails. Both give the same probability.
10184 RETURN fallback;
10185END;
10186$$ LANGUAGE plpgsql VOLATILE;
10187
10188-- ===========================================================================
10189-- Safe-UCQ Möbius-inversion route (mobius_evaluate.cpp).
10190--
10191-- The last missing exact route of the Dalvi-Suciu dichotomy: UCQs that are
10192-- safe only because the \#P-hard terms of their inclusion-exclusion expansion
10193-- carry a zero Möbius value on the CNF lattice and cancel (canonical witness:
10194-- QW / q9). Same TID gather as ucq_joint, then the lattice-walking compiler
10195-- materialises a gate_mobius-rooted circuit (a signed combination over
10196-- certified-independent islands), answered in PTIME data complexity by the
10197-- standard probability path.
10198-- ===========================================================================
10199
10200/**
10201 * @brief Materialise the safe-UCQ Möbius circuit and return its root token.
10202 * Columnar (TID) interface; see ucq_mobius_provenance for the gather.
10203 */
10204CREATE OR REPLACE FUNCTION ucq_mobius_materialize_tracked(
10205 disjunct_nvars INT[],
10206 atom_disjunct INT[],
10207 atom_rel INT[],
10208 atom_vars INT[],
10209 atom_arity INT[],
10210 fact_rel INT[],
10211 fact_elems INT[],
10212 fact_arity INT[],
10213 fact_tokens UUID[],
10214 lineage UUID DEFAULT NULL)
10215 RETURNS UUID AS
10216 'provsql','ucq_mobius_materialize_tracked' LANGUAGE C VOLATILE;
10217
10218/**
10219 * @brief Compile the Möbius circuit and return the lattice statistics plus the
10220 * probability (the demonstrability surface). @c cancelled_hard is the
10221 * single number that makes the mechanism legible: for q9 the 1 cancelled
10222 * element is \#P-hard, so the query is easy only because its hard part
10223 * cancels.
10224 */
10225CREATE OR REPLACE FUNCTION ucq_mobius_compile_stats(
10226 IN disjunct_nvars INT[],
10227 IN atom_disjunct INT[],
10228 IN atom_rel INT[],
10229 IN atom_vars INT[],
10230 IN atom_arity INT[],
10231 IN fact_rel INT[],
10232 IN fact_elems INT[],
10233 IN fact_arity INT[],
10234 IN fact_tokens UUID[],
10235 OUT probability DOUBLE PRECISION,
10236 OUT n_components INT,
10237 OUT n_cnf_conjuncts INT,
10238 OUT lattice_size INT,
10239 OUT n_nonzero INT,
10240 OUT n_cancelled INT,
10241 OUT cancelled_hard BOOLEAN,
10242 OUT dd_size BIGINT,
10243 OUT memo_hits BIGINT)
10244 AS 'provsql','ucq_mobius_compile_stats'
10245 LANGUAGE C VOLATILE;
10246
10247/**
10248 * @brief Pass a token through iff it is a @c gate_mobius, else return NULL.
10249 *
10250 * The Möbius-precedence dispatch (see @c make_provenance_expression) wraps the
10251 * Möbius call in this and then @c COALESCE\ s it before the joint-width call:
10252 * a Möbius *success* always roots a @c gate_mobius (the compiler wraps even a
10253 * thin selector around the lineage), so it short-circuits and the joint-width
10254 * compiler never runs; a Möbius *decline* returns the literal lineage (never a
10255 * @c gate_mobius), so this yields NULL and @c COALESCE falls through to
10256 * joint-width. The lineage token is a plain plus/times/input, so the test is
10257 * unambiguous.
10258 */
10259CREATE OR REPLACE FUNCTION mobius_or_null(tok UUID)
10260RETURNS UUID AS $$
10261 SELECT CASE WHEN tok IS NOT NULL AND provsql.get_gate_type(tok) = 'mobius'
10262 THEN tok END
10263$$ LANGUAGE sql STABLE;
10264
10265/**
10266 * @brief Möbius-route provenance from a descriptor (the planner-substituted
10267 * entry point, and the manual one). Same descriptor and TID gather as
10268 * @c ucq_joint_provenance; on any decline (unsafe shape, cap, not TID)
10269 * returns @p fallback, so a recognised query never fails.
10270 */
10271CREATE OR REPLACE FUNCTION ucq_mobius_provenance(
10272 descriptor JSONB, fallback UUID DEFAULT NULL)
10273RETURNS UUID AS $$
10274DECLARE
10275 legs TEXT; sql TEXT; saved TEXT;
10276 fact_rel INT[]; fact_elems INT[]; fact_arity INT[]; fact_tokens UUID[];
10277 dnv INT[]:='{}'; adisj INT[]:='{}'; arel INT[]:='{}';
10278 avars INT[]:='{}'; aarity INT[]:='{}';
10279 d jsonb; a jsonb; v TEXT; didx INT:=0;
10280BEGIN
10281 FOR d IN SELECT * FROM jsonb_array_elements(descriptor->'disjuncts') LOOP
10282 dnv := dnv || (d->>'n_vars')::INT;
10283 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
10284 adisj := adisj || didx; arel := arel || (a->>'rel')::INT;
10285 aarity := aarity || jsonb_array_length(a->'vars');
10286 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
10287 avars := avars || v::INT;
10288 END LOOP;
10289 END LOOP;
10290 didx := didx + 1;
10291 END LOOP;
10292
10293 SELECT string_agg(
10294 format('SELECT %s, ARRAY[%s]::TEXT[], provsql FROM %s%s',
10295 rn - 1,
10296 (SELECT string_agg(format('(%I)::TEXT', c), ',')
10297 FROM jsonb_array_elements_text(descriptor->'elem_cols'->(rn-1)::INT) c),
10298 rel,
10299 CASE WHEN coalesce(descriptor->'rel_where'->>(rn-1)::INT,'') <> ''
10300 THEN ' WHERE '||(descriptor->'rel_where'->>(rn-1)::INT)
10301 ELSE '' END),
10302 ' UNION ALL ')
10303 INTO legs
10304 FROM jsonb_array_elements_text(descriptor->'relations') WITH ORDINALITY t(rel, rn);
10305
10306 sql := format($q$
10307 WITH facts(rel,elems,tok) AS (%s),
10308 ord AS (SELECT row_number() OVER () AS ord, rel, elems, tok FROM facts),
10309 dict AS (SELECT val, (dense_rank() OVER (ORDER BY val))-1 AS id
10310 FROM (SELECT DISTINCT unnest(elems) AS val FROM facts) u)
10311 SELECT (SELECT array_agg(rel ORDER BY ord) FROM ord),
10312 (SELECT array_agg(cardinality(elems) ORDER BY ord) FROM ord),
10313 (SELECT array_agg(tok ORDER BY ord) FROM ord),
10314 (SELECT array_agg(dd.id ORDER BY o.ord, e.k)
10315 FROM ord o, LATERAL unnest(o.elems) WITH ORDINALITY e(val,k)
10316 JOIN dict dd ON dd.val = e.val)
10317 $q$, legs);
10318
10319 saved := current_setting('provsql.active', true);
10320 PERFORM set_config('provsql.active','off', true);
10321 EXECUTE sql INTO fact_rel, fact_arity, fact_tokens, fact_elems;
10322 PERFORM set_config('provsql.active', saved, true);
10323
10324 -- Pass the normal-provenance fallback as the lineage: it is carried on the
10325 -- gate_mobius so the token still answers Shapley / semiring / PROV on the
10326 -- literal lineage (the Möbius combination is a probability-only shortcut).
10327 RETURN ucq_mobius_materialize_tracked(dnv,adisj,arel,avars,aarity,
10328 fact_rel,fact_elems,fact_arity,fact_tokens, fallback);
10329EXCEPTION WHEN OTHERS THEN
10330 RETURN fallback;
10331END;
10332$$ LANGUAGE plpgsql VOLATILE;
10333
10334/**
10335 * @brief Möbius lattice statistics + probability from a descriptor: the
10336 * demonstrability SRF. Gathers
10337 * the same TID facts as @c ucq_mobius_provenance, then runs the columnar
10338 * @c ucq_mobius_compile_stats.
10339 */
10340CREATE OR REPLACE FUNCTION mobius_compile_stats(
10341 IN descriptor JSONB,
10342 OUT probability DOUBLE PRECISION,
10343 OUT n_components INT,
10344 OUT n_cnf_conjuncts INT,
10345 OUT lattice_size INT,
10346 OUT n_nonzero INT,
10347 OUT n_cancelled INT,
10348 OUT cancelled_hard BOOLEAN,
10349 OUT dd_size BIGINT,
10350 OUT memo_hits BIGINT)
10351RETURNS RECORD AS $$
10352DECLARE
10353 legs TEXT; sql TEXT; saved TEXT;
10354 fact_rel INT[]; fact_elems INT[]; fact_arity INT[]; fact_tokens UUID[];
10355 dnv INT[]:='{}'; adisj INT[]:='{}'; arel INT[]:='{}';
10356 avars INT[]:='{}'; aarity INT[]:='{}';
10357 d jsonb; a jsonb; v TEXT; didx INT:=0;
10358BEGIN
10359 FOR d IN SELECT * FROM jsonb_array_elements(descriptor->'disjuncts') LOOP
10360 dnv := dnv || (d->>'n_vars')::INT;
10361 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
10362 adisj := adisj || didx; arel := arel || (a->>'rel')::INT;
10363 aarity := aarity || jsonb_array_length(a->'vars');
10364 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
10365 avars := avars || v::INT;
10366 END LOOP;
10367 END LOOP;
10368 didx := didx + 1;
10369 END LOOP;
10370
10371 SELECT string_agg(
10372 format('SELECT %s, ARRAY[%s]::TEXT[], provsql FROM %s%s',
10373 rn - 1,
10374 (SELECT string_agg(format('(%I)::TEXT', c), ',')
10375 FROM jsonb_array_elements_text(descriptor->'elem_cols'->(rn-1)::INT) c),
10376 rel,
10377 CASE WHEN coalesce(descriptor->'rel_where'->>(rn-1)::INT,'') <> ''
10378 THEN ' WHERE '||(descriptor->'rel_where'->>(rn-1)::INT)
10379 ELSE '' END),
10380 ' UNION ALL ')
10381 INTO legs
10382 FROM jsonb_array_elements_text(descriptor->'relations') WITH ORDINALITY t(rel, rn);
10383
10384 sql := format($q$
10385 WITH facts(rel,elems,tok) AS (%s),
10386 ord AS (SELECT row_number() OVER () AS ord, rel, elems, tok FROM facts),
10387 dict AS (SELECT val, (dense_rank() OVER (ORDER BY val))-1 AS id
10388 FROM (SELECT DISTINCT unnest(elems) AS val FROM facts) u)
10389 SELECT (SELECT array_agg(rel ORDER BY ord) FROM ord),
10390 (SELECT array_agg(cardinality(elems) ORDER BY ord) FROM ord),
10391 (SELECT array_agg(tok ORDER BY ord) FROM ord),
10392 (SELECT array_agg(dd.id ORDER BY o.ord, e.k)
10393 FROM ord o, LATERAL unnest(o.elems) WITH ORDINALITY e(val,k)
10394 JOIN dict dd ON dd.val = e.val)
10395 $q$, legs);
10396
10397 saved := current_setting('provsql.active', true);
10398 PERFORM set_config('provsql.active','off', true);
10399 EXECUTE sql INTO fact_rel, fact_arity, fact_tokens, fact_elems;
10400 PERFORM set_config('provsql.active', saved, true);
10401
10402 SELECT s.probability, s.n_components, s.n_cnf_conjuncts, s.lattice_size,
10403 s.n_nonzero, s.n_cancelled, s.cancelled_hard, s.dd_size, s.memo_hits
10404 INTO probability, n_components, n_cnf_conjuncts, lattice_size,
10405 n_nonzero, n_cancelled, cancelled_hard, dd_size, memo_hits
10406 FROM ucq_mobius_compile_stats(dnv,adisj,arel,avars,aarity,
10407 fact_rel,fact_elems,fact_arity,fact_tokens) s;
10408END;
10409$$ LANGUAGE plpgsql VOLATILE;
10410
10411/**
10412 * @brief Internal gather for the per-answer joint route: parse @p descriptor
10413 * into the columnar UCQ arrays and gather every fact (relation index,
10414 * dense element ids, provenance token) with the value dictionary.
10415 *
10416 * Used only by the planner-substituted @c ucq_joint_provenance_answer (the C
10417 * single-DP entry point), which calls it ONCE per query and then computes all
10418 * answers in one sweep. No head pinning: the single DP discovers the answers.
10419 * @c val_by_id maps a dense element id back to its TEXT value (so an answer's
10420 * head ids can be matched to the @c GROUP @c BY head TEXT).
10421 */
10422CREATE OR REPLACE FUNCTION ucq_joint_gather(
10423 descriptor JSONB,
10424 OUT disjunct_nvars INT[], OUT atom_disjunct INT[], OUT atom_rel INT[],
10425 OUT atom_vars INT[], OUT atom_arity INT[],
10426 OUT fact_rel INT[], OUT fact_elems INT[], OUT fact_arity INT[],
10427 OUT fact_tokens UUID[], OUT val_by_id TEXT[])
10428AS $$
10429DECLARE
10430 legs TEXT; sql TEXT; saved TEXT; d jsonb; a jsonb; v TEXT; didx INT := 0;
10431BEGIN
10432 disjunct_nvars:='{}'; atom_disjunct:='{}'; atom_rel:='{}';
10433 atom_vars:='{}'; atom_arity:='{}';
10434 FOR d IN SELECT * FROM jsonb_array_elements(descriptor->'disjuncts') LOOP
10435 disjunct_nvars := disjunct_nvars || (d->>'n_vars')::INT;
10436 FOR a IN SELECT * FROM jsonb_array_elements(d->'atoms') LOOP
10437 atom_disjunct := atom_disjunct || didx;
10438 atom_rel := atom_rel || (a->>'rel')::INT;
10439 atom_arity := atom_arity || jsonb_array_length(a->'vars');
10440 FOR v IN SELECT * FROM jsonb_array_elements_text(a->'vars') LOOP
10441 atom_vars := atom_vars || v::INT;
10442 END LOOP;
10443 END LOOP;
10444 didx := didx + 1;
10445 END LOOP;
10446
10447 SELECT string_agg(
10448 format('SELECT %s, ARRAY[%s]::TEXT[], provsql FROM %s%s', rn - 1,
10449 (SELECT string_agg(format('(%I)::TEXT', c), ',')
10450 FROM jsonb_array_elements_text(descriptor->'elem_cols'->(rn-1)::INT) c),
10451 rel,
10452 CASE WHEN coalesce(descriptor->'rel_where'->>(rn-1)::INT,'') <> ''
10453 THEN ' WHERE '||(descriptor->'rel_where'->>(rn-1)::INT)
10454 ELSE '' END),
10455 ' UNION ALL ')
10456 INTO legs
10457 FROM jsonb_array_elements_text(descriptor->'relations') WITH ORDINALITY t(rel, rn);
10458
10459 sql := format($q$
10460 WITH facts(rel,elems,tok) AS (%s),
10461 ord AS (SELECT row_number() OVER () AS ord, rel, elems, tok FROM facts),
10462 dict AS (SELECT val, (dense_rank() OVER (ORDER BY val))-1 AS id
10463 FROM (SELECT DISTINCT unnest(elems) AS val FROM facts) u)
10464 SELECT (SELECT array_agg(rel ORDER BY ord) FROM ord),
10465 (SELECT array_agg(cardinality(elems) ORDER BY ord) FROM ord),
10466 (SELECT array_agg(tok ORDER BY ord) FROM ord),
10467 (SELECT array_agg(dd.id ORDER BY o.ord, e.k)
10468 FROM ord o, LATERAL unnest(o.elems) WITH ORDINALITY e(val,k)
10469 JOIN dict dd ON dd.val = e.val),
10470 (SELECT array_agg(val ORDER BY id) FROM dict)
10471 $q$, legs);
10472
10473 saved := current_setting('provsql.active', true);
10474 PERFORM set_config('provsql.active','off', true);
10475 EXECUTE sql INTO fact_rel, fact_arity, fact_tokens, fact_elems, val_by_id;
10476 PERFORM set_config('provsql.active', saved, true);
10477END;
10478$$ LANGUAGE plpgsql VOLATILE;
10479
10480/**
10481 * @brief Per-answer joint-width provenance via the TOP-DOWN single DP
10482 * (planner-substituted, C).
10483 *
10484 * The transparent per-answer rewrite substitutes one call per output group.
10485 * On the FIRST call of a query the function gathers the facts once
10486 * (@c ucq_joint_gather), runs the single DP, and materialises EVERY answer's
10487 * certified d-D into the store, caching @c head_vals -> token in @c fn_extra;
10488 * each subsequent group call is an O(1) lookup -- so the whole GROUP BY costs
10489 * one gather + one decomposition + one sweep, not @p k of each. On any
10490 * decline (joint width too large) the @p fallback token (the normal
10491 * per-answer provenance) is returned, so the query never fails. The answer's
10492 * marginal / Shapley / expectation is then the standard evaluation on the
10493 * returned token -- one pipeline for the whole system.
10494 */
10495CREATE OR REPLACE FUNCTION ucq_joint_provenance_answer(
10496 descriptor JSONB, head_vars INT[], head_vals TEXT[], fallback UUID DEFAULT NULL)
10497RETURNS UUID AS 'provsql','ucq_joint_provenance_answer'
10498LANGUAGE C STABLE;
10499
10500/**
10501 * @brief Per-answer safe-UCQ Möbius provenance (planner-substituted): one
10502 * head-pinned Möbius circuit per output group. On the first call the
10503 * facts are gathered once (ucq_joint_gather) and cached; each group pins
10504 * @p head_vars to @p head_vals and compiles, caching head -> token. On
10505 * any decline returns @p fallback. STABLE: it caches per fn-call
10506 * context, so it is not re-evaluated within one scan.
10507 */
10508CREATE OR REPLACE FUNCTION ucq_mobius_provenance_answer(
10509 descriptor JSONB, head_vars INT[], head_vals TEXT[], fallback UUID DEFAULT NULL)
10510RETURNS UUID AS 'provsql','ucq_mobius_provenance_answer'
10511LANGUAGE C STABLE;
10512
10513
10514/**
10515 * @brief Compile and materialise the reachability provenance of every
10516 * vertex (columnar form, internal)
10517 *
10518 * All-targets variant of @c reachability_evaluate(): compiles, along a
10519 * tree decomposition of the data graph, one certified provenance
10520 * circuit per vertex reachable from some source in the all-edges-present
10521 * world, materialises the (shared, linear-size) circuits in the
10522 * provenance store -- @c plus / @c times gates carrying the d-DNNF
10523 * certificate, negated edges as @c monus(one, edge) -- and returns one
10524 * @c (vertex, token) row per such vertex. Sources form a possibly
10525 * *probabilistic source set*: each source arc is gated by the source
10526 * tuple's token, the nil UUID marking a certain (always present)
10527 * source. This is the engine behind the rewriter's
10528 * recursive-reachability route; the returned tokens are ordinary
10529 * provenance tokens usable with the whole evaluation surface, wrapped
10530 * in the 'absorptive' assumption marker (the compiled circuit is the
10531 * exact Boolean lineage but only the absorptive quotient of the
10532 * infinite recursive semiring provenance: probability and absorptive
10533 * semiring evaluations -- e.g. nonnegative min-plus -- are exact,
10534 * counting and why-provenance refuse).
10535 *
10536 * @param sources source vertex of each edge (dense INTEGER IDs)
10537 * @param destinations destination vertex of each edge
10538 * @param tokens provenance token of each edge tuple
10539 * @param probabilities probability of each edge tuple
10540 * @param block_keys per-edge BID key variable (nil UUID = independent
10541 * tuple; alternatives sharing a key are mutually exclusive, e.g.
10542 * from repair_key)
10543 * @param block_indices per-edge outcome index within its block
10544 * @param source_vertices the source vertices
10545 * @param source_tokens per-source provenance token (nil UUID = certain)
10546 * @param source_probabilities per-source probability
10547 * @param directed if false, each edge can be traversed both ways
10548 * @param[out] vertex a vertex reachable from some source
10549 * @param[out] token the materialised reachability provenance token of @c vertex
10550 */
10551CREATE OR REPLACE FUNCTION reachability_materialize(
10552 IN sources INT[],
10553 IN destinations INT[],
10554 IN tokens UUID[],
10555 IN probabilities DOUBLE PRECISION[],
10556 IN block_keys UUID[],
10557 IN block_indices INT[],
10558 IN source_vertices INT[],
10559 IN source_tokens UUID[],
10560 IN source_probabilities DOUBLE PRECISION[],
10561 IN directed BOOLEAN,
10562 OUT vertex INT,
10563 OUT token UUID)
10564 RETURNS SETOF RECORD AS
10565 'provsql','reachability_materialize' LANGUAGE C VOLATILE;
10566
10567
10568/**
10569 * @brief Bounded-hop variant of @c reachability_materialize() (internal)
10570 *
10571 * Compiles, along a tree decomposition of the data graph, one certified
10572 * provenance circuit per (vertex, walk length) pair achievable within
10573 * @p hop_bound edges -- the rows a hop-counting recursive CTE derives,
10574 * row @c (v,h) meaning "some *walk* of exactly @c h edges connects a
10575 * present source to @c v" -- and returns them as @c (vertex, hops,
10576 * token) with @p hop_seed added to the lengths (the CTE base arm's hop
10577 * constant). Also pre-creates, per vertex, the certified gate that a
10578 * hop-discarding query's deduplication will address, wired to the
10579 * compilation's native within-bound root, so the natural "within k
10580 * hops" probability evaluates through the linear certified route.
10581 *
10582 * @param sources source vertex of each edge (dense INTEGER IDs)
10583 * @param destinations destination vertex of each edge
10584 * @param tokens provenance token of each edge tuple
10585 * @param probabilities probability of each edge tuple
10586 * @param block_keys per-edge BID key variable (nil UUID = independent)
10587 * @param block_indices per-edge outcome index within its block
10588 * @param source_vertices the source vertices
10589 * @param source_tokens per-source provenance token (nil UUID = certain)
10590 * @param source_probabilities per-source probability
10591 * @param directed if false, each edge can be traversed both ways
10592 * @param hop_bound maximum walk length
10593 * @param hop_seed hop value of the base arm (added to reported lengths)
10594 * @param[out] vertex a reachable vertex
10595 * @param[out] hops the walk length at which @c vertex is reached
10596 * @param[out] token the materialised provenance token of the @c (vertex, hops) pair
10597 */
10598CREATE OR REPLACE FUNCTION reachability_materialize_hops(
10599 IN sources INT[],
10600 IN destinations INT[],
10601 IN tokens UUID[],
10602 IN probabilities DOUBLE PRECISION[],
10603 IN block_keys UUID[],
10604 IN block_indices INT[],
10605 IN source_vertices INT[],
10606 IN source_tokens UUID[],
10607 IN source_probabilities DOUBLE PRECISION[],
10608 IN directed BOOLEAN,
10609 IN hop_bound INT,
10610 IN hop_seed INT,
10611 OUT vertex INT,
10612 OUT hops INT,
10613 OUT token UUID)
10614 RETURNS SETOF RECORD AS
10615 'provsql','reachability_materialize_hops' LANGUAGE C VOLATILE;
10616
10617
10618/**
10619 * @brief Per-group "some member reachable" compilation (columnar form,
10620 * internal)
10621 *
10622 * For each distinct group in the parallel @p group_ids /
10623 * @p member_vertices arrays, compiles the certified circuit of "some
10624 * member vertex is reachable from a present source" along the data
10625 * decomposition -- the disjunction over the group's *correlated*
10626 * per-vertex reachability events, deterministic by construction
10627 * through the set-reachability state bit -- materialises it, and
10628 * returns one @c (group_id, token) row per group. Engine behind the
10629 * rewriter's cross-vertex aggregation planting.
10630 *
10631 * @param sources source vertex of each edge (dense INTEGER IDs)
10632 * @param destinations destination vertex of each edge
10633 * @param tokens provenance token of each edge tuple
10634 * @param probabilities probability of each edge tuple
10635 * @param block_keys per-edge BID key variable (nil UUID = independent)
10636 * @param block_indices per-edge outcome index within its block
10637 * @param source_vertices the source vertices
10638 * @param source_tokens per-source provenance token (nil UUID = certain)
10639 * @param source_probabilities per-source probability
10640 * @param directed if false, each edge can be traversed both ways
10641 * @param group_ids group identifier of each member row
10642 * @param member_vertices member vertex of each member row
10643 * @param[out] group_id a group whose every member is reachable
10644 * @param[out] token the materialised all-members-reachable provenance token of
10645 * @c group_id
10646 */
10647CREATE OR REPLACE FUNCTION reachability_materialize_any(
10648 IN sources INT[],
10649 IN destinations INT[],
10650 IN tokens UUID[],
10651 IN probabilities DOUBLE PRECISION[],
10652 IN block_keys UUID[],
10653 IN block_indices INT[],
10654 IN source_vertices INT[],
10655 IN source_tokens UUID[],
10656 IN source_probabilities DOUBLE PRECISION[],
10657 IN directed BOOLEAN,
10658 IN group_ids INT[],
10659 IN member_vertices INT[],
10660 OUT group_id INT,
10661 OUT token UUID)
10662 RETURNS SETOF RECORD AS
10663 'provsql','reachability_materialize_any' LANGUAGE C VOLATILE;
10664
10665/**
10666 * @brief Compile and materialise the "every member vertex reachable"
10667 * (k-terminal / coverage) circuit (columnar form, internal)
10668 *
10669 * Arguments as @c reachability_materialize_any() with a single member
10670 * set: compiles the certified circuit of "every member vertex is
10671 * reachable from a present source" -- the conjunction over the
10672 * members' *correlated* per-vertex events, deterministic by
10673 * construction through the pending rescuer-set congruence --
10674 * materialises it, and returns its token, wrapped in the
10675 * @c 'absorptive' assumption marker. Probability evaluation gives the
10676 * k-terminal reliability; nonnegative min-plus the cost of the
10677 * cheapest covering subgraph (directed Steiner cost), shared edges
10678 * paid once. A member vertex absent from the graph is unreachable:
10679 * the circuit is then constant false.
10680 *
10681 * @param sources source vertex of each edge (dense INTEGER IDs)
10682 * @param destinations destination vertex of each edge
10683 * @param tokens provenance token of each edge tuple
10684 * @param probabilities probability of each edge tuple
10685 * @param block_keys per-edge BID key variable (nil UUID = independent)
10686 * @param block_indices per-edge outcome index within its block
10687 * @param source_vertices the source vertices
10688 * @param source_tokens per-source provenance token (nil UUID = certain)
10689 * @param source_probabilities per-source probability
10690 * @param directed if false, each edge can be traversed both ways
10691 * @param member_vertices the member vertices (dense IDs)
10692 */
10693CREATE OR REPLACE FUNCTION reachability_materialize_cover(
10694 sources INT[],
10695 destinations INT[],
10696 tokens UUID[],
10697 probabilities DOUBLE PRECISION[],
10698 block_keys UUID[],
10699 block_indices INT[],
10700 source_vertices INT[],
10701 source_tokens UUID[],
10702 source_probabilities DOUBLE PRECISION[],
10703 directed BOOLEAN,
10704 member_vertices INT[])
10705 RETURNS UUID AS
10706 'provsql','reachability_materialize_cover' LANGUAGE C VOLATILE;
10707
10708/**
10709 * @brief Plant certified any-member-reachable gates for a grouped
10710 * reachability aggregation (internal)
10711 *
10712 * Called (at plan time, over SPI) by the recursive-CTE lowering when
10713 * the outer query aggregates a reachability working table by a column
10714 * of a joined, untracked member relation: @c GROUP @c BY collapses
10715 * each group's per-vertex reach tokens with @c provenance_plus, whose
10716 * disjuncts are correlated (they share edges) and would otherwise
10717 * leave the certified route. For each multi-member group this
10718 * pre-creates, at the canonical address of the group's token multiset,
10719 * a certified single-child plus over the group's native
10720 * any-member-reachable circuit (@c reachability_materialize_any), so
10721 * the natural aggregation stays on the linear evaluation route.
10722 * Best-effort: any failure leaves the generic path untouched (notice
10723 * under verbosity 10).
10724 *
10725 * @param work_name the lowered CTE's working table
10726 * @param node_attribute its vertex column
10727 * @param member_rel the joined member relation (must be untracked)
10728 * @param member_attribute the member relation's join column
10729 * @param group_attribute the member relation's grouping column
10730 * @param edge_rel the tracked edge relation (as for eval_reachability)
10731 * @param source_attribute name of the source-vertex column
10732 * @param destination_attribute name of the destination-vertex column
10733 * @param source_value the base arm's constant, as TEXT
10734 * @param directed if false, each edge can be traversed both ways
10735 * @param edge_quals optional deterministic filter over edge columns
10736 * @param source_rel source relation of a multi-source base arm
10737 * @param source_rel_attribute the source relation's vertex column
10738 * @param edge_sql deparsed edge subquery (join-defined edges)
10739 * @param member_quals optional deterministic filter over the member
10740 * relation's columns (table-qualified as @c t.column), restricting
10741 * which members participate in each group
10742 */
10743CREATE OR REPLACE FUNCTION plant_reach_any_groups(
10744 work_name TEXT,
10745 node_attribute TEXT,
10746 member_rel REGCLASS,
10747 member_attribute TEXT,
10748 group_attribute TEXT,
10749 edge_rel REGCLASS,
10750 source_attribute TEXT,
10751 destination_attribute TEXT,
10752 source_value TEXT,
10753 directed BOOLEAN,
10754 edge_quals TEXT DEFAULT NULL,
10755 source_rel REGCLASS DEFAULT NULL,
10756 source_rel_attribute TEXT DEFAULT NULL,
10757 edge_sql TEXT DEFAULT NULL,
10758 member_quals TEXT DEFAULT NULL)
10759 RETURNS VOID AS
10760$$
10761DECLARE
10762 e RECORD;
10763 grp RECORD;
10764 m RECORD;
10765 sv TEXT[];
10766 st UUID[];
10767 sp double precision[];
10768 gids INT[] := ARRAY[]::INT[];
10769 mids INT[] := ARRAY[]::INT[];
10770 vid INT;
10771 verbosity INT := coalesce(current_setting('provsql.verbose_level', true)::INT, 0);
10772BEGIN
10773 BEGIN
10774 -- A tracked member relation would make the aggregated tokens
10775 -- per-row products, not the bare reach tokens: nothing to plant.
10776 IF EXISTS (SELECT 1 FROM pg_attribute
10777 WHERE attrelid = member_rel AND attname = 'provsql'
10778 AND atttypid = 'UUID'::REGTYPE AND NOT attisdropped) THEN
10779 RETURN;
10780 END IF;
10781
10782 IF source_rel IS NOT NULL THEN
10783 SELECT g.source_values, g.source_tokens, g.source_probabilities
10784 INTO sv, st, sp
10785 FROM provsql.gather_reachability_sources(source_rel,
10786 source_rel_attribute) g;
10787 IF sv IS NULL THEN
10788 sv := ARRAY[]::TEXT[];
10789 st := ARRAY[]::UUID[];
10790 sp := ARRAY[]::float8[];
10791 END IF;
10792 ELSE
10793 sv := ARRAY[source_value];
10794 st := ARRAY['00000000-0000-0000-0000-000000000000'::UUID];
10795 sp := ARRAY[1.0::float8];
10796 END IF;
10797
10798 e := provsql.gather_reachability_edges(edge_rel, source_attribute,
10799 destination_attribute,
10800 sv, edge_quals, edge_sql);
10801
10802 -- The groups, replicating the user's join semantics: per group, the
10803 -- member vertices and the multiset of their reach tokens (with the
10804 -- multiplicity the join produces). Single-member groups need no
10805 -- planting (provenance_plus passes a single token through).
10806 -- Two steps: materialise the joined rows with their per-row tokens
10807 -- (tracked CTAS, then strip the automatic provsql column), and only
10808 -- then aggregate the now-plain table -- aggregating provenance()
10809 -- inside a grouped tracked query would be rewritten as a
10810 -- provenance-aware aggregation, which is not what the planting
10811 -- needs.
10812 DROP TABLE IF EXISTS provsql_reach_any_flat_tmp;
10813 EXECUTE format(
10814 'CREATE TEMP TABLE provsql_reach_any_flat_tmp AS '
10815 || 'SELECT w.%1$I::TEXT AS node_val, provsql.provenance() AS tok, '
10816 || ' t.%5$I AS grp_key '
10817 || 'FROM %2$I w JOIN %3$s t ON w.%1$I = t.%4$I'
10818 -- The member-relation filter restricts which members participate
10819 -- (deparsed table-qualified as t.column); the working table side
10820 -- carries no provenance distinction here.
10821 || coalesce(' WHERE ' || member_quals, ''),
10822 node_attribute, work_name, member_rel::TEXT, member_attribute,
10823 group_attribute);
10824 PERFORM provsql.remove_provenance('provsql_reach_any_flat_tmp');
10825 DROP TABLE IF EXISTS provsql_reach_any_groups_tmp;
10826 CREATE TEMP TABLE provsql_reach_any_groups_tmp AS
10827 SELECT (row_number() OVER ())::INT AS gid, members, toks FROM (
10828 SELECT array_agg(node_val) AS members, array_agg(tok) AS toks
10829 FROM provsql_reach_any_flat_tmp
10830 GROUP BY grp_key HAVING count(*) >= 2) g;
10831 DROP TABLE provsql_reach_any_flat_tmp;
10832
10833 FOR grp IN SELECT gid, members FROM provsql_reach_any_groups_tmp LOOP
10834 FOR m IN SELECT DISTINCT unnest(grp.members) AS val LOOP
10835 vid := array_position(e.vertices, m.val);
10836 IF vid IS NOT NULL THEN
10837 gids := gids || grp.gid;
10838 mids := mids || vid;
10839 END IF;
10840 END LOOP;
10841 END LOOP;
10842 IF cardinality(gids) = 0 THEN
10843 DROP TABLE provsql_reach_any_groups_tmp;
10844 RETURN;
10845 END IF;
10846
10847 FOR grp IN
10848 SELECT a.group_id, a.token AS any_token, t.toks
10849 FROM provsql.reachability_materialize_any(
10850 e.sources, e.destinations, e.tokens, e.probabilities,
10851 e.block_keys, e.block_indices, e.extra_ids, st, sp,
10852 directed, gids, mids) a
10853 JOIN provsql_reach_any_groups_tmp t ON t.gid = a.group_id
10854 LOOP
10855 PERFORM provsql.plant_canonical(work_name, 'plus', grp.toks,
10856 grp.any_token, 1);
10857 END LOOP;
10858 DROP TABLE provsql_reach_any_groups_tmp;
10859 IF verbosity >= 20 THEN
10860 -- Lift the function-level client_min_messages = warning for the
10861 -- one RAISE; the function-level SET restores the caller's value.
10862 PERFORM set_config('client_min_messages', 'notice', true);
10863 RAISE NOTICE 'ProvSQL: certified any-member gates planted for the aggregation of "%" by %.%',
10864 work_name, member_rel, group_attribute;
10865 PERFORM set_config('client_min_messages', 'warning', true);
10866 END IF;
10867 EXCEPTION WHEN OTHERS THEN
10868 IF verbosity >= 10 THEN
10869 PERFORM set_config('client_min_messages', 'notice', true);
10870 RAISE NOTICE 'ProvSQL: any-member planting for "%" skipped (%)',
10871 work_name, SQLERRM;
10872 PERFORM set_config('client_min_messages', 'warning', true);
10873 END IF;
10874 END;
10875END
10876-- No SET search_path: the deparsed edge subquery must resolve against
10877-- the caller's path; ProvSQL internals are schema-qualified.
10878$$ LANGUAGE plpgsql SET client_min_messages = warning;
10879
10880/**
10881 * @brief Plant the certified all-members-reachable gate for a
10882 * reachability self-join conjunction (internal)
10883 *
10884 * Called (at plan time, over SPI) by the recursive-CTE lowering when
10885 * the outer query self-joins a reachability working table with one
10886 * constant node binding per reference -- "are these k vertices all
10887 * reachable" -- whose row provenance @c provenance_times() computes as
10888 * the product of *correlated* per-vertex reach tokens (they share
10889 * edges). This pre-creates, at the times-canonical address of that
10890 * token multiset, a certified single-child times over the native
10891 * all-members-reachable circuit (@c reachability_materialize_cover),
10892 * so the natural conjunction stays on the linear certified route --
10893 * with the joint-worlds semantics: probability evaluation gives the
10894 * k-terminal reliability, and nonnegative min-plus the cost of the
10895 * cheapest covering subgraph (directed Steiner cost), shared edges
10896 * paid once where the raw product would pay them once per factor.
10897 * Best-effort: any failure leaves the generic path untouched (notice
10898 * under verbosity 10).
10899 *
10900 * @param work_name the lowered CTE's working table
10901 * @param node_attribute its vertex column
10902 * @param edge_rel the tracked edge relation (as for eval_reachability)
10903 * @param source_attribute name of the source-vertex column
10904 * @param destination_attribute name of the destination-vertex column
10905 * @param source_value the base arm's constant, as TEXT
10906 * @param directed if false, each edge can be traversed both ways
10907 * @param node_values the constant node bindings, as TEXT (multiset:
10908 * one per self-join reference)
10909 * @param edge_quals optional deterministic filter over edge columns
10910 * @param source_rel source relation of a multi-source base arm
10911 * @param source_rel_attribute the source relation's vertex column
10912 * @param edge_sql deparsed edge subquery (join-defined edges)
10913 */
10914CREATE OR REPLACE FUNCTION plant_reach_cover(
10915 work_name TEXT,
10916 node_attribute TEXT,
10917 edge_rel REGCLASS,
10918 source_attribute TEXT,
10919 destination_attribute TEXT,
10920 source_value TEXT,
10921 directed BOOLEAN,
10922 node_values TEXT[],
10923 edge_quals TEXT DEFAULT NULL,
10924 source_rel REGCLASS DEFAULT NULL,
10925 source_rel_attribute TEXT DEFAULT NULL,
10926 edge_sql TEXT DEFAULT NULL)
10927 RETURNS VOID AS
10928$$
10929DECLARE
10930 e RECORD;
10931 sv TEXT[];
10932 st UUID[];
10933 sp double precision[];
10934 val TEXT;
10935 vid INT;
10936 vids INT[] := ARRAY[]::INT[];
10937 tok UUID;
10938 toks UUID[] := ARRAY[]::UUID[];
10939 cover_token UUID;
10940 verbosity INT := coalesce(current_setting('provsql.verbose_level', true)::INT, 0);
10941BEGIN
10942 BEGIN
10943 IF source_rel IS NOT NULL THEN
10944 SELECT g.source_values, g.source_tokens, g.source_probabilities
10945 INTO sv, st, sp
10946 FROM provsql.gather_reachability_sources(source_rel,
10947 source_rel_attribute) g;
10948 IF sv IS NULL THEN
10949 sv := ARRAY[]::TEXT[];
10950 st := ARRAY[]::UUID[];
10951 sp := ARRAY[]::float8[];
10952 END IF;
10953 ELSE
10954 sv := ARRAY[source_value];
10955 st := ARRAY['00000000-0000-0000-0000-000000000000'::UUID];
10956 sp := ARRAY[1.0::float8];
10957 END IF;
10958
10959 e := provsql.gather_reachability_edges(edge_rel, source_attribute,
10960 destination_attribute,
10961 sv, edge_quals, edge_sql);
10962
10963 -- The bound vertices and their per-row reach tokens, with the
10964 -- multiplicity the self-join produces. A vertex absent from the
10965 -- graph, or from the working table, means the join is empty: no
10966 -- row will exist, nothing to plant.
10967 FOREACH val IN ARRAY node_values LOOP
10968 vid := array_position(e.vertices, val);
10969 IF vid IS NULL THEN
10970 RETURN;
10971 END IF;
10972 vids := vids || vid;
10973 EXECUTE format('SELECT provsql FROM %I WHERE %I::TEXT = $1',
10974 work_name, node_attribute)
10975 INTO tok USING val;
10976 IF tok IS NULL THEN
10977 RETURN;
10978 END IF;
10979 toks := toks || tok;
10980 END LOOP;
10981
10982 cover_token := provsql.reachability_materialize_cover(
10983 e.sources, e.destinations, e.tokens, e.probabilities,
10984 e.block_keys, e.block_indices, e.extra_ids, st, sp,
10985 directed, vids);
10986
10987 PERFORM provsql.plant_canonical(work_name, 'times', toks, cover_token, 1);
10988 IF verbosity >= 20 THEN
10989 -- Lift the function-level client_min_messages = warning for the
10990 -- one RAISE; the function-level SET restores the caller's value.
10991 PERFORM set_config('client_min_messages', 'notice', true);
10992 RAISE NOTICE 'ProvSQL: certified all-members gate planted for the self-join of "%"',
10993 work_name;
10994 PERFORM set_config('client_min_messages', 'warning', true);
10995 END IF;
10996 EXCEPTION WHEN OTHERS THEN
10997 IF verbosity >= 10 THEN
10998 PERFORM set_config('client_min_messages', 'notice', true);
10999 RAISE NOTICE 'ProvSQL: all-members planting for "%" skipped (%)',
11000 work_name, SQLERRM;
11001 PERFORM set_config('client_min_messages', 'warning', true);
11002 END IF;
11003 END;
11004END
11005-- No SET search_path: the deparsed edge subquery must resolve against
11006-- the caller's path; ProvSQL internals are schema-qualified.
11007$$ LANGUAGE plpgsql SET client_min_messages = warning;
11008
11009/**
11010 * @brief Input leaves of a conjunction-shaped provenance token (internal)
11011 *
11012 * Descends a token's circuit through the conjunctive gate types
11013 * (@c times, and the pass-through @c project / @c eq where-provenance
11014 * wrappers) down to @c input leaves. Returns the distinct leaves, or
11015 * NULL when the circuit contains any other gate type (a disjunctive or
11016 * aggregate shape, which is not a conjunction of independent tuples).
11017 * Used by the reachability gathering to accept join-defined edges:
11018 * a derived edge whose token is a pure conjunction of base tuples.
11019 *
11020 * @param token the provenance token
11021 */
11022CREATE OR REPLACE FUNCTION token_conjunctive_leaves(token UUID)
11023 RETURNS UUID[] AS
11024$$
11025WITH RECURSIVE walk(g) AS (
11026 SELECT token
11027 UNION
11028 SELECT c FROM walk w, unnest(provsql.get_children(w.g)) AS c
11029 WHERE provsql.get_gate_type(w.g) IN ('times', 'project', 'eq', 'annotation')
11030)
11031SELECT CASE WHEN bool_and(provsql.get_gate_type(g)
11032 IN ('times', 'project', 'eq', 'annotation', 'input'))
11033 THEN array_agg(DISTINCT g)
11034 FILTER (WHERE provsql.get_gate_type(g) = 'input')
11035 ELSE NULL END
11036FROM walk;
11037$$ LANGUAGE sql STABLE;
11038
11039/**
11040 * @brief Gather the edges of a tracked relation in the columnar form
11041 * expected by reachability_evaluate (internal)
11042 *
11043 * Materializes the edge relation with its provenance tokens and
11044 * probabilities, maps arbitrary vertex values (compared as TEXT) onto
11045 * dense INTEGER IDs, and checks that every edge tuple carries a base
11046 * input token (independent tuples): reachability compilation along the
11047 * data is only correct when the edges are independent events, so views
11048 * or query results with derived provenance are rejected.
11049 *
11050 * @param rel the provenance-tracked edge relation
11051 * @param source_attribute name of the source-vertex column
11052 * @param destination_attribute name of the destination-vertex column
11053 * @param extra_vertices vertex values (as TEXT) that must be part of
11054 * the dense ID space even when they touch no edge -- the source
11055 * set in particular; their IDs come back in @c extra_ids
11056 * (aligned with the input)
11057 * @param edge_quals optional deterministic filter over the edge
11058 * relation's columns (SQL TEXT, deparsed by the rewriter from
11059 * the recursive arm's WHERE clause), restricting which edges
11060 * participate
11061 * @param rel_sql deparsed edge subquery to gather from instead of
11062 * @p rel (join-defined edges); the tokens are then conjunctions
11063 * of base tuples, validated for shape and disjoint supports
11064 *
11065 * The @c vertices output maps the dense IDs back to the original
11066 * vertex values (as TEXT, 1-indexed), for callers that need to label
11067 * per-vertex results.
11068 *
11069 * @param[out] sources source vertex (dense ID) of each gathered edge
11070 * @param[out] destinations destination vertex (dense ID) of each edge
11071 * @param[out] tokens provenance token of each edge tuple
11072 * @param[out] probabilities probability of each edge tuple
11073 * @param[out] block_keys per-edge BID key variable (nil UUID = independent)
11074 * @param[out] block_indices per-edge outcome index within its block
11075 * @param[out] extra_ids dense IDs assigned to the @p extra_vertices
11076 * @param[out] vertices dense-ID-to-original-value map (TEXT, 1-indexed)
11077 */
11078CREATE OR REPLACE FUNCTION gather_reachability_edges(
11079 IN rel REGCLASS,
11080 IN source_attribute TEXT,
11081 IN destination_attribute TEXT,
11082 IN extra_vertices TEXT[],
11083 IN edge_quals TEXT DEFAULT NULL,
11084 IN rel_sql TEXT DEFAULT NULL,
11085 OUT sources INT[],
11086 OUT destinations INT[],
11087 OUT tokens UUID[],
11088 OUT probabilities DOUBLE PRECISION[],
11089 OUT block_keys UUID[],
11090 OUT block_indices INT[],
11091 OUT extra_ids INT[],
11092 OUT vertices TEXT[])
11093AS
11094$$
11095DECLARE
11096 tkind TEXT;
11097 bkey_expr TEXT;
11098 sel_probs TEXT;
11099 sel_bkeys TEXT;
11100 sel_bidx TEXT;
11101 verbosity INT := coalesce(current_setting('provsql.verbose_level', true)::INT, 0);
11102BEGIN
11103 -- Consult the per-table characterisation registry (TID / BID / OPAQUE,
11104 -- maintained by add_provenance / repair_key and the CTAS lineage hook):
11105 -- a TID relation is certified all-independent-inputs, a BID relation
11106 -- holds input or mulinput rows with the block structure given by the
11107 -- registry's key columns. Derived (OPAQUE), unregistered, or
11108 -- subquery-defined edges take the fully dynamic per-token path.
11109 IF rel IS NOT NULL AND rel_sql IS NULL THEN
11110 tkind := (provsql.get_table_info(rel::oid)).kind;
11111 END IF;
11112 IF tkind NOT IN ('tid', 'bid') THEN
11113 tkind := NULL;
11114 END IF;
11115 IF tkind = 'bid' THEN
11116 SELECT string_agg(quote_ident(a.attname) || '::TEXT', ' || '','' || '
11117 ORDER BY k.ord)
11118 INTO bkey_expr
11119 FROM unnest((provsql.get_table_info(rel::oid)).block_key)
11120 WITH ORDINALITY AS k(attnum, ord)
11121 JOIN pg_attribute a ON a.attrelid = rel AND a.attnum = k.attnum;
11122 -- An empty registry key means the whole table is one block.
11123 bkey_expr := coalesce(bkey_expr, quote_literal(''));
11124 END IF;
11125 IF tkind IS NOT NULL AND verbosity >= 20 THEN
11126 -- The function-level client_min_messages = warning (which silences
11127 -- the CTAS / DROP TABLE chatter) would also swallow this notice;
11128 -- lift it for the one RAISE. The function-level SET restores the
11129 -- caller's value at exit regardless.
11130 PERFORM set_config('client_min_messages', 'notice', true);
11131 RAISE NOTICE 'ProvSQL: catalog characterises % as %', rel, upper(tkind);
11132 PERFORM set_config('client_min_messages', 'warning', true);
11133 END IF;
11134
11135 -- Materialize the edges with their tokens; the planner hook resolves
11136 -- provenance() over the tracked relation, and remove_provenance strips
11137 -- the automatic provsql column so the later aggregation is plain SQL.
11138 -- For a BID relation the synthetic per-block key (a v5 UUID over the
11139 -- registry key columns' values) is computed here, while the columns
11140 -- are in scope.
11141 DROP TABLE IF EXISTS provsql_reachability_edges_tmp;
11142 EXECUTE format(
11143 'CREATE TEMP TABLE provsql_reachability_edges_tmp AS '
11144 || 'SELECT %1$I::TEXT AS u, %2$I::TEXT AS v, '
11145 || 'provsql.strip_annotations(provsql.provenance()) AS token%5$s '
11146 || 'FROM %3$s WHERE %1$I IS NOT NULL AND %2$I IS NOT NULL%4$s',
11147 source_attribute, destination_attribute,
11148 CASE WHEN rel_sql IS NULL THEN rel::TEXT
11149 ELSE '(' || rel_sql || ') AS provsql_edge_subquery' END,
11150 CASE WHEN edge_quals IS NULL THEN ''
11151 ELSE ' AND (' || edge_quals || ')' END,
11152 CASE WHEN tkind = 'bid'
11153 THEN ', public.uuid_generate_v5(provsql.uuid_ns_provsql(), '
11154 || quote_literal('bidblock' || rel::TEXT || ':')
11155 || ' || ' || bkey_expr || ') AS bkey'
11156 ELSE ', NULL::UUID AS bkey' END);
11157 PERFORM provsql.remove_provenance('provsql_reachability_edges_tmp');
11158
11159 DROP TABLE IF EXISTS provsql_reachability_support_tmp;
11160 IF tkind IS NULL THEN
11161 -- Dynamic path: validate the token shapes and, for conjunction-shaped
11162 -- (join-defined) tokens, the pairwise disjointness of their supports.
11163 IF EXISTS (SELECT 1 FROM provsql_reachability_edges_tmp
11164 WHERE provsql.get_gate_type(token) NOT IN ('input', 'mulinput', 'times',
11165 'project', 'eq')) THEN
11166 DROP TABLE provsql_reachability_edges_tmp;
11167 RAISE EXCEPTION 'reachability: the provenance of % must consist of base input, repair_key, or conjunctive join tokens', coalesce(rel::TEXT, 'the edge query')
11168 USING ERRCODE = 'feature_not_supported',
11169 DETAIL = 'provsql-reason: reachability-provenance-shape; scope: gap';
11170 END IF;
11171 CREATE TEMP TABLE provsql_reachability_support_tmp AS
11172 SELECT t.token, l.leaf
11173 FROM (SELECT DISTINCT token FROM provsql_reachability_edges_tmp
11174 WHERE provsql.get_gate_type(token) IN ('times', 'project', 'eq')) t,
11175 LATERAL unnest(provsql.token_conjunctive_leaves(t.token)) AS l(leaf);
11176 IF EXISTS (SELECT 1
11177 FROM (SELECT DISTINCT token FROM provsql_reachability_edges_tmp) t
11178 WHERE provsql.get_gate_type(t.token) IN ('times', 'project', 'eq')
11179 AND provsql.token_conjunctive_leaves(t.token) IS NULL) THEN
11180 DROP TABLE provsql_reachability_support_tmp;
11181 DROP TABLE provsql_reachability_edges_tmp;
11182 RAISE EXCEPTION 'reachability: a join-defined edge token is not a pure conjunction of base tuples'
11183 USING ERRCODE = 'feature_not_supported',
11184 DETAIL = 'provsql-reason: reachability-edge-not-conjunction; scope: gap';
11185 END IF;
11186 IF EXISTS (SELECT 1 FROM (
11187 SELECT leaf FROM provsql_reachability_support_tmp
11188 UNION ALL
11189 SELECT DISTINCT token FROM provsql_reachability_edges_tmp
11190 WHERE provsql.get_gate_type(token) = 'input'
11191 ) all_leaves
11192 GROUP BY leaf HAVING count(*) > 1) THEN
11193 DROP TABLE provsql_reachability_support_tmp;
11194 DROP TABLE provsql_reachability_edges_tmp;
11195 RAISE EXCEPTION 'reachability: join-defined edges share base tuples (their supports overlap), so they are not independent'
11196 USING ERRCODE = 'feature_not_supported',
11197 DETAIL = 'provsql-reason: reachability-edges-share-tuples; scope: gap';
11198 END IF;
11199 END IF;
11200
11201 -- Per-kind classification expressions for the final aggregation: a TID
11202 -- relation needs no per-row gate introspection at all; a BID relation
11203 -- one get_gate_type per row (the input/mulinput split), block keys from
11204 -- the precomputed column-derived key and indices by numbering within
11205 -- the block; the dynamic path reads the gates.
11206 IF tkind = 'tid' THEN
11207 sel_probs := 'coalesce(provsql.get_prob(e.token), 1.0)';
11208 sel_bkeys := $sql$'00000000-0000-0000-0000-000000000000'::UUID$sql$;
11209 sel_bidx := '0';
11210 ELSIF tkind = 'bid' THEN
11211 sel_probs := 'coalesce(provsql.get_prob(e.token), 1.0)';
11212 sel_bkeys := $sql$CASE WHEN provsql.get_gate_type(e.token) = 'mulinput'
11213 THEN e.bkey
11214 ELSE '00000000-0000-0000-0000-000000000000'::UUID END$sql$;
11215 sel_bidx := 'e.bidx';
11216 ELSE
11217 sel_probs := $sql$CASE WHEN provsql.get_gate_type(e.token) IN ('times','project','eq')
11218 THEN (SELECT CASE WHEN bool_or(coalesce(provsql.get_prob(s.leaf),1.0) = 0)
11219 THEN 0.0
11220 ELSE exp(sum(ln(coalesce(provsql.get_prob(s.leaf),1.0)))) END
11221 FROM provsql_reachability_support_tmp s
11222 WHERE s.token = e.token)
11223 ELSE coalesce(provsql.get_prob(e.token), 1.0) END$sql$;
11224 sel_bkeys := $sql$CASE WHEN provsql.get_gate_type(e.token) = 'mulinput'
11225 THEN (provsql.get_children(e.token))[1]
11226 ELSE '00000000-0000-0000-0000-000000000000'::UUID END$sql$;
11227 sel_bidx := $sql$CASE WHEN provsql.get_gate_type(e.token) = 'mulinput'
11228 THEN (provsql.get_infos(e.token)).info1 ELSE 0 END$sql$;
11229 END IF;
11230
11231 EXECUTE format(
11232 $sql$
11233 WITH verts AS (
11234 SELECT u AS x FROM provsql_reachability_edges_tmp
11235 UNION SELECT v FROM provsql_reachability_edges_tmp
11236 UNION SELECT unnest($1)),
11237 ids AS (
11238 SELECT x, (row_number() OVER (ORDER BY x))::INT AS id FROM verts)
11239 SELECT array_agg(iu.id), array_agg(iv.id),
11240 array_agg(e.token),
11241 array_agg(%s),
11242 array_agg(%s),
11243 array_agg(%s),
11244 (SELECT array_agg(i.id ORDER BY ev.ord)
11245 FROM unnest($1) WITH ORDINALITY AS ev(x, ord)
11246 JOIN ids i ON i.x = ev.x),
11247 (SELECT array_agg(x ORDER BY id) FROM ids)
11248 FROM (SELECT t.*,
11249 (row_number() OVER (PARTITION BY t.bkey))::INT AS bidx
11250 FROM provsql_reachability_edges_tmp t) e
11251 JOIN ids iu ON iu.x = e.u
11252 JOIN ids iv ON iv.x = e.v
11253 $sql$, sel_probs, sel_bkeys, sel_bidx)
11254 INTO sources, destinations, tokens, probabilities, block_keys,
11255 block_indices, extra_ids, vertices
11256 USING extra_vertices;
11257
11258 DROP TABLE provsql_reachability_edges_tmp;
11259 DROP TABLE IF EXISTS provsql_reachability_support_tmp;
11260END
11261-- No SET search_path: the deparsed edge subquery (and the REGCLASS
11262-- rendering) must resolve against the caller's search_path; the ProvSQL
11263-- calls above are schema-qualified instead.
11264$$ LANGUAGE plpgsql SET client_min_messages = warning;
11265
11266
11267/**
11268 * @brief Gather a source relation's vertices, tokens and probabilities
11269 * (internal)
11270 *
11271 * For a provenance-tracked source relation, every tuple must carry a
11272 * base @c input token (a *probabilistic source set*); for an untracked
11273 * relation the sources are certain and the tokens come back as the nil
11274 * UUID. Vertex values are returned as TEXT, for the shared dense-ID
11275 * mapping of @c gather_reachability_edges().
11276 *
11277 * @param rel the source relation
11278 * @param source_attribute name of the vertex column
11279 * @param[out] source_values vertex value of each source tuple (as TEXT)
11280 * @param[out] source_tokens per-source base @c input token (nil UUID = certain)
11281 * @param[out] source_probabilities per-source probability
11282 */
11283CREATE OR REPLACE FUNCTION gather_reachability_sources(
11284 IN rel REGCLASS,
11285 IN source_attribute TEXT,
11286 OUT source_values TEXT[],
11287 OUT source_tokens UUID[],
11288 OUT source_probabilities DOUBLE PRECISION[])
11289AS
11290$$
11291DECLARE
11292 tracked BOOLEAN;
11293 tkind TEXT;
11294BEGIN
11295 SELECT EXISTS (
11296 SELECT 1 FROM pg_attribute
11297 WHERE attrelid = rel AND attname = 'provsql'
11298 AND atttypid = 'UUID'::REGTYPE AND NOT attisdropped)
11299 INTO tracked;
11300
11301 -- Registry consultation: a TID source relation is certified
11302 -- all-base-input, so the per-row gate check can be skipped; a BID one
11303 -- holds block-correlated tuples, which a probabilistic source set
11304 -- cannot model -- reject it before gathering anything.
11305 IF tracked THEN
11306 tkind := (get_table_info(rel::oid)).kind;
11307 IF tkind = 'bid' THEN
11308 RAISE EXCEPTION 'reachability: % is block-independent (repair_key); block-correlated source sets are not supported', rel
11309 USING ERRCODE = 'feature_not_supported',
11310 DETAIL = 'provsql-reason: reachability-block-correlated; scope: gap';
11311 END IF;
11312 END IF;
11313
11314 DROP TABLE IF EXISTS provsql_reachability_sources_tmp;
11315 IF tracked THEN
11316 EXECUTE format(
11317 'CREATE TEMP TABLE provsql_reachability_sources_tmp AS '
11318 || 'SELECT %1$I::TEXT AS x, provenance() AS token '
11319 || 'FROM %2$s WHERE %1$I IS NOT NULL',
11320 source_attribute, rel);
11321 PERFORM remove_provenance('provsql_reachability_sources_tmp');
11322 IF tkind IS DISTINCT FROM 'tid'
11323 AND EXISTS (SELECT 1 FROM provsql_reachability_sources_tmp
11324 WHERE get_gate_type(token) <> 'input') THEN
11325 DROP TABLE provsql_reachability_sources_tmp;
11326 RAISE EXCEPTION 'reachability: the provenance of % must consist of base input tokens (independent tuples); views or query results are not supported', rel
11327 USING ERRCODE = 'feature_not_supported',
11328 DETAIL = 'provsql-reason: reachability-not-base-inputs; scope: gap';
11329 END IF;
11330 SELECT array_agg(x), array_agg(token),
11331 array_agg(coalesce(get_prob(token), 1.0))
11332 INTO source_values, source_tokens, source_probabilities
11333 FROM provsql_reachability_sources_tmp;
11334 DROP TABLE provsql_reachability_sources_tmp;
11335 ELSE
11336 EXECUTE format(
11337 'CREATE TEMP TABLE provsql_reachability_sources_tmp AS '
11338 || 'SELECT DISTINCT %1$I::TEXT AS x FROM %2$s WHERE %1$I IS NOT NULL',
11339 source_attribute, rel);
11340 SELECT array_agg(x),
11341 array_agg('00000000-0000-0000-0000-000000000000'::UUID),
11342 array_agg(1.0::float8)
11343 INTO source_values, source_tokens, source_probabilities
11344 FROM provsql_reachability_sources_tmp;
11345 DROP TABLE provsql_reachability_sources_tmp;
11346 END IF;
11347END
11348$$ LANGUAGE plpgsql SET search_path=provsql,pg_temp,public SET client_min_messages = warning;
11349
11350/**
11351 * @brief Fixpoint driver for the recursive reachability shape:
11352 * decomposition-aligned compilation with fallback to eval_recursive_system
11353 *
11354 * Called (at plan time, over SPI) by the recursive-CTE lowering when
11355 * the provenance class is 'absorptive' or 'BOOLEAN'
11356 * (@c provsql.provenance) and the CTE matches the linear
11357 * reachability shape over a tracked base edge relation. Attempts the
11358 * decomposition-aligned route -- gather the edges, compile every
11359 * reachable vertex's certified provenance circuit along a tree
11360 * decomposition of the data graph, materialise them, and fill the
11361 * working table with one tokenised row per reachable vertex. On any
11362 * failure (data treewidth above the cap, per-node state bound, edges
11363 * that are not independent base tuples...), falls back to the generic
11364 * @c eval_recursive_system() driver, preserving its behaviour exactly.
11365 *
11366 * @param edge_rel the provenance-tracked edge relation
11367 * @param source_attribute name of the source-vertex column
11368 * @param destination_attribute name of the destination-vertex column
11369 * @param source_value the base arm's constant, as TEXT
11370 * @param directed if false, each edge can be traversed both ways
11371 * @param work_name name of the working temp table (the CTE name)
11372 * @param colnames comma-separated user column names (for the fallback)
11373 * @param coldef column definitions of the working table
11374 * @param coltype type of the CTE's single column
11375 * @param body_sql deparsed CTE body (for the fallback)
11376 * @param edge_quals optional deterministic filter over edge columns
11377 * (deparsed from the recursive arm's WHERE clause)
11378 * @param source_rel source relation of a multi-source base arm
11379 * (@c SELECT col FROM sources), NULL for the constant form;
11380 * tracked sources form a probabilistic source set, untracked
11381 * ones are certain
11382 * @param source_rel_attribute the source relation's vertex column
11383 * @param edge_sql deparsed edge subquery when the recursive arm joins a
11384 * derived (join-defined) edge relation instead of a base one;
11385 * NULL for the REGCLASS form
11386 * @param hop_bound maximum number of recursive steps for the
11387 * hop-counting CTE shape (NULL for plain reachability)
11388 * @param hop_seed the base arm's hop constant (hop-counting shape)
11389 * @param hops_position 1-based position of the hop column among the
11390 * CTE's two columns (hop-counting shape)
11391 */
11392CREATE OR REPLACE FUNCTION eval_reachability(
11393 edge_rel REGCLASS,
11394 source_attribute TEXT,
11395 destination_attribute TEXT,
11396 source_value TEXT,
11397 directed BOOLEAN,
11398 work_name TEXT,
11399 colnames TEXT,
11400 coldef TEXT,
11401 coltype TEXT,
11402 body_sql TEXT,
11403 edge_quals TEXT DEFAULT NULL,
11404 source_rel REGCLASS DEFAULT NULL,
11405 source_rel_attribute TEXT DEFAULT NULL,
11406 edge_sql TEXT DEFAULT NULL,
11407 hop_bound INT DEFAULT NULL,
11408 hop_seed INT DEFAULT NULL,
11409 hops_position INT DEFAULT NULL)
11410 RETURNS VOID AS
11411$$
11412DECLARE
11413 e RECORD;
11414 sv TEXT[];
11415 st UUID[];
11416 sp double precision[];
11417 verbosity INT := coalesce(current_setting('provsql.verbose_level', true)::INT, 0);
11418BEGIN
11419 BEGIN
11420 IF source_rel IS NOT NULL THEN
11421 -- Multi-source: gather the source relation (probabilistic when
11422 -- tracked, certain otherwise).
11423 SELECT g.source_values, g.source_tokens, g.source_probabilities
11424 INTO sv, st, sp
11425 FROM provsql.gather_reachability_sources(source_rel,
11426 source_rel_attribute) g;
11427 IF sv IS NULL THEN
11428 sv := ARRAY[]::TEXT[];
11429 st := ARRAY[]::UUID[];
11430 sp := ARRAY[]::float8[];
11431 END IF;
11432 ELSE
11433 -- Constant base arm: one certain source.
11434 sv := ARRAY[source_value];
11435 st := ARRAY['00000000-0000-0000-0000-000000000000'::UUID];
11436 sp := ARRAY[1.0::float8];
11437 END IF;
11438
11439 e := provsql.gather_reachability_edges(edge_rel, source_attribute,
11440 destination_attribute,
11441 sv, edge_quals, edge_sql);
11442 IF to_regclass(work_name) IS NOT NULL THEN
11443 EXECUTE format('DROP TABLE %I', work_name);
11444 END IF;
11445 /* Dropped with the statement, as the other drivers' tables are. */
11446 EXECUTE format('CREATE TEMP TABLE %I (%s, provsql UUID) ON COMMIT DROP',
11447 work_name, coldef);
11448 PERFORM provsql.planted_scope(work_name);
11449 IF hop_bound IS NULL THEN
11450 EXECUTE format(
11451 'INSERT INTO %I SELECT ($1::TEXT[])[m.vertex]::%s, m.token '
11452 || 'FROM provsql.reachability_materialize($2, $3, $4, $5, $6, $7, $8, $9, $10, $11) m',
11453 work_name, coltype)
11454 USING e.vertices, e.sources, e.destinations, e.tokens, e.probabilities,
11455 e.block_keys, e.block_indices, e.extra_ids, st, sp, directed;
11456 ELSE
11457 -- Hop-counting shape: one row per (vertex, walk length), the hop
11458 -- column in its CTE position.
11459 EXECUTE format(
11460 'INSERT INTO %I SELECT %s, m.token '
11461 || 'FROM provsql.reachability_materialize_hops($2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13) m',
11462 work_name,
11463 CASE WHEN hops_position = 1
11464 THEN format('m.hops, ($1::TEXT[])[m.vertex]::%s', coltype)
11465 ELSE format('($1::TEXT[])[m.vertex]::%s, m.hops', coltype) END)
11466 USING e.vertices, e.sources, e.destinations, e.tokens, e.probabilities,
11467 e.block_keys, e.block_indices, e.extra_ids, st, sp, directed,
11468 hop_bound, hop_seed;
11469 END IF;
11470 IF verbosity >= 20 THEN
11471 RAISE NOTICE 'ProvSQL: recursive CTE "%" compiled along a tree decomposition of %',
11472 regexp_replace(work_name, '^provsql_rec_[0-9]+a?_', ''),
11473 coalesce(edge_rel::TEXT, 'the join-defined edge query');
11474 END IF;
11475 EXCEPTION WHEN OTHERS THEN
11476 IF verbosity >= 10 THEN
11477 /* Named as the user named the CTE: the working table carries a name of
11478 ours (provsql_rec_<n>_<cte>), which is no business of a message. */
11479 RAISE NOTICE 'ProvSQL: reachability route for "%" fell back to the generic fixpoint (%)',
11480 regexp_replace(work_name, '^provsql_rec_[0-9]+a?_', ''), SQLERRM;
11481 END IF;
11482 PERFORM provsql.eval_recursive_system(body_sql, work_name, colnames, coldef);
11483 END;
11484END
11485$$ LANGUAGE plpgsql;
11486
11487
11488
11489/** @} */
11490
11491/** @defgroup provenance_output Provenance output
11492 * Functions for visualizing and exporting provenance circuits
11493 * in various formats.
11494 * @{
11495 */
11496
11497/**
11498 * @brief Return a DOT or TEXT visualization of the provenance circuit
11499 *
11500 * @param token root provenance token
11501 * @param token2desc mapping table for gate descriptions
11502 * @param dbg debug level (0 = normal)
11503 */
11504CREATE OR REPLACE FUNCTION view_circuit(
11505 token UUID,
11506 token2desc REGCLASS,
11507 dbg INT = 0)
11508 RETURNS TEXT AS
11509 'provsql','view_circuit' LANGUAGE C;
11510
11511/**
11512 * @brief Return a DOT visualisation of the d-DNNF compiled from the
11513 * provenance circuit
11514 *
11515 * Runs the requested external knowledge compiler and renders the
11516 * resulting d-DNNF as a GraphViz digraph.
11517 *
11518 * @param token root provenance token
11519 * @param compiler external compiler or in-process meta-route to invoke;
11520 * empty (the default) picks the highest-preference available compiler
11521 */
11522CREATE OR REPLACE FUNCTION compile_to_ddnnf_dot(
11523 token UUID,
11524 compiler TEXT = '')
11525 RETURNS TEXT AS
11526 'provsql','compile_to_ddnnf_dot' LANGUAGE C;
11527
11528/**
11529 * @brief Return the compiled d-DNNF of a provenance circuit in the
11530 * c2d / d4 ".nnf" TEXT interchange format.
11531 *
11532 * Companion to compile_to_ddnnf_dot (DOT, for viewing): this is the
11533 * machine-readable form, suitable for feeding to an external d-DNNF
11534 * reasoner / verifier or saving next to tseytin_cnf (same variable
11535 * numbering). Accepts the same compiler / meta-route names.
11536 *
11537 * @param token root provenance token
11538 * @param compiler compiler or in-process meta-route to use; empty (the
11539 * default) picks the highest-preference available compiler
11540 */
11541CREATE OR REPLACE FUNCTION compile_to_ddnnf(
11542 token UUID,
11543 compiler TEXT = '')
11544 RETURNS TEXT AS
11545 'provsql','compile_to_ddnnf' LANGUAGE C;
11546
11547/**
11548 * @brief Structural statistics of the d-DNNF a compiler produces for a
11549 * provenance circuit.
11550 *
11551 * Compiles the circuit with the given compiler / meta-route (same names
11552 * as compile_to_ddnnf_dot: d4, d4v2, c2d, minic2d, dsharp, panini-*,
11553 * tree-decomposition, interpret-as-dd, default) and returns a jsonb
11554 * object: nodes, edges, and / or / not / inputs counts, smooth, depth
11555 * (longest path), treewidth (null when not computable), and compile_ms.
11556 * Lets clients compare what each compiler produces on the same circuit.
11557 *
11558 * @param token root provenance token
11559 * @param compiler compiler or in-process meta-route to use; empty (the
11560 * default) picks the highest-preference available compiler
11561 */
11562CREATE OR REPLACE FUNCTION ddnnf_stats(
11563 token UUID,
11564 compiler TEXT = '')
11565 RETURNS jsonb AS
11566 'provsql','ddnnf_stats' LANGUAGE C;
11567
11568/**
11569 * @brief Canonical form of the Boolean circuit of a provenance token
11570 * (diagnostic).
11571 *
11572 * The key the cache of compiled d-DNNFs (setting prob_cache) files a
11573 * circuit under: its structure, with each input written V where it is
11574 * first met and a gate met again written \#k, its rank among the nodes of
11575 * the form. Circuits of equal form differ only by their inputs and
11576 * share one compiled d-DNNF.
11577 *
11578 * @param token root provenance token
11579 */
11580CREATE OR REPLACE FUNCTION circuit_canonical_form(token UUID)
11581 RETURNS TEXT AS
11582 'provsql','circuit_canonical_form' LANGUAGE C STRICT;
11583
11584/**
11585 * @brief Islands of the Boolean circuit of a provenance token
11586 * (diagnostic).
11587 *
11588 * The cache of compiled d-DNNFs looks a circuit up in parts: each
11589 * island, a part the rest of the circuit reaches through one gate only,
11590 * and the residual, the circuit with every island read as an input.
11591 * Returns one line "residual: <form>" followed by one line
11592 * "island <i>: <form>" per island, each form as circuit_canonical_form
11593 * writes it.
11594 *
11595 * @param token root provenance token
11596 */
11597CREATE OR REPLACE FUNCTION circuit_island_key(token UUID)
11598 RETURNS TEXT AS
11599 'provsql','circuit_island_key' LANGUAGE C STRICT;
11600
11601/**
11602 * @brief Counters of the cache of compiled d-DNNFs of the session
11603 * (diagnostic).
11604 *
11605 * Returns a jsonb object: hits and misses (lookups served and not
11606 * served), inserts, evictions (entries dropped for room), rejections
11607 * (d-DNNFs too large to keep), the entries and bytes held now, and the
11608 * budget in bytes that the entries may reach. The counters run from the
11609 * start of the session or the last prob_cache_reset.
11610 */
11611CREATE OR REPLACE FUNCTION prob_cache_stats()
11612 RETURNS jsonb AS
11613 'provsql','prob_cache_stats' LANGUAGE C;
11614
11615/**
11616 * @brief Empty the cache of compiled d-DNNFs of the session, and its
11617 * counters (diagnostic).
11618 */
11619CREATE OR REPLACE FUNCTION prob_cache_reset()
11620 RETURNS VOID AS
11621 'provsql','prob_cache_reset' LANGUAGE C;
11622
11623/**
11624 * @brief Return the DIMACS CNF (Tseytin transformation) of the provenance circuit
11625 *
11626 * Returns the same encoding the extension writes to a temp file before
11627 * invoking d4 / c2d / minic2d / dsharp. With @c weighted true (the
11628 * default), per-input probability weights are appended as @c w lines.
11629 *
11630 * @param token root provenance token
11631 * @param weighted include probability weights when true
11632 * @param mapping prepend "c input <var> <UUID> <prob>" comment lines
11633 * documenting which provenance input each variable stands for
11634 */
11635CREATE OR REPLACE FUNCTION tseytin_cnf(
11636 token UUID,
11637 weighted BOOLEAN = TRUE,
11638 mapping BOOLEAN = TRUE)
11639 RETURNS TEXT AS
11640 'provsql','tseytin_cnf' LANGUAGE C;
11641
11642/**
11643 * @brief Map each DIMACS variable of tseytin_cnf back to its
11644 * provenance input.
11645 *
11646 * Returns one row per input gate: the variable index (matching
11647 * tseytin_cnf and compile_to_ddnnf's NNF), the original-circuit UUID
11648 * of that input, and its probability. Lets a satisfying assignment or
11649 * weighted model count obtained from an external tool be read against
11650 * the provenance circuit.
11651 *
11652 * @param token root provenance token
11653 */
11654CREATE OR REPLACE FUNCTION tseytin_cnf_mapping_json(token UUID)
11655 RETURNS jsonb AS
11656 'provsql','tseytin_cnf_mapping_json' LANGUAGE C;
11657
11658CREATE OR REPLACE FUNCTION tseytin_cnf_mapping(token UUID)
11659 RETURNS TABLE(variable INT, gate UUID, probability FLOAT8) AS $$
11660 SELECT variable, gate, probability
11661 FROM jsonb_to_recordset(tseytin_cnf_mapping_json(token))
11662 AS x(variable INT, gate UUID, probability FLOAT8)
11663 ORDER BY variable
11664$$ LANGUAGE SQL STABLE;
11665
11666/**
11667 * @brief Return a DOT visualisation of the tree decomposition of the
11668 * provenance circuit
11669 *
11670 * Computes the min-fill decomposition used by the in-process
11671 * knowledge compiler. The first line of the output is a comment of
11672 * the form @c "// treewidth=<n>".
11673 *
11674 * @param token root provenance token
11675 */
11676CREATE OR REPLACE FUNCTION tree_decomposition_dot(
11677 token UUID)
11678 RETURNS TEXT AS
11679 'provsql','tree_decomposition_dot' LANGUAGE C;
11680
11681/**
11682 * @brief Report whether an external tool is on the backend's resolved PATH
11683 *
11684 * Uses the same @c find_external_tool() helper that the compilers
11685 * (d4 / c2d / minic2d / dsharp / panini), model counters (ganak /
11686 * sharpsat-td / dpmc via htb+dmc / weightmc), and visualisation
11687 * wrappers (graph-easy, dot) themselves consult, so the result
11688 * reflects exactly what a subsequent @c probability_evaluate or
11689 * @c view_circuit call would see, including the
11690 * @c provsql.tool_search_path GUC prepended to @c $PATH.
11691 *
11692 * Names with a slash are treated as paths and tested directly via
11693 * @c access(X_OK); bare names are resolved through @c /bin/sh's
11694 * @c command -v under the backend's PATH.
11695 *
11696 * @param name bare executable (e.g. @c 'd4') or an absolute path
11697 * @return true iff the tool resolves to an executable file
11698 */
11699CREATE OR REPLACE FUNCTION tool_available(name TEXT)
11700 RETURNS BOOLEAN AS
11701 'provsql','tool_available' LANGUAGE C STRICT;
11702
11703/* ----------------------------------------------------------------------
11704 * External-tool registry
11705 *
11706 * A catalog of the external tools ProvSQL can invoke (the knowledge
11707 * compilers, weighted model counters, and the graph-easy DOT renderer).
11708 * The default tools and their invocations are compiled in (seeded in C), so
11709 * out-of-the-box behaviour is unchanged with no configuration.
11710 *
11711 * Administrators may add / repoint / reorder / disable tools at run time;
11712 * those changes are persisted in the @c provsql.tool_overrides table below
11713 * and overlaid on the compiled seed, so they survive across sessions and
11714 * backends (and dump/restore). An empty overrides table means exactly the
11715 * compiled defaults. The mutators are superuser-only because a tool RECORD
11716 * names an executable run as the PostgreSQL OS user (the same trust level as
11717 * provsql.tool_search_path).
11718 * ---------------------------------------------------------------------- */
11719
11720/**
11721 * @brief Persistent overrides overlaid on the compiled-in tool seed.
11722 *
11723 * Each row is the complete desired RECORD for a tool (added or modified) keyed
11724 * by logical @c name, or a tombstone (@c removed = true) hiding a seeded
11725 * default. The effective registry is the compiled seed with tombstoned names
11726 * removed and the remaining rows upserted over it. Written only by the
11727 * superuser-only register_tool / unregister_tool / set_tool_* functions;
11728 * read back into each backend's in-memory registry on demand. Marked as a
11729 * configuration table so pg_dump carries an operator's registrations.
11730 */
11731CREATE TABLE IF NOT EXISTS tool_overrides(
11732 name TEXT PRIMARY KEY,
11733 removed BOOLEAN NOT NULL DEFAULT false,
11734 kind TEXT,
11735 executable TEXT,
11736 operations TEXT[],
11737 input_formats TEXT[],
11738 output_format TEXT,
11739 parser TEXT,
11740 preference INT,
11741 enabled BOOLEAN,
11742 dependencies TEXT[],
11743 argtpl TEXT,
11744 argtpl_circuit TEXT,
11745 endpoint TEXT
11746);
11747SELECT pg_catalog.pg_extension_config_dump('tool_overrides', '');
11748
11749/**
11750 * @brief Set-returning listing backing the @c provsql.tools view.
11751 *
11752 * @c operations / @c input_formats / @c output_format use the KCMCP
11753 * shared-registry names (see the KCMCP server protocol), so a CLI RECORD and
11754 * a future kcmcp-server RECORD are comparable; @c parser is the CLI-only tag
11755 * for how to decode the tool's raw output. @c argtpl is the command template
11756 * ({in}/{out}/... placeholders). @c available is true iff @c executable
11757 * (when set) and every dependency currently resolve on the backend's PATH.
11758 */
11759CREATE OR REPLACE FUNCTION tool_registry_list()
11760 RETURNS TABLE(name TEXT, kind TEXT, executable TEXT, operations TEXT[],
11761 input_formats TEXT[], output_format TEXT, parser TEXT,
11762 preference INT, enabled BOOLEAN, argtpl TEXT,
11763 argtpl_circuit TEXT, endpoint TEXT, available BOOLEAN) AS
11764 'provsql','tool_registry_list' LANGUAGE C STABLE;
11765
11766/**
11767 * @brief Read-only view of the registered tools.
11768 */
11769CREATE OR REPLACE VIEW tools AS
11770 SELECT name, kind, executable, operations, input_formats, output_format,
11771 parser, preference, enabled, argtpl, argtpl_circuit, endpoint,
11772 available
11773 FROM tool_registry_list();
11774
11775/**
11776 * @brief Register a tool, or replace the RECORD with the same logical name.
11777 *
11778 * @param name logical id (e.g. @c 'd4-jm62300'); also the value
11779 * @c provsql.fallback_compiler / the wmc tool selector use
11780 * @param executable executable to resolve on PATH (defaults to @c name)
11781 * @param kind @c 'cli' (spawn @c executable) or @c 'kcmcp' (talk to
11782 * the KCMCP server at @c endpoint)
11783 * @param operations capabilities (KCMCP names): @c 'compile' / @c 'wmc'
11784 * (and ProvSQL-local @c 'render')
11785 * @param input_formats accepted inputs (KCMCP names): @c 'dimacs-cnf',
11786 * @c 'circuit-bcs12' (listing @c 'circuit-bcs12' enables
11787 * the native-circuit fast path)
11788 * @param output_format result encoding (KCMCP names): @c 'ddnnf-nnf',
11789 * @c 'decimal', @c 'rational', ... (local @c 'panini-dd'
11790 * / @c 'ascii' where KCMCP has no code)
11791 * @param parser CLI-only decode tag: @c 'nnf' (the tolerant d4 / c2d
11792 * NNF reader), @c 'panini-dd', @c 'wmc-line',
11793 * @c 'weightmc', @c 'ascii'
11794 * @param argtpl command template; placeholders @c {in} / @c {out}
11795 * (and @c {binary} / @c {tmpdir} / @c {pivotAC}). When
11796 * it omits @c {binary}, the executable is prepended.
11797 * @param argtpl_circuit command used when the @c 'circuit-bcs12' input is
11798 * selected (a BC-S1.2 circuit rather than a CNF); only a
11799 * tool accepting that input needs it
11800 * @param preference ordering within an operation (higher first)
11801 * @param enabled whether the dispatchers may select it
11802 * @param endpoint for a @c 'kcmcp' RECORD, the server address:
11803 * @c 'unix:/path' or @c 'host:port'
11804 *
11805 * Superuser-only: a CLI RECORD runs an arbitrary command as the PostgreSQL
11806 * OS user, and a kcmcp RECORD names a socket the server connects to.
11807 */
11808CREATE OR REPLACE FUNCTION register_tool(
11809 name TEXT,
11810 executable TEXT DEFAULT NULL,
11811 kind TEXT DEFAULT 'cli',
11812 operations TEXT[] DEFAULT NULL,
11813 input_formats TEXT[] DEFAULT NULL,
11814 output_format TEXT DEFAULT NULL,
11815 parser TEXT DEFAULT NULL,
11816 argtpl TEXT DEFAULT NULL,
11817 argtpl_circuit TEXT DEFAULT NULL,
11818 preference INT DEFAULT 0,
11819 enabled BOOLEAN DEFAULT true,
11820 endpoint TEXT DEFAULT NULL)
11821 RETURNS VOID AS
11822 'provsql','tool_registry_register' LANGUAGE C;
11823
11824/** @brief Unregister a tool; errors on an unknown tool name. Superuser-only. */
11825CREATE OR REPLACE FUNCTION unregister_tool(name TEXT)
11826 RETURNS VOID AS
11827 'provsql','tool_registry_unregister' LANGUAGE C STRICT;
11828
11829/** @brief Enable/disable a tool; errors on an unknown tool name. Superuser-only. */
11830CREATE OR REPLACE FUNCTION set_tool_enabled(name TEXT, enabled BOOLEAN)
11831 RETURNS VOID AS
11832 'provsql','tool_registry_set_enabled' LANGUAGE C STRICT;
11833
11834/** @brief Set a tool's preference; errors on an unknown tool name. Superuser-only. */
11835CREATE OR REPLACE FUNCTION set_tool_preference(name TEXT, preference INT)
11836 RETURNS VOID AS
11837 'provsql','tool_registry_set_preference' LANGUAGE C STRICT;
11838
11839-- The mutators guard at the C level too, but revoke from PUBLIC so the
11840-- superuser requirement is visible in the catalog.
11841REVOKE ALL ON FUNCTION register_tool(TEXT, TEXT, TEXT, TEXT[], TEXT[], TEXT, TEXT, TEXT, TEXT, INT, BOOLEAN, TEXT) FROM PUBLIC;
11842REVOKE ALL ON FUNCTION unregister_tool(TEXT) FROM PUBLIC;
11843REVOKE ALL ON FUNCTION set_tool_enabled(TEXT, BOOLEAN) FROM PUBLIC;
11844REVOKE ALL ON FUNCTION set_tool_preference(TEXT, INT) FROM PUBLIC;
11845
11846/**
11847 * @brief Return an XML representation of the provenance circuit
11848 *
11849 * @param token root provenance token
11850 * @param token2desc optional mapping table for gate descriptions
11851 */
11852CREATE OR REPLACE FUNCTION to_provxml(
11853 token UUID,
11854 token2desc REGCLASS = NULL)
11855 RETURNS TEXT AS
11856 'provsql','to_provxml' LANGUAGE C;
11857
11858/** @brief Return the provenance token of the current query result tuple */
11859CREATE OR REPLACE FUNCTION provenance() RETURNS UUID AS
11860 'provsql', 'provenance' LANGUAGE C;
11861
11862/**
11863 * @brief Compute where-provenance for a result tuple
11864 *
11865 * Returns a TEXT representation showing which input columns
11866 * contributed to each output column.
11867 */
11868CREATE OR REPLACE FUNCTION where_provenance(token UUID)
11869 RETURNS TEXT AS
11870 'provsql','where_provenance' LANGUAGE C;
11871
11872/** @} */
11873
11874/** @defgroup circuit_init Circuit initialization
11875 * Functions and statements executed at extension load time to
11876 * reset internal caches and create the constant zero/one gates.
11877 * @{
11878 */
11879
11880/** @brief Reset the internal cache of OID constants used by the query rewriter */
11881CREATE OR REPLACE FUNCTION reset_constants_cache()
11882 RETURNS VOID AS
11883 'provsql', 'reset_constants_cache' LANGUAGE C;
11884
11885SELECT reset_constants_cache();
11886
11887SELECT create_gate(gate_zero(), 'zero');
11888SELECT create_gate(gate_one(), 'one');
11889SELECT create_gate(gate_null(), 'value', NULL, NULL, NULL, 'NULL');
11890
11891/** @} */
11892
11893/** @brief Types of update operations tracked for temporal provenance */
11894CREATE TYPE QUERY_TYPE_ENUM AS ENUM (
11895 'INSERT', -- Row was inserted
11896 'DELETE', -- Row was deleted
11897 'UPDATE', -- Row was updated
11898 'UNDO', -- Previous operation was undone
11899 'TRANSACTION', -- The transaction the statements below belong to
11900 'REPLACE' -- An update gate given a different probability
11901 );
11902
11903/** @defgroup compiled_semirings Compiled semirings
11904 * Definitions of compiled semirings
11905 * @{
11906 */
11907
11908/** @brief Evaluate provenance as a symbolic formula (e.g., "a ⊗ b ⊕ c") */
11909-- The mapping is optional (as for sr_boolexpr): formula renders whatever
11910-- circuit it is given, and the measure-carrier circuits it is most useful
11911-- on (random variables, arithmetic, mixtures) have no leaf mapping at all.
11912-- Without one, input leaves render as the semiring's 𝟙.
11913CREATE FUNCTION sr_formula(token ANYELEMENT, token2value REGCLASS = NULL)
11914 RETURNS VARCHAR AS
11915$$
11916BEGIN
11917 IF token IS NULL THEN
11918 RETURN NULL;
11919 END IF;
11920 RETURN provsql.provenance_evaluate_compiled(
11921 token,
11922 token2value,
11923 'formula',
11924 '𝟙'::VARCHAR
11925 );
11926END
11927$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
11928
11929/**
11930 * @brief The formula of a token as rows of bounded size
11931 *
11932 * The formula @c sr_formula writes, cut into rows: a sub-formula of more
11933 * than @p max_size symbols (each leaf, operator or constant counting for
11934 * one) is named (@c \#2, @c \#3…) and given a row of its own, where the
11935 * rows that use it read its name. A sum, product or aggregate whose row
11936 * would still be more than four times that long is written
11937 * <tt>\#k.1+…+\#k.n (n terms)</tt>, with its own operator, and each term
11938 * @c \#k.i has a row. The first row, @c \#1, is the formula of the token.
11939 * Rows are produced one at a time, each loading from the circuit store
11940 * only what it writes, so a formula too large for @c sr_formula can be
11941 * read in part: called in the select list, a @c LIMIT stops it early.
11942 *
11943 * @param token a provenance token, an aggregate or a random variable
11944 * @param token2value mapping table from input tokens to their names
11945 * @param max_size the most symbols a row writes before naming sub-formulas
11946 */
11947CREATE FUNCTION sr_formula_rows(
11948 token ANYELEMENT, token2value REGCLASS = NULL, max_size INT = 50)
11949 RETURNS TABLE(name TEXT, formula TEXT) AS
11950 'provsql', 'sr_formula_rows' LANGUAGE C PARALLEL SAFE STABLE;
11951
11952/** @brief Evaluate provenance over the counting semiring (ℕ) */
11953CREATE FUNCTION sr_counting(token ANYELEMENT, token2value REGCLASS)
11954 RETURNS INT AS
11955$$
11956BEGIN
11957 RETURN provsql.provenance_evaluate_compiled(
11958 token,
11959 token2value,
11960 'counting',
11961 1
11962 );
11963END
11964$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
11965
11966/** @brief Evaluate provenance as why-provenance (set of witness sets) */
11967CREATE FUNCTION sr_why(token ANYELEMENT, token2value REGCLASS)
11968 RETURNS VARCHAR AS
11969$$
11970BEGIN
11971 RETURN provsql.provenance_evaluate_compiled(
11972 token,
11973 token2value,
11974 'why',
11975 '{}'::VARCHAR
11976 );
11977END
11978$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
11979
11980/** @brief Evaluate provenance as how-provenance (canonical polynomial provenance ℕ[X], universal commutative-semiring provenance) */
11981CREATE FUNCTION sr_how(token ANYELEMENT, token2value REGCLASS)
11982 RETURNS VARCHAR AS
11983$$
11984BEGIN
11985 RETURN provsql.provenance_evaluate_compiled(
11986 token,
11987 token2value,
11988 'how',
11989 '{}'::VARCHAR
11990 );
11991END
11992$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
11993
11994/** @brief Evaluate provenance as which-provenance (lineage: a single set of contributing labels) */
11995CREATE FUNCTION sr_which(token ANYELEMENT, token2value REGCLASS)
11996 RETURNS VARCHAR AS
11997$$
11998BEGIN
11999 RETURN provsql.provenance_evaluate_compiled(
12000 token,
12001 token2value,
12002 'which',
12003 '{}'::VARCHAR
12004 );
12005END
12006$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
12007
12008/** @brief Evaluate provenance as a Boolean expression
12009 *
12010 * The optional @p token2value mapping labels the leaves of the
12011 * formula: when omitted, leaves are rendered as bare @c x@<id@>
12012 * placeholders.
12013 */
12014CREATE FUNCTION sr_boolexpr(token ANYELEMENT, token2value REGCLASS = NULL)
12015 RETURNS VARCHAR AS
12016$$
12017BEGIN
12018 IF token IS NULL THEN
12019 RETURN NULL;
12020 END IF;
12021 RETURN provsql.provenance_evaluate_compiled(
12022 token,
12023 token2value,
12024 'boolexpr',
12025 '⊤'::VARCHAR
12026 );
12027END
12028$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
12029
12030/** @brief Evaluate provenance over the Boolean semiring (true/false)
12031 *
12032 * The optional @p token2value mapping gives the Boolean value of the
12033 * leaves; a leaf it does not map, and every leaf when it is omitted, is
12034 * true. Without a mapping, the result is whether the token holds in the
12035 * database as it is, every input tuple present.
12036 */
12037CREATE FUNCTION sr_boolean(token ANYELEMENT, token2value REGCLASS = NULL)
12038 RETURNS BOOLEAN AS
12039$$
12040BEGIN
12041 IF token IS NULL THEN
12042 RETURN NULL;
12043 END IF;
12044 RETURN provsql.provenance_evaluate_compiled(
12045 token,
12046 token2value,
12047 'BOOLEAN',
12048 TRUE
12049 );
12050END
12051$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
12052
12053/**
12054 * @brief Whether a token holds in the database as it is (internal)
12055 *
12056 * @c sr_boolean(token) without a mapping, with a fast path for leaves. The
12057 * rewriter filters by it the rows a displayed aggregate value reads, so that
12058 * the value is the one plain SQL computes on the same data.
12059 */
12060CREATE FUNCTION plain_truth(token UUID)
12061 RETURNS BOOLEAN AS
12062 'provsql', 'plain_truth' LANGUAGE C PARALLEL SAFE STABLE;
12063
12064/** @brief Structural universal-zero test (C backend of nonzero's default mode) */
12065CREATE FUNCTION true_nonzero(token UUID)
12066 RETURNS BOOLEAN AS
12067 'provsql', 'true_nonzero' LANGUAGE C PARALLEL SAFE STABLE;
12068
12069/**
12070 * @brief Test whether a provenance annotation is nonzero.
12071 *
12072 * Returns false only on a *proof* that the annotation is zero; true
12073 * otherwise, so filtering with <tt>WHERE nonzero(provenance())</tt> never
12074 * discards a row whose annotation could be nonzero.
12075 *
12076 * The default mode (@p semiring NULL) tests *universal* zero-ness: zero in
12077 * every (m-)semiring under every leaf valuation, decided by sound
12078 * structural rules (zero propagation through the gates; a comparison gate
12079 * whose satisfying-world set is empty). Filtering on it can never
12080 * contradict any downstream semiring evaluation.
12081 *
12082 * A named @p semiring evaluates the circuit there and tests against that
12083 * semiring's zero: 'BOOLEAN' is presence in the vanilla SQL answer on this
12084 * instance (the mode that filters, e.g., the null-padded arm of a
12085 * difference), 'counting' is bag multiplicity. An absent @p mapping reads
12086 * every leaf as the semiring's one (true / 1); with a mapping, leaves take
12087 * their mapped values.
12088 *
12089 * A NULL @p token reads as the neutral 1 (an untracked row): true.
12090 *
12091 * @param token provenance token to test
12092 * @param semiring NULL (universal zero test), 'BOOLEAN', or 'counting'
12093 * @param mapping optional mapping table from tokens to leaf values
12094 */
12095CREATE FUNCTION nonzero(token UUID,
12096 semiring TEXT DEFAULT NULL,
12097 mapping REGCLASS DEFAULT NULL)
12098 RETURNS BOOLEAN AS
12099$$
12100BEGIN
12101 IF token IS NULL THEN
12102 RETURN true;
12103 END IF;
12104 IF semiring IS NULL THEN
12105 RETURN provsql.true_nonzero(token);
12106 ELSIF semiring = 'BOOLEAN' THEN
12107 IF mapping IS NULL THEN
12108 /* Every leaf true: that truth is plain_truth, which walks the gates
12109 * whose truth follows from their children's and reads a comparison of
12110 * aggregate results off the values they RECORD. Reading such a
12111 * comparison over the worlds of what it aggregates, as the evaluation
12112 * below does, costs one term per subset of its contributions. */
12113 RETURN provsql.plain_truth(token);
12114 END IF;
12115 RETURN provsql.provenance_evaluate_compiled(token, mapping, 'BOOLEAN', TRUE);
12116 ELSIF semiring = 'counting' THEN
12117 RETURN provsql.provenance_evaluate_compiled(token, mapping, 'counting', 1) <> 0;
12118 ELSE
12119 RAISE EXCEPTION 'nonzero: unsupported semiring "%" (supported: BOOLEAN, counting; NULL for the universal zero test)', semiring
12120 USING ERRCODE = 'feature_not_supported',
12121 DETAIL = 'provsql-reason: nonzero-semiring; scope: gap';
12122 END IF;
12123END
12124$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
12125
12126/**
12127 * @brief Presence in the vanilla SQL answer on this instance.
12128 *
12129 * <tt>WHERE present(provenance())</tt> restores the result set the query
12130 * has without provenance tracking, filtering the zero-annotated extras
12131 * (antijoin arms, failed HAVING groups, unknown comparisons) that the
12132 * rewriting keeps visible.
12133 *
12134 * Shorthand for <tt>nonzero(token, 'BOOLEAN')</tt> with every leaf true,
12135 * which reads that truth off the gates (@c plain_truth).
12136 */
12137CREATE FUNCTION present(token UUID)
12138 RETURNS BOOLEAN AS
12139$$
12140 SELECT provsql.nonzero(token, 'BOOLEAN');
12141$$ LANGUAGE sql PARALLEL SAFE STABLE;
12142
12143/** @brief Evaluate provenance over the tropical (min-plus) m-semiring
12144 *
12145 * Inputs are read as %float8 cost values; the additive identity
12146 * is <tt>'Infinity'::%float8</tt> and the multiplicative identity is 0.
12147 * Returns the cost of the cheapest derivation.
12148 *
12149 * With @p nonnegative, input costs are checked nonnegative and the
12150 * semiring is *absorptive*: evaluation then also accepts circuits
12151 * carrying the @c 'absorptive' assumption marker -- notably the
12152 * reachability circuits of the bounded-treewidth route, giving exact
12153 * min-cost reachability on cyclic data.
12154 */
12155CREATE FUNCTION sr_tropical(token ANYELEMENT, token2value REGCLASS,
12156 nonnegative BOOLEAN = false)
12157 RETURNS FLOAT AS
12158$$
12159BEGIN
12160 RETURN provsql.provenance_evaluate_compiled(
12161 token,
12162 token2value,
12163 CASE WHEN nonnegative THEN 'tropical_nonneg' ELSE 'tropical' END,
12164 0::FLOAT
12165 );
12166END
12167$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
12168
12169/** @brief Evaluate provenance as a regular expression over the input labels
12170 *
12171 * Inputs are read as labels (an empty label is the empty word); a
12172 * derivation is the word of its labels, in the order of the query (that
12173 * of the @c FROM clause for a join), and a tuple's value is the language
12174 * of its derivations: @c | for union, @c · for concatenation, @c * for
12175 * the Kleene star, @c ε and @c ∅ for the empty word and language.
12176 *
12177 * Concatenation does not commute. A recursion on cyclic data has the
12178 * regular expression of its derivations as exact value, provided every
12179 * recursive @c FROM clause has the recursive relation at the same place
12180 * (first, or last); otherwise it is refused.
12181 */
12182CREATE FUNCTION sr_regex(token ANYELEMENT, token2value REGCLASS)
12183 RETURNS VARCHAR AS
12184$$
12185BEGIN
12186 RETURN provsql.provenance_evaluate_compiled(
12187 token,
12188 token2value,
12189 'regex',
12190 ''::VARCHAR
12191 );
12192END
12193$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
12194
12195/** @brief C implementation of @c sr_tropical_paths */
12196CREATE FUNCTION provenance_evaluate_tropical_paths(
12197 token UUID, costs REGCLASS, labels REGCLASS,
12198 OUT cost FLOAT, OUT paths TEXT)
12199 AS 'provsql', 'provenance_evaluate_tropical_paths'
12200 LANGUAGE C PARALLEL SAFE STABLE;
12201
12202/** @brief Evaluate provenance as the least cost of a derivation, with the
12203 * derivations of that cost
12204 *
12205 * Inputs are read as %float8 costs from @p costs (0 if absent) and as
12206 * labels from @p labels (the empty word if absent). Returns the least
12207 * cost, as @c sr_tropical over nonnegative costs, and the derivations of
12208 * that cost as a regular expression over the labels, as @c sr_regex: on a
12209 * path query, the shortest paths. A cycle of cost zero can be followed any
12210 * number of times on a shortest path, and appears under a star; one of
12211 * negative cost is refused.
12212 */
12213CREATE FUNCTION sr_tropical_paths(token ANYELEMENT, costs REGCLASS,
12214 labels REGCLASS,
12215 OUT cost FLOAT, OUT paths TEXT)
12216 AS
12217$$
12218 SELECT * FROM provsql.provenance_evaluate_tropical_paths(token, costs, labels);
12219$$ LANGUAGE sql STRICT PARALLEL SAFE STABLE;
12220
12221/** @brief C implementation of @c sr_best_path */
12222CREATE FUNCTION provenance_evaluate_best_path(
12223 token UUID, costs REGCLASS, labels REGCLASS,
12224 OUT cost FLOAT, OUT path TEXT[])
12225 AS 'provsql', 'provenance_evaluate_best_path'
12226 LANGUAGE C PARALLEL SAFE STABLE;
12227
12228/** @brief Evaluate provenance as one least-cost derivation, its cost and
12229 * its labels
12230 *
12231 * Inputs are read as nonnegative %float8 costs from @p costs (0 if absent)
12232 * and as labels from @p labels (no label if absent). Returns the least
12233 * cost, as @c sr_tropical over nonnegative costs, and the labels of one
12234 * derivation of that cost, in the order of the query: on a path query, a
12235 * shortest path. Among the derivations of least cost, the one returned has
12236 * the fewest labels, and comes first in lexicographic order of its labels
12237 * among those. With no derivation, the cost is infinite and the path
12238 * @c NULL.
12239 */
12240CREATE FUNCTION sr_best_path(token ANYELEMENT, costs REGCLASS,
12241 labels REGCLASS,
12242 OUT cost FLOAT, OUT path TEXT[])
12243 AS
12244$$
12245 SELECT * FROM provsql.provenance_evaluate_best_path(token, costs, labels);
12246$$ LANGUAGE sql STRICT PARALLEL SAFE STABLE;
12247
12248/** @brief Evaluate provenance over the Viterbi (max-times) m-semiring
12249 *
12250 * Inputs are read as %float8 probability values in @f$[0,1]@f$.
12251 * Returns the probability of the most likely derivation.
12252 */
12253CREATE FUNCTION sr_viterbi(token ANYELEMENT, token2value REGCLASS)
12254 RETURNS FLOAT AS
12255$$
12256BEGIN
12257 RETURN provsql.provenance_evaluate_compiled(
12258 token,
12259 token2value,
12260 'viterbi',
12261 1::FLOAT
12262 );
12263END
12264$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
12265
12266/** @brief Evaluate provenance over the Łukasiewicz fuzzy m-semiring
12267 *
12268 * Inputs are read as %float8 graded-truth values in @f$[0,1]@f$.
12269 * Addition is @f$\max@f$; multiplication is the Łukasiewicz t-norm
12270 * @f$\max(a + b - 1, 0)@f$, which preserves crisp truth and avoids
12271 * the near-zero collapse of long product chains.
12272 */
12273CREATE FUNCTION sr_lukasiewicz(token ANYELEMENT, token2value REGCLASS)
12274 RETURNS FLOAT AS
12275$$
12276BEGIN
12277 RETURN provsql.provenance_evaluate_compiled(
12278 token,
12279 token2value,
12280 'lukasiewicz',
12281 1::FLOAT
12282 );
12283END
12284$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
12285
12286/** @brief Evaluate provenance over the min-max m-semiring on a user ENUM
12287 *
12288 * Inputs are read as values of a user-defined ENUM carrier; addition
12289 * is ENUM-min, multiplication is ENUM-max. Bottom and top of the ENUM
12290 * are derived from @c pg_enum.enumsortorder. The third argument is a
12291 * value of the carrier ENUM, used only for type inference; its value is
12292 * ignored, so @c NULL::type is enough.
12293 *
12294 * The security shape: alternative derivations combine to the least
12295 * sensitive label, joins combine to the most sensitive label.
12296 *
12297 * @param token Provenance token to evaluate.
12298 * @param token2value Mapping from input gates to ENUM values.
12299 * @param element_one A value of the carrier ENUM, used only for its type
12300 * (@c NULL::type is enough).
12301 */
12302CREATE FUNCTION sr_minmax(token UUID, token2value REGCLASS, element_one ANYENUM)
12303 RETURNS ANYENUM AS
12304$$
12305BEGIN
12306 IF token IS NULL OR token2value IS NULL THEN
12307 RETURN NULL;
12308 END IF;
12309 RETURN provsql.provenance_evaluate_compiled(
12310 token,
12311 token2value,
12312 'minmax',
12313 element_one
12314 );
12315END
12316$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
12317
12318/** @brief Evaluate provenance over the max-min m-semiring on a user ENUM
12319 *
12320 * Dual of :sqlfunc:`sr_minmax`: addition is ENUM-max, multiplication
12321 * is ENUM-min. The fuzzy / availability / trust shape: alternatives
12322 * combine to the most permissive label, joins combine to the strictest
12323 * label. The third argument is a value of the carrier ENUM, used only
12324 * for type inference; its value is ignored, so @c NULL::type is enough.
12325 *
12326 * @param token Provenance token to evaluate.
12327 * @param token2value Mapping from input gates to ENUM values.
12328 * @param element_one A value of the carrier ENUM, used only for its type
12329 * (@c NULL::type is enough).
12330 */
12331CREATE FUNCTION sr_maxmin(token UUID, token2value REGCLASS, element_one ANYENUM)
12332 RETURNS ANYENUM AS
12333$$
12334BEGIN
12335 IF token IS NULL OR token2value IS NULL THEN
12336 RETURN NULL;
12337 END IF;
12338 RETURN provsql.provenance_evaluate_compiled(
12339 token,
12340 token2value,
12341 'maxmin',
12342 element_one
12343 );
12344END
12345$$ LANGUAGE plpgsql PARALLEL SAFE STABLE;
12346
12347/** @brief Evaluate provenance over a subset semiring, as a bitmask (internal)
12348 *
12349 * Bit @f$i@f$ stands for the label of rank @f$i@f$ of the ENUM type of
12350 * @p element_one; bit 63 for the unrestricted element of @c consent.
12351 * @p semiring is @c subset, @c clearance or @c consent.
12352 */
12353CREATE OR REPLACE FUNCTION subset_evaluate(
12354 token UUID, token2value REGCLASS, semiring TEXT, element_one ANYENUM)
12355 RETURNS bigint AS
12356 'provsql', 'provenance_evaluate_compiled' LANGUAGE C PARALLEL SAFE STABLE;
12357
12358/** @brief The labels of the ENUM type of @p element_one a bitmask holds (internal) */
12359CREATE OR REPLACE FUNCTION subset_labels(mask bigint, element_one ANYENUM)
12360 RETURNS ANYARRAY AS
12361 'provsql', 'subset_labels' LANGUAGE C IMMUTABLE PARALLEL SAFE;
12362
12363/** @brief The settling level of a bitmask of clearance levels (internal) */
12364CREATE OR REPLACE FUNCTION subset_settling(mask bigint, element_one ANYENUM)
12365 RETURNS ANYENUM AS
12366 'provsql', 'subset_settling' LANGUAGE C IMMUTABLE PARALLEL SAFE;
12367
12368/** @brief Membership of a label, given as TEXT, in a subset annotation (internal)
12369 *
12370 * The ENUM type is that of the @c value column of @p token2value.
12371 */
12372CREATE OR REPLACE FUNCTION subset_member(
12373 token UUID, token2value REGCLASS, semiring TEXT, label TEXT)
12374 RETURNS BOOLEAN AS
12375 'provsql', 'subset_member' LANGUAGE C PARALLEL SAFE STABLE;
12376
12377/** @brief Evaluate provenance over the subsets of the labels of a user ENUM
12378 *
12379 * The powerset Boolean algebra: alternatives combine by union, joins by
12380 * intersection, negation (@c EXCEPT, @c NOT @c EXISTS) by difference.
12381 * A mapping value is a set of labels (an array of the ENUM), or a single
12382 * label standing for itself. The result is the set of labels whose world
12383 * contains the tuple. The third argument is a value of the ENUM, used
12384 * only for type inference (@c NULL::type is enough). At most 63 labels.
12385 *
12386 * @param token Provenance token to evaluate.
12387 * @param token2value Mapping from input gates to labels or arrays of labels.
12388 * @param element_one A value of the carrier ENUM, used only for its type
12389 * (@c NULL::type is enough).
12390 */
12391CREATE OR REPLACE FUNCTION sr_subset(
12392 token UUID, token2value REGCLASS, element_one ANYENUM)
12393 RETURNS ANYARRAY AS
12394$$
12395 SELECT provsql.subset_labels(
12396 provsql.subset_evaluate(token, token2value, 'subset', element_one),
12397 element_one)
12398 WHERE token IS NOT NULL AND token2value IS NOT NULL;
12399$$ LANGUAGE sql PARALLEL SAFE STABLE;
12400
12401/** @brief Evaluate provenance as the set of clearance levels a tuple is visible at
12402 *
12403 * The labels of the ENUM are clearance levels, in increasing order. A
12404 * single level in the mapping makes a tuple visible at that level and every
12405 * one above it; an array is an arbitrary set of levels (compartments). The
12406 * result is the set of levels at which the query, run over the tuples
12407 * visible at that level, returns the tuple: unlike :sqlfunc:`sr_minmax`,
12408 * negation is exact, so a tuple can be visible at a level and not at a
12409 * higher one.
12410 *
12411 * @param token Provenance token to evaluate.
12412 * @param token2value Mapping from input gates to levels or arrays of levels.
12413 * @param element_one A value of the carrier ENUM, used only for its type
12414 * (@c NULL::type is enough).
12415 */
12416CREATE OR REPLACE FUNCTION sr_clearance(
12417 token UUID, token2value REGCLASS, element_one ANYENUM)
12418 RETURNS ANYARRAY AS
12419$$
12420 SELECT provsql.subset_labels(
12421 provsql.subset_evaluate(token, token2value, 'clearance', element_one),
12422 element_one)
12423 WHERE token IS NOT NULL AND token2value IS NOT NULL;
12424$$ LANGUAGE sql PARALLEL SAFE STABLE;
12425
12426/** @brief Whether a tuple is visible at a clearance level
12427 *
12428 * Membership of @p level in :sqlfunc:`sr_clearance`; the level is given as
12429 * TEXT, of the ENUM type of the @c value column of the mapping.
12430 *
12431 * @param token Provenance token to evaluate.
12432 * @param token2value Mapping from input gates to levels or arrays of levels.
12433 * @param level The clearance level.
12434 */
12435CREATE OR REPLACE FUNCTION visible_at(
12436 token UUID, token2value REGCLASS, level TEXT)
12437 RETURNS BOOLEAN AS
12438$$
12439 SELECT provsql.subset_member(token, token2value, 'clearance', level);
12440$$ LANGUAGE sql STRICT PARALLEL SAFE STABLE;
12441
12442/** @brief The level from which the visibility of a tuple no longer changes
12443 *
12444 * The lowest clearance level @c settles_at such that the tuple is visible
12445 * at every level from it to the top, or at none of them; @c visible_at_top
12446 * says which. Meaningful for hierarchical levels.
12447 *
12448 * @param token Provenance token to evaluate.
12449 * @param token2value Mapping from input gates to levels or arrays of levels.
12450 * @param element_one A value of the carrier ENUM, used only for its type
12451 * (@c NULL::type is enough).
12452 * @param settles_at The settling level.
12453 * @param visible_at_top Whether the tuple is visible at the top level.
12454 */
12455CREATE OR REPLACE FUNCTION clearance_settling(
12456 token UUID, token2value REGCLASS, element_one ANYENUM,
12457 OUT settles_at ANYENUM, OUT visible_at_top BOOLEAN) AS
12458$$
12459 SELECT provsql.subset_settling(m, element_one),
12460 enum_last(element_one) = ANY(provsql.subset_labels(m, element_one))
12461 FROM provsql.subset_evaluate(token, token2value, 'clearance', element_one) m
12462 WHERE token IS NOT NULL AND token2value IS NOT NULL;
12463$$ LANGUAGE sql PARALLEL SAFE STABLE;
12464
12465/** @brief Evaluate provenance over consented purposes
12466 *
12467 * The labels of the ENUM are purposes; the mapping gives the purposes each
12468 * tuple is consented for (a purpose or an array of purposes). The result
12469 * gives the purposes for which the query, run over the tuples consented for
12470 * that purpose, returns the tuple, and whether the query over the whole
12471 * database (@c unrestricted) returns it.
12472 *
12473 * @param token Provenance token to evaluate.
12474 * @param token2value Mapping from input gates to purposes or arrays of purposes.
12475 * @param element_one A value of the carrier ENUM, used only for its type
12476 * (@c NULL::type is enough).
12477 * @param purposes The purposes for which the query returns the tuple.
12478 * @param unrestricted Whether the query over the whole database returns it.
12479 */
12480CREATE OR REPLACE FUNCTION sr_consent(
12481 token UUID, token2value REGCLASS, element_one ANYENUM,
12482 OUT purposes ANYARRAY, OUT unrestricted BOOLEAN) AS
12483$$
12484 SELECT provsql.subset_labels(m, element_one), m < 0
12485 FROM provsql.subset_evaluate(token, token2value, 'consent', element_one) m
12486 WHERE token IS NOT NULL AND token2value IS NOT NULL;
12487$$ LANGUAGE sql PARALLEL SAFE STABLE;
12488
12489/** @brief Whether a tuple may be used for a purpose
12490 *
12491 * True when the query returns the tuple both over the whole database and
12492 * over the tuples consented for @p purpose, given as TEXT, of the ENUM type
12493 * of the @c value column of the mapping.
12494 *
12495 * @param token Provenance token to evaluate.
12496 * @param token2value Mapping from input gates to purposes or arrays of purposes.
12497 * @param purpose The purpose.
12498 */
12499CREATE OR REPLACE FUNCTION consented_for(
12500 token UUID, token2value REGCLASS, purpose TEXT)
12501 RETURNS BOOLEAN AS
12502$$
12503 SELECT provsql.subset_member(token, token2value, 'consent', purpose);
12504$$ LANGUAGE sql STRICT PARALLEL SAFE STABLE;
12505
12506/** @brief The purposes a tuple may be used for
12507 *
12508 * The purposes for which :sqlfunc:`consented_for` holds: empty when the
12509 * query over the whole database does not return the tuple.
12510 *
12511 * @param token Provenance token to evaluate.
12512 * @param token2value Mapping from input gates to purposes or arrays of purposes.
12513 * @param element_one A value of the carrier ENUM, used only for its type
12514 * (@c NULL::type is enough).
12515 */
12516CREATE OR REPLACE FUNCTION consent_purposes(
12517 token UUID, token2value REGCLASS, element_one ANYENUM)
12518 RETURNS ANYARRAY AS
12519$$
12520 SELECT CASE WHEN m < 0 THEN provsql.subset_labels(m, element_one)
12521 ELSE provsql.subset_labels(0, element_one) END
12522 FROM provsql.subset_evaluate(token, token2value, 'consent', element_one) m
12523 WHERE token IS NOT NULL AND token2value IS NOT NULL;
12524$$ LANGUAGE sql PARALLEL SAFE STABLE;
12525
12526/** @brief The purposes for which consent changes the answer
12527 *
12528 * The purposes whose consented tuples give a different answer about the
12529 * tuple than the whole database: the tuple is returned for the purpose but
12530 * not over the whole database (only possible through a negation reading a
12531 * tuple the purpose was not consented for), or the reverse (the purpose
12532 * lacks consent for a tuple the answer needs).
12533 *
12534 * @param token Provenance token to evaluate.
12535 * @param token2value Mapping from input gates to purposes or arrays of purposes.
12536 * @param element_one A value of the carrier ENUM, used only for its type
12537 * (@c NULL::type is enough).
12538 */
12539CREATE OR REPLACE FUNCTION consent_conflicts(
12540 token UUID, token2value REGCLASS, element_one ANYENUM)
12541 RETURNS ANYARRAY AS
12542$$
12543 SELECT CASE WHEN m < 0 THEN provsql.subset_labels(~m, element_one)
12544 ELSE provsql.subset_labels(m, element_one) END
12545 FROM provsql.subset_evaluate(token, token2value, 'consent', element_one) m
12546 WHERE token IS NOT NULL AND token2value IS NOT NULL;
12547$$ LANGUAGE sql PARALLEL SAFE STABLE;
12548
12549/** @} */
12550
12551/** @defgroup choose_aggregate choose aggregate
12552 * Choose one value among many, used in particular to code a mutually
12553 * exclusive choice as an aggregate.
12554 * @{
12555 */
12556
12557/** @brief Transition function for the choose aggregate (keeps first non-NULL value) */
12558CREATE FUNCTION choose_function(state ANYELEMENT, data ANYELEMENT)
12559 RETURNS ANYELEMENT AS
12560$$
12561BEGIN
12562 IF state IS NULL THEN
12563 RETURN data;
12564 ELSE
12565 RETURN state;
12566 END IF;
12567END
12568$$ LANGUAGE plpgsql PARALLEL SAFE IMMUTABLE;
12569
12570/** @brief Aggregate that returns an arbitrary non-NULL value from a group */
12571CREATE AGGREGATE choose(ANYELEMENT) (
12572 SFUNC = choose_function,
12573 STYPE = ANYELEMENT
12574);
12575
12576/** @brief Transition function of @c array_collect */
12577CREATE FUNCTION array_collect_step(state ANYARRAY, data ANYNONARRAY)
12578 RETURNS ANYARRAY AS
12579$$ SELECT array_append(state, data) $$
12580LANGUAGE sql PARALLEL SAFE IMMUTABLE;
12581
12582/** @brief @c array_agg, but the empty array over no rows, not NULL
12583 *
12584 * This is the value of @c ARRAY(SELECT ...): ProvSQL rewrites such a
12585 * subquery into this aggregate over the matching rows. */
12586CREATE AGGREGATE array_collect(ANYNONARRAY) (
12587 SFUNC = array_collect_step,
12588 STYPE = ANYARRAY,
12589 INITCOND = '{}'
12590);
12591
12592/** @brief Explodes a table column containing aggregated provenance into multiple rows.
12593 *
12594 * For each row in the input table, this function unnests the children of the
12595 * specified aggregate token column and produces one output row per child.
12596 * It reconstructs the corresponding value and provenance (`provsql`) for
12597 * each resulting row.
12598 *
12599 * The original table is replaced by the transformed table.
12600 *
12601 * @param _tbl Name of the table to transform.
12602 * @param AGG_TOKEN Name of the column containing the aggregate to explode.
12603 */
12604CREATE OR REPLACE FUNCTION explode_table(_tbl TEXT, AGG_TOKEN TEXT)
12605RETURNS VOID AS $$
12606DECLARE
12607 _nsp TEXT;
12608BEGIN
12609 -- Resolve the schema actually holding _tbl so the rebuilt table is
12610 -- recreated in place (the provsql helper functions are schema-qualified
12611 -- so this works whatever the caller's search_path is).
12612 SELECT n.nspname INTO _nsp
12613 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
12614 WHERE c.oid = _tbl::REGCLASS;
12615
12616 EXECUTE format('
12617 CREATE TABLE %1$I.temp_exploded AS
12618 SELECT
12619 %2$I.*,
12620 provsql.get_extra(children[2]) AS new_t,
12621 provsql.provenance_times(children[1], provsql) AS new_provsql
12622 FROM %1$I.%2$I,
12623 LATERAL (
12624 SELECT provsql.get_children(sm) AS children
12625 FROM UNNEST(provsql.agg_token_explode_children(%3$I)) AS sm
12626 ) AS sub', _nsp, _tbl, AGG_TOKEN);
12627 EXECUTE format('DROP TABLE %I.%I', _nsp, _tbl);
12628 EXECUTE format('ALTER TABLE %I.temp_exploded DROP COLUMN %I, DROP COLUMN provsql', _nsp, AGG_TOKEN);
12629 EXECUTE format('ALTER TABLE %I.temp_exploded RENAME COLUMN new_t TO %I', _nsp, AGG_TOKEN);
12630 EXECUTE format('ALTER TABLE %I.temp_exploded RENAME COLUMN new_provsql TO provsql', _nsp);
12631 EXECUTE format('ALTER TABLE %I.temp_exploded RENAME TO %I', _nsp, _tbl);
12632END;
12633$$ LANGUAGE plpgsql;
12634
12635/** @} */
12636
12637/**
12638 * @brief The build of the ProvSQL library loaded, as TEXT
12639 *
12640 * The commit the library was built from, as @c "git describe --tags --always
12641 * --dirty" gives it (e.g., @c v1.12.0-431-g577cc730), or @c unknown for a
12642 * build outside a git checkout. The extension's version is the same for
12643 * every build of a development cycle; this tells them apart, for a bug report
12644 * or a RECORD of which build produced a result.
12645 */
12646CREATE OR REPLACE FUNCTION build_id()
12647 RETURNS TEXT
12648 AS 'provsql','build_id' LANGUAGE C STABLE STRICT PARALLEL SAFE;
12649
12650/**
12651 * @brief Append @c provsql to this database's default search_path, if missing.
12652 *
12653 * ProvSQL's operators and functions live in the @c provsql schema and
12654 * are resolved through @c search_path. When @c provsql is absent from
12655 * the path some surfaces fail with a clear error (RV/AGG_TOKEN
12656 * arithmetic), but others can be silently misrouted by an implicit
12657 * cross-domain cast. This helper makes the common case painless: it
12658 * reads the current <em>database-level</em> search_path setting from
12659 * @c pg_db_role_setting, appends @c provsql if not already present
12660 * (never replacing or reordering the existing entries), and applies the
12661 * result with @c ALTER @c DATABASE. It is idempotent and emits a
12662 * @c NOTICE describing what it did.
12663 *
12664 * Only @b new sessions pick up the change; the calling session keeps its
12665 * current path. Role-level settings (if any) take precedence over the
12666 * database-level setting and are left untouched. The caller must be the
12667 * database owner or a superuser (the privilege model of @c ALTER
12668 * @c DATABASE). Returns the resulting search_path value.
12669 */
12670CREATE OR REPLACE FUNCTION setup_search_path()
12671 RETURNS TEXT
12672 LANGUAGE plpgsql AS $$
12673DECLARE
12674 db TEXT := current_database();
12675 cfg TEXT[];
12676 cur TEXT; -- existing database-level search_path value
12677 new_path TEXT;
12678BEGIN
12679 -- setrole = 0 selects the database-wide default, not a per-role override.
12680 SELECT s.setconfig INTO cfg
12681 FROM pg_db_role_setting s
12682 JOIN pg_database d ON d.oid = s.setdatabase
12683 WHERE d.datname = db AND s.setrole = 0;
12684
12685 IF cfg IS NOT NULL THEN
12686 SELECT substr(e, length('search_path=') + 1) INTO cur
12687 FROM unnest(cfg) AS e
12688 WHERE e LIKE 'search_path=%';
12689 END IF;
12690
12691 IF cur IS NULL THEN
12692 -- No database-level search_path at all: install the documented
12693 -- default with provsql appended.
12694 new_path := '"$user", public, provsql';
12695 EXECUTE format('ALTER DATABASE %I SET search_path = %s', db, new_path);
12696 RAISE NOTICE 'ProvSQL: set search_path = % for database "%" (no previous database-level setting). Only new sessions are affected.',
12697 new_path, db;
12698 RETURN new_path;
12699 END IF;
12700
12701 -- Already contains provsql as a path element? Idempotent no-op.
12702 IF EXISTS (
12703 SELECT 1 FROM unnest(string_to[](cur, ',')) AS p
12704 WHERE btrim(btrim(p), '"') = 'provsql')
12705 THEN
12706 RAISE NOTICE 'ProvSQL: search_path for database "%" already contains provsql (= %); no change.',
12707 db, cur;
12708 RETURN cur;
12709 END IF;
12710
12711 new_path := cur || ', provsql';
12712 EXECUTE format('ALTER DATABASE %I SET search_path = %s', db, new_path);
12713 RAISE NOTICE 'ProvSQL: appended provsql to search_path for database "%" (now: %). Only new sessions are affected.',
12714 db, new_path;
12715 RETURN new_path;
12716END;
12717$$;
12718
12719GRANT USAGE ON SCHEMA provsql TO PUBLIC;
12720
12721SET search_path TO public;
12722
12723-- Installation-time advisory: if provsql is not in the database's default
12724-- search_path, point the user at setup_search_path(). reset_val reflects
12725-- the configured session default (postgresql.conf / ALTER DATABASE / ALTER
12726-- ROLE), unaffected by the SET search_path statements this script ran.
12727-- CREATE EXTENSION raises client_min_messages to WARNING for the duration
12728-- of the script, so we lower it around the RAISE NOTICE. SET LOCAL only:
12729-- it unwinds by itself when CREATE EXTENSION's transaction ends. An
12730-- explicit save/restore here would capture the WARNING clamp (already in
12731-- force when this block runs) and restore *that* at session level,
12732-- leaving the whole installing session with NOTICEs suppressed.
12733DO $$
12734DECLARE
12735 rp TEXT;
12736 has_provsql BOOLEAN;
12737BEGIN
12738 SELECT reset_val INTO rp FROM pg_settings WHERE name = 'search_path';
12739 SELECT bool_or(btrim(btrim(p), '"') = 'provsql')
12740 INTO has_provsql
12741 FROM unnest(string_to[](coalesce(rp, ''), ',')) AS p;
12742 IF NOT coalesce(has_provsql, false) THEN
12743 SET LOCAL client_min_messages = notice;
12744 RAISE NOTICE 'ProvSQL: schema "provsql" is not in your default search_path (currently: %).', rp;
12745 RAISE NOTICE 'ProvSQL operators and functions are resolved through search_path. Run "SELECT provsql.setup_search_path();" to add it, or set it manually (e.g. ALTER DATABASE % SET search_path = "$user", public, provsql).', quote_ident(current_database());
12746 END IF;
12747END;
12748$$;
12749
12750-- Final constants-cache refresh. The planned SELECT statements earlier in
12751-- this script (reset_constants_cache itself, the zero/one create_gate calls)
12752-- make the installing session memoize the OID constants *mid-script*, while
12753-- objects defined later (notably the choose aggregate, used by the
12754-- scalar-subquery decorrelation) do not exist yet. Their optional lookups
12755-- then stay InvalidOid for the rest of the session, silently disabling the
12756-- corresponding rewrites (e.g. IN/NOT IN over a tracked relation would raise
12757-- "Subqueries ... not supported") until a new connection. Refreshing here,
12758-- after every object exists, repairs the installing session's cache.
12759SELECT provsql.reset_constants_cache();
12760SET search_path TO provsql;
12761
12762/** @defgroup update_provenance Update provenance (PostgreSQL 14+)
12763 * Extended provenance tracking for INSERT, UPDATE, DELETE, and UNDO
12764 * operations, including temporal validity ranges.
12765 * @{
12766 */
12767
12768/**
12769 * @brief Table recording the history of INSERT, UPDATE, DELETE, and UNDO operations
12770 *
12771 * Each row records one provenance-tracked modification, linking the
12772 * operation's provenance token to metadata (query TEXT, type, user,
12773 * TIMESTAMP) and the temporal validity range of the affected rows.
12774 *
12775 * A row of type @c TRANSACTION stands for the transaction the statements
12776 * around it belong to (see @c provsql.transaction_token): @c xid is its
12777 * transaction id and its own @c tx_token is NULL, while every statement
12778 * row of that transaction carries the transaction's token in @c tx_token.
12779 * A modified tuple's provenance names both -- the effect is
12780 * @c times(tx_token, statement_token) -- so @c undo() reverses either one
12781 * statement or the whole transaction, and the temporal semiring reads the
12782 * transaction's validity through the shared factor.
12783 *
12784 * @c ts and the lower bound of @c valid_time are stamped at commit, not
12785 * at the statement: @c CURRENT_TIMESTAMP is the transaction's start time,
12786 * so two overlapping transactions could otherwise commit in the opposite
12787 * order of their recorded validity.
12788 */
12789CREATE TABLE update_provenance (
12790 provsql UUID,
12791 query TEXT,
12792 query_type QUERY_TYPE_ENUM,
12793 username TEXT,
12794 ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
12795 valid_time TSTZMULTIRANGE DEFAULT TSTZMULTIRANGE(tstzrange(CURRENT_TIMESTAMP, NULL)),
12796 xid xid8,
12797 tx_token UUID
12798);
12799/**
12800 * @brief The update gate standing for the current transaction
12801 *
12802 * Each data-modification statement already mints an @c update gate of its
12803 * own, but nothing tied the statements of one transaction together: a
12804 * reader of @c update_provenance could not tell that two rows came from
12805 * the same transaction, and @c undo() could reverse a statement but not
12806 * "the transaction". This mints one gate per transaction, on the first
12807 * tracked modification, and hands the same one back for the rest of it.
12808 *
12809 * Where a transaction's gate lives is @c SET @c LOCAL, so it vanishes
12810 * when the transaction ends, whether it commits or rolls back -- and a
12811 * rolled-back transaction leaves no @c update_provenance row for it
12812 * either, since that row is an ordinary heap insert.
12813 */
12814CREATE OR REPLACE FUNCTION transaction_token()
12815RETURNS UUID
12816LANGUAGE plpgsql
12817AS $$
12818DECLARE
12819 tok TEXT;
12820 new_tok UUID;
12821 query_text TEXT;
12822BEGIN
12823 tok := current_setting('provsql.transaction_token', true);
12824 IF tok IS NOT NULL AND tok <> '' THEN
12825 RETURN tok::UUID;
12826 END IF;
12827
12828 new_tok := public.uuid_generate_v4();
12829 PERFORM create_gate(new_tok, 'update');
12830 PERFORM set_config('provsql.transaction_token', new_tok::TEXT, true);
12831
12832 -- A transaction has no query TEXT of its own: query is left NULL, so
12833 -- looking a statement up by its TEXT finds the statement and not the
12834 -- transaction that carried it.
12835 query_text := NULL;
12836
12837 -- The transaction's own validity is the universal range, the
12838 -- multiplicative identity of the temporal m-semiring: it is a factor of
12839 -- every effect of the transaction, and what a tuple is valid for is the
12840 -- statement's business, not the transaction's. Giving it a real
12841 -- interval would intersect it into every one of them.
12842 INSERT INTO update_provenance(provsql, query, query_type, username, ts,
12843 valid_time, xid)
12844 VALUES (new_tok, query_text, 'TRANSACTION', current_user,
12845 CURRENT_TIMESTAMP, '{(,)}'::TSTZMULTIRANGE,
12846 pg_current_xact_id());
12847
12848 RETURN new_tok;
12849END;
12850$$;
12851
12852/**
12853 * @brief Deferred trigger stamping a log row with its commit time
12854 *
12855 * @c CURRENT_TIMESTAMP is the transaction's *start* time, so two
12856 * overlapping transactions can commit in the opposite order of the
12857 * validity they recorded. This fires at commit -- it is a constraint
12858 * trigger declared @c DEFERRABLE @c INITIALLY @c DEFERRED -- and moves
12859 * the row's TIMESTAMP and the lower bound of its validity to
12860 * @c clock_timestamp(), which by then is the commit time to within the
12861 * commit itself.
12862 */
12863CREATE OR REPLACE FUNCTION stamp_commit_time()
12864 RETURNS trigger AS
12865$$
12866DECLARE
12867 now_ts TIMESTAMPTZ := clock_timestamp();
12868BEGIN
12869 UPDATE update_provenance
12870 SET ts = now_ts,
12871 valid_time = CASE WHEN query_type IN ('TRANSACTION', 'REPLACE')
12872 THEN valid_time
12873 ELSE TSTZMULTIRANGE(tstzrange(now_ts, NULL)) END
12874 WHERE provsql = NEW.provsql;
12875 RETURN NULL;
12876END;
12877$$ LANGUAGE plpgsql;
12878
12879DO $$ BEGIN
12880 IF NOT EXISTS (SELECT 1 FROM pg_trigger
12881 WHERE tgrelid = 'provsql.update_provenance'::REGCLASS
12882 AND tgname = 'stamp_commit_time') THEN
12883 CREATE CONSTRAINT TRIGGER stamp_commit_time
12884 AFTER INSERT ON provsql.update_provenance
12885 DEFERRABLE INITIALLY DEFERRED
12886 FOR EACH ROW EXECUTE FUNCTION provsql.stamp_commit_time();
12887 END IF;
12888END $$;
12889
12890/** @cond INTERNAL */
12891/* Enable provenance tracking on an existing table (PostgreSQL 14+ version).
12892 * Overrides the common version; documented via add_provenance in provsql.common.sql. */
12893CREATE OR REPLACE FUNCTION add_provenance(_tbl REGCLASS)
12894 RETURNS VOID AS
12895$$
12896BEGIN
12897 -- Idempotence: a second add_provenance on an already-tracked table is
12898 -- a no-op with a NOTICE, so setup scripts and notebook cells can be
12899 -- re-run freely.
12900 IF EXISTS (
12901 SELECT 1 FROM pg_attribute
12902 WHERE attrelid = _tbl AND attname = 'provsql' AND NOT attisdropped
12903 ) THEN
12904 RAISE NOTICE 'table % already has provenance tracking', _tbl;
12905 RETURN;
12906 END IF;
12907 -- See the common-version body for the rationale of dropping the
12908 -- column DEFAULT and UNIQUE in favour of provenance_guard + a
12909 -- plain index.
12910 EXECUTE format('ALTER TABLE %s ADD COLUMN provsql UUID', _tbl);
12911 EXECUTE format(
12912 'UPDATE %s SET provsql = public.uuid_generate_v4() WHERE provsql IS NULL',
12913 _tbl);
12914 EXECUTE format('CREATE INDEX ON %s(provsql)', _tbl);
12915 EXECUTE format(
12916 'CREATE TRIGGER provenance_guard BEFORE INSERT OR UPDATE OF provsql '
12917 'ON %s FOR EACH ROW EXECUTE FUNCTION provsql.provenance_guard()',
12918 _tbl);
12919
12920 EXECUTE format('CREATE TRIGGER insert_statement AFTER INSERT ON %s REFERENCING NEW TABLE AS NEW_TABLE FOR EACH STATEMENT EXECUTE FUNCTION provsql.insert_statement_trigger()', _tbl);
12921 EXECUTE format('CREATE TRIGGER delete_statement AFTER DELETE ON %s REFERENCING OLD TABLE AS OLD_TABLE FOR EACH STATEMENT EXECUTE FUNCTION provsql.delete_statement_trigger()', _tbl);
12922 EXECUTE format('CREATE TRIGGER update_statement AFTER UPDATE ON %s REFERENCING OLD TABLE AS OLD_TABLE NEW TABLE AS NEW_TABLE FOR EACH STATEMENT EXECUTE FUNCTION provsql.update_statement_trigger()', _tbl);
12923
12924 PERFORM provsql.set_table_info(_tbl::oid, 'tid');
12925 PERFORM provsql.set_ancestors(_tbl::oid, ARRAY[_tbl::oid]);
12926END
12927$$ LANGUAGE plpgsql SECURITY DEFINER;
12928/** @endcond */
12929
12930/** @cond INTERNAL */
12931/* Trigger function for DELETE statement provenance tracking (PostgreSQL 14+).
12932 * Overrides the common version; documented via delete_statement_trigger in provsql.common.sql. */
12933CREATE OR REPLACE FUNCTION delete_statement_trigger()
12934 RETURNS TRIGGER AS
12935$$
12936DECLARE
12937 query_text TEXT;
12938 delete_token UUID;
12939 old_token UUID;
12940 new_token UUID;
12941 r RECORD;
12942 tx_token UUID;
12943 enable_trigger BOOL;
12944BEGIN
12945 enable_trigger := current_setting('provsql.update_provenance', true);
12946 IF enable_trigger = 'f' THEN
12947 RETURN NULL;
12948 END IF;
12949 delete_token := public.uuid_generate_v4();
12950
12951 PERFORM create_gate(delete_token, 'update');
12952
12953 SELECT query
12954 INTO query_text
12955 FROM pg_stat_activity
12956 WHERE pid = pg_backend_pid();
12957
12958 tx_token := transaction_token();
12959
12960 INSERT INTO update_provenance (provsql, query, query_type, username, ts,
12961 valid_time, xid, tx_token)
12962 VALUES (delete_token, query_text, 'DELETE', current_user, CURRENT_TIMESTAMP,
12963 TSTZMULTIRANGE(tstzrange(CURRENT_TIMESTAMP, NULL)),
12964 pg_current_xact_id(), tx_token);
12965
12966 -- The effect this statement has on a row names both the statement and
12967 -- the transaction it belongs to, so undo() can reverse either.
12968 delete_token := provenance_times(tx_token, delete_token);
12969
12970 PERFORM set_config('provsql.update_provenance', 'off', true);
12971 EXECUTE format('INSERT INTO %I.%I SELECT * FROM OLD_TABLE;', TG_TABLE_SCHEMA, TG_TABLE_NAME);
12972 PERFORM set_config('provsql.update_provenance', 'on', true);
12973
12974 FOR r IN (SELECT * FROM OLD_TABLE) LOOP
12975 old_token := r.provsql;
12976 new_token := provenance_monus(old_token, delete_token);
12977
12978 PERFORM set_config('provsql.update_provenance', 'off', true);
12979 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2;', TG_TABLE_SCHEMA, TG_TABLE_NAME)
12980 USING new_token, old_token;
12981 PERFORM set_config('provsql.update_provenance', 'on', true);
12982 END LOOP;
12983
12984 RETURN NULL;
12985END
12986$$ LANGUAGE plpgsql SET search_path=provsql,pg_temp SECURITY DEFINER;
12987/** @endcond */
12988
12989/**
12990 * @brief Trigger function for INSERT statement provenance tracking
12991 *
12992 * Records the insertion in update_provenance and multiplies provenance
12993 * tokens of inserted rows with the insert token.
12994 */
12995CREATE OR REPLACE FUNCTION insert_statement_trigger()
12996 RETURNS TRIGGER AS
12997$$
12998DECLARE
12999 query_text TEXT;
13000 insert_token UUID;
13001 old_token UUID;
13002 new_token UUID;
13003 r RECORD;
13004 tx_token UUID;
13005 enable_trigger BOOL;
13006BEGIN
13007 enable_trigger := current_setting('provsql.update_provenance', true);
13008 IF enable_trigger = 'f' THEN
13009 RETURN NULL;
13010 END IF;
13011
13012 insert_token := public.uuid_generate_v4();
13013
13014 PERFORM create_gate(insert_token, 'update');
13015
13016 SELECT query
13017 INTO query_text
13018 FROM pg_stat_activity
13019 WHERE pid = pg_backend_pid();
13020
13021 tx_token := transaction_token();
13022
13023 INSERT INTO update_provenance (provsql, query, query_type, username, ts,
13024 valid_time, xid, tx_token)
13025 VALUES (insert_token, query_text, 'INSERT', current_user, CURRENT_TIMESTAMP,
13026 TSTZMULTIRANGE(tstzrange(CURRENT_TIMESTAMP, NULL)),
13027 pg_current_xact_id(), tx_token);
13028
13029 -- The effect this statement has on a row names both the statement and
13030 -- the transaction it belongs to, so undo() can reverse either.
13031 insert_token := provenance_times(tx_token, insert_token);
13032
13033 FOR r IN (SELECT * FROM NEW_TABLE) LOOP
13034 old_token := r.provsql;
13035 new_token := provenance_times(old_token, insert_token);
13036 PERFORM set_config('provsql.update_provenance', 'off', true);
13037 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2;', TG_TABLE_SCHEMA, TG_TABLE_NAME)
13038 USING new_token, old_token;
13039 PERFORM set_config('provsql.update_provenance', 'on', true);
13040 END LOOP;
13041
13042 RETURN NULL;
13043END
13044$$ LANGUAGE plpgsql SET search_path=provsql,pg_temp SECURITY DEFINER;
13045
13046/**
13047 * @brief Trigger function for UPDATE statement provenance tracking
13048 *
13049 * Records the update in update_provenance. Multiplies new-row tokens
13050 * with the update token and applies monus to old-row tokens.
13051 */
13052CREATE OR REPLACE FUNCTION update_statement_trigger()
13053 RETURNS TRIGGER AS
13054$$
13055DECLARE
13056 query_text TEXT;
13057 update_token UUID;
13058 old_token UUID;
13059 new_token UUID;
13060 r RECORD;
13061 tx_token UUID;
13062 enable_trigger BOOL;
13063BEGIN
13064 enable_trigger := current_setting('provsql.update_provenance', true);
13065 IF enable_trigger = 'f' THEN
13066 RETURN NULL;
13067 END IF;
13068 update_token := public.uuid_generate_v4();
13069
13070 PERFORM create_gate(update_token, 'update');
13071
13072 SELECT query
13073 INTO query_text
13074 FROM pg_stat_activity
13075 WHERE pid = pg_backend_pid();
13076
13077 tx_token := transaction_token();
13078
13079 INSERT INTO update_provenance (provsql, query, query_type, username, ts,
13080 valid_time, xid, tx_token)
13081 VALUES (update_token, query_text, 'UPDATE', current_user, CURRENT_TIMESTAMP,
13082 TSTZMULTIRANGE(tstzrange(CURRENT_TIMESTAMP, NULL)),
13083 pg_current_xact_id(), tx_token);
13084
13085 -- The effect this statement has on a row names both the statement and
13086 -- the transaction it belongs to, so undo() can reverse either.
13087 update_token := provenance_times(tx_token, update_token);
13088
13089 FOR r IN (SELECT * FROM NEW_TABLE) LOOP
13090 old_token := r.provsql;
13091 new_token := provenance_times(old_token, update_token);
13092
13093 PERFORM set_config('provsql.update_provenance', 'off', true);
13094 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2;', TG_TABLE_SCHEMA, TG_TABLE_NAME)
13095 USING new_token, old_token;
13096 PERFORM set_config('provsql.update_provenance', 'on', true);
13097 END LOOP;
13098
13099 PERFORM set_config('provsql.update_provenance', 'off', true);
13100 EXECUTE format('INSERT INTO %I.%I SELECT * FROM OLD_TABLE;', TG_TABLE_SCHEMA, TG_TABLE_NAME);
13101 PERFORM set_config('provsql.update_provenance', 'on', true);
13102
13103 FOR r IN (SELECT * FROM OLD_TABLE) LOOP
13104 old_token := r.provsql;
13105 new_token := provenance_monus(old_token, update_token);
13106
13107 PERFORM set_config('provsql.update_provenance', 'off', true);
13108 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2;', TG_TABLE_SCHEMA, TG_TABLE_NAME)
13109 USING new_token, old_token;
13110 PERFORM set_config('provsql.update_provenance', 'on', true);
13111 END LOOP;
13112
13113 RETURN NULL;
13114END
13115$$ LANGUAGE plpgsql SET search_path=provsql,pg_temp SECURITY DEFINER;
13116
13117
13118/** @} */
13119
13120/** @defgroup temporal_db Temporal DB (PostgreSQL 14+)
13121 * Functions for temporal database support. These use provenance
13122 * evaluation over the multirange semiring to track temporal validity
13123 * of tuples.
13124 * @{
13125 */
13126
13127SET search_path TO provsql;
13128
13129/**
13130 * @brief Evaluate provenance over the temporal (interval-union) m-semiring
13131 *
13132 * Inputs are read as %TSTZMULTIRANGE validity intervals; the additive
13133 * identity is <tt>'{}'::%TSTZMULTIRANGE</tt> (empty), the multiplicative
13134 * identity is <tt>'{(,)}'::%TSTZMULTIRANGE</tt> (universal). Returns the union
13135 * of intervals supporting the result, computed via the compiled circuit
13136 * traversal.
13137 *
13138 * @param token Provenance token to evaluate.
13139 * @param token2value Mapping from input gates to validity multiranges.
13140 */
13141CREATE FUNCTION sr_temporal(token ANYELEMENT, token2value REGCLASS)
13142 RETURNS TSTZMULTIRANGE AS
13143$$
13144BEGIN
13145 RETURN provsql.provenance_evaluate_compiled(
13146 token,
13147 token2value,
13148 'interval_union',
13149 '{(,)}'::TSTZMULTIRANGE
13150 );
13151END
13152$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
13153
13154/**
13155 * @brief Evaluate provenance over the interval-union m-semiring
13156 * with a NUMERIC multirange carrier
13157 *
13158 * Inputs are read as %nummultirange validity ranges over a NUMERIC
13159 * domain (e.g. sensor measurement-validity ranges). Addition is
13160 * multirange union, multiplication is intersection, monus is set
13161 * difference; the additive identity is <tt>'{}'::%nummultirange</tt>
13162 * and the multiplicative identity is <tt>'{(,)}'::%nummultirange</tt>
13163 * (universal range).
13164 *
13165 * @param token Provenance token to evaluate.
13166 * @param token2value Mapping from input gates to NUMERIC multiranges.
13167 */
13168CREATE FUNCTION sr_interval_num(token ANYELEMENT, token2value REGCLASS)
13169 RETURNS nummultirange AS
13170$$
13171BEGIN
13172 RETURN provsql.provenance_evaluate_compiled(
13173 token,
13174 token2value,
13175 'interval_union',
13176 '{(,)}'::nummultirange
13177 );
13178END
13179$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
13180
13181/**
13182 * @brief Evaluate provenance over the interval-union m-semiring
13183 * with an int4 multirange carrier
13184 *
13185 * Inputs are read as %int4multirange validity ranges over the
13186 * integers (e.g. page or line ranges of supporting documents).
13187 * Addition is multirange union, multiplication is intersection,
13188 * monus is set difference; the additive identity is
13189 * <tt>'{}'::%int4multirange</tt> and the multiplicative identity is
13190 * <tt>'{(,)}'::%int4multirange</tt>.
13191 *
13192 * @param token Provenance token to evaluate.
13193 * @param token2value Mapping from input gates to int4 multiranges.
13194 */
13195CREATE FUNCTION sr_interval_int(token ANYELEMENT, token2value REGCLASS)
13196 RETURNS int4multirange AS
13197$$
13198BEGIN
13199 RETURN provsql.provenance_evaluate_compiled(
13200 token,
13201 token2value,
13202 'interval_union',
13203 '{(,)}'::int4multirange
13204 );
13205END
13206$$ LANGUAGE plpgsql STRICT PARALLEL SAFE STABLE;
13207
13208/**
13209 * @brief Evaluate temporal provenance as a TIMESTAMP multirange
13210 *
13211 * Thin wrapper around :sqlfunc:`sr_temporal` retained for backward
13212 * compatibility; both compute the same union of validity intervals.
13213 *
13214 * @param token provenance token to evaluate
13215 * @param token2value mapping table from tokens to temporal validity ranges
13216 */
13217CREATE OR REPLACE FUNCTION union_tstzintervals(
13218 token UUID,
13219 token2value REGCLASS
13220)
13221RETURNS TSTZMULTIRANGE AS
13222$$
13223 SELECT sr_temporal(token, token2value)
13224$$ LANGUAGE SQL PARALLEL SAFE STABLE;
13225
13226/**
13227 * @brief Query a table as it was at a specific point in time
13228 *
13229 * Returns all rows whose temporal validity includes the given TIMESTAMP.
13230 *
13231 * @param tablename name of the provenance-tracked table
13232 * @param at_time the point in time to query
13233 */
13234CREATE OR REPLACE FUNCTION timetravel(
13235 tablename TEXT,
13236 at_time TIMESTAMPTZ
13237)
13238RETURNS SETOF RECORD
13239LANGUAGE plpgsql
13240AS
13241$$
13242BEGIN
13243 RETURN QUERY EXECUTE format(
13244 '
13245 SELECT
13246 %1$I.*,
13247 sr_temporal(provenance(), %2$L)
13248 FROM
13249 %1$I
13250 WHERE
13251 sr_temporal(provenance(), %2$L) @> %3$L::TIMESTAMPTZ
13252 ',
13253 tablename,
13254 'provsql.time_validity_view',
13255 at_time::TEXT
13256 );
13257END;
13258$$;
13259
13260/**
13261 * @brief Query a table for rows valid during a time interval
13262 *
13263 * Returns all rows whose temporal validity overlaps the given range.
13264 *
13265 * @param tablename name of the provenance-tracked table
13266 * @param from_time start of the time interval
13267 * @param to_time end of the time interval
13268 */
13269CREATE OR REPLACE FUNCTION timeslice(
13270 tablename TEXT,
13271 from_time TIMESTAMPTZ,
13272 to_time TIMESTAMPTZ
13273)
13274RETURNS SETOF RECORD
13275LANGUAGE plpgsql
13276AS
13277$$
13278BEGIN
13279 RETURN QUERY EXECUTE format(
13280 '
13281 SELECT
13282 %1$I.*,
13283 sr_temporal(provenance(), %2$L)
13284 FROM
13285 %1$I
13286 WHERE
13287 sr_temporal(provenance(), %2$L)
13288 && tstzrange(%3$L::TIMESTAMPTZ, %4$L::TIMESTAMPTZ)
13289 ',
13290 tablename,
13291 'provsql.time_validity_view',
13292 from_time::TEXT,
13293 to_time::TEXT
13294 );
13295END;
13296$$;
13297
13298/**
13299 * @brief Query the full temporal history of specific rows
13300 *
13301 * Returns all versions of rows matching the given column values,
13302 * with their temporal validity ranges.
13303 *
13304 * @param tablename name of the provenance-tracked table
13305 * @param col_names array of column names to filter on
13306 * @param col_values array of corresponding values to match
13307 */
13308CREATE OR REPLACE FUNCTION history(
13309 tablename TEXT,
13310 col_names TEXT[],
13311 col_values TEXT[]
13312)
13313RETURNS SETOF RECORD
13314LANGUAGE plpgsql
13315AS
13316$$
13317DECLARE
13318 condition TEXT := '';
13319 i INT;
13320BEGIN
13321 IF array_length(col_names, 1) IS NULL
13322 OR array_length(col_values, 1) IS NULL
13323 OR array_length(col_names, 1) != array_length(col_values, 1)
13324 THEN
13325 RAISE EXCEPTION 'col_names and col_values must have the same (non-null) length';
13326 END IF;
13327
13328 FOR i IN 1..array_length(col_names, 1)
13329 LOOP
13330 IF i > 1 THEN
13331 condition := condition || ' AND ';
13332 END IF;
13333 condition := condition || format('%I = %L', col_names[i], col_values[i]);
13334 END LOOP;
13335
13336 RETURN QUERY EXECUTE format(
13337 '
13338 SELECT
13339 %I.*,
13340 sr_temporal(provenance(), %L)
13341 FROM
13342 %I
13343 WHERE
13344 %s
13345 ',
13346 tablename,
13347 'provsql.time_validity_view',
13348 tablename,
13349 condition
13350 );
13351END;
13352$$;
13353
13354/**
13355 * @brief Get the valid time range for a specific tuple
13356 *
13357 * @param token provenance token of the tuple
13358 * @param tablename name of the table containing the tuple
13359 */
13360CREATE OR REPLACE FUNCTION get_valid_time(
13361 token UUID,
13362 tablename TEXT
13363)
13364RETURNS TSTZMULTIRANGE
13365LANGUAGE plpgsql
13366AS $$
13367DECLARE
13368 result TSTZMULTIRANGE;
13369BEGIN
13370 EXECUTE format(
13371 '
13372 SELECT
13373 sr_temporal(provenance(), %L)
13374 FROM
13375 %I
13376 WHERE
13377 provsql = %L
13378 ',
13379 'provsql.time_validity_view',
13380 tablename,
13381 token
13382 )
13383 INTO result;
13384
13385 RETURN result;
13386END;
13387$$;
13388
13389/**
13390 * @brief Undo a previously recorded update operation
13391 *
13392 * Traverses all provenance-tracked tables and rewrites their circuits
13393 * to apply monus with respect to the given update token, effectively
13394 * undoing the operation.
13395 *
13396 * @param c UUID of the update operation to undo (from update_provenance)
13397 */
13398CREATE OR REPLACE FUNCTION undo(
13399 c UUID
13400)
13401RETURNS UUID
13402LANGUAGE plpgsql
13403AS $$
13404DECLARE
13405 undo_query TEXT;
13406 undone_query TEXT;
13407 undo_token UUID;
13408 schema_rec RECORD;
13409 table_rec RECORD;
13410 row_rec RECORD;
13411 new_x UUID;
13412 tracking TEXT := current_setting('provsql.update_provenance');
13413BEGIN
13414 -- Test for the row, not for its query text: a TRANSACTION row has no
13415 -- query of its own, and undoing a whole transaction is exactly what it
13416 -- is there for.
13417 SELECT query INTO undone_query
13418 FROM update_provenance
13419 WHERE provsql = c
13420 LIMIT 1;
13421
13422 IF NOT FOUND THEN
13423 RAISE NOTICE 'Unable to find % in update_provenance', c;
13424 RETURN c;
13425 END IF;
13426
13427 SELECT query
13428 INTO undo_query
13429 FROM pg_stat_activity
13430 WHERE pid = pg_backend_pid();
13431
13432 undo_token := public.uuid_generate_v4();
13433 PERFORM create_gate(undo_token, 'update');
13434 INSERT INTO update_provenance(provsql, query, query_type, username, ts,
13435 valid_time, xid, tx_token)
13436 VALUES (
13437 undo_token,
13438 undo_query,
13439 'UNDO',
13440 current_user,
13441 CURRENT_TIMESTAMP,
13442 TSTZMULTIRANGE(tstzrange(CURRENT_TIMESTAMP, NULL)),
13443 pg_current_xact_id(),
13444 transaction_token()
13445 );
13446
13447 -- Off for the rewriting below, then back to what it was, for this
13448 -- transaction only: a session-level change would outlive it.
13449 PERFORM set_config('provsql.update_provenance', 'off', true);
13450
13451 FOR schema_rec IN
13452 SELECT nspname
13453 FROM pg_namespace
13454 WHERE nspname NOT IN ('pg_catalog','information_schema','pg_toast','pg_temp_1','pg_toast_temp_1')
13455 LOOP
13456 FOR table_rec IN
13457 EXECUTE format('SELECT tablename AS tname FROM pg_tables WHERE schemaname = %L', schema_rec.nspname)
13458 LOOP
13459 IF EXISTS (
13460 SELECT 1
13461 FROM information_schema.columns
13462 WHERE table_schema = schema_rec.nspname
13463 AND table_name = table_rec.tname
13464 AND table_name <> 'update_provenance'
13465 AND column_name = 'provsql'
13466 ) THEN
13467 FOR row_rec IN
13468 EXECUTE format('SELECT provsql AS x FROM %I.%I', schema_rec.nspname, table_rec.tname)
13469 LOOP
13470 new_x := replace_the_circuit(row_rec.x, c, undo_token);
13471 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2',
13472 schema_rec.nspname, table_rec.tname)
13473 USING new_x, row_rec.x;
13474 END LOOP;
13475 END IF;
13476 END LOOP;
13477 END LOOP;
13478
13479 PERFORM set_config('provsql.update_provenance', tracking, true);
13480
13481 RETURN undo_token;
13482END;
13483$$;
13484
13485/**
13486 * @brief Recursively rewrite a circuit to undo a specific operation
13487 *
13488 * Helper for undo(). Walks the circuit and replaces occurrences of
13489 * the target update gate with its monus.
13490 *
13491 * @param x provenance token to rewrite
13492 * @param c UUID of the update operation to undo
13493 * @param u UUID of the undo operation
13494 */
13495CREATE OR REPLACE FUNCTION replace_the_circuit(
13496 x UUID,
13497 c UUID,
13498 u UUID
13499)
13500RETURNS UUID
13501LANGUAGE plpgsql
13502AS $$
13503DECLARE
13504 nchildren UUID[];
13505 child UUID;
13506 ntoken UUID;
13507 ntype PROVENANCE_GATE;
13508BEGIN
13509 IF x = c THEN
13510 RETURN provenance_monus(c, u);
13511 -- update and input gates cannot have children
13512 ELSIF get_gate_type(x) = 'update' OR get_gate_type(x) = 'input' THEN
13513 RETURN x;
13514 ELSE
13515 nchildren := '{}';
13516 FOREACH child IN ARRAY get_children(x)
13517 LOOP
13518 nchildren := array_append(nchildren, replace_the_circuit(child, c, u));
13519 END LOOP;
13520
13521 ntoken := public.uuid_generate_v4();
13522 ntype := get_gate_type(x);
13523
13524 PERFORM create_gate(ntoken, ntype, nchildren);
13525 RETURN ntoken;
13526 END IF;
13527END;
13528$$;
13529
13530/**
13531 * @brief Rewrite a circuit, substituting one gate for another
13532 *
13533 * Walks @p x and rebuilds every gate above an occurrence of @p old over
13534 * @p new instead. Leaves that are not @p old come back unchanged, so a
13535 * token that does not mention @p old is returned as it is.
13536 *
13537 * @param x the token to rewrite
13538 * @param old the gate to substitute away
13539 * @param new the gate to put in its place
13540 */
13541CREATE OR REPLACE FUNCTION substitute_gate(
13542 x UUID,
13543 old UUID,
13544 new UUID
13545)
13546RETURNS UUID
13547LANGUAGE plpgsql
13548AS $$
13549DECLARE
13550 nchildren UUID[];
13551 child UUID;
13552 rewritten UUID;
13553 changed BOOLEAN := false;
13554 ntoken UUID;
13555 ntype PROVENANCE_GATE;
13556BEGIN
13557 IF x = old THEN
13558 RETURN new;
13559 END IF;
13560 ntype := get_gate_type(x);
13561 -- Leaves have no children to walk into.
13562 IF ntype IN ('input', 'update', 'rv', 'value', 'zero', 'one') THEN
13563 RETURN x;
13564 END IF;
13565 nchildren := '{}';
13566 FOREACH child IN ARRAY get_children(x)
13567 LOOP
13568 rewritten := substitute_gate(child, old, new);
13569 IF rewritten <> child THEN
13570 changed := true;
13571 END IF;
13572 nchildren := array_append(nchildren, rewritten);
13573 END LOOP;
13574 IF NOT changed THEN
13575 RETURN x;
13576 END IF;
13577 ntoken := public.uuid_generate_v4();
13578 PERFORM create_gate(ntoken, ntype, nchildren);
13579 RETURN ntoken;
13580END;
13581$$;
13582
13583/**
13584 * @brief Give a recorded data modification a different probability
13585 *
13586 * The @c update-gate counterpart of @c provsql.replace_input. A gate's
13587 * probability is written once, so "how likely is it that this
13588 * modification happened" is changed by minting a new @c update gate with
13589 * the new probability, logging it in @c update_provenance beside the one
13590 * it replaces, and rewriting every tracked row whose provenance mentions
13591 * the old gate to mention the new one instead -- the same walk @c undo
13592 * performs. The old gate and its log row are kept: the history of the
13593 * database is not rewritten, it is extended. The new log row, of type
13594 * @c REPLACE, has the validity of the row it replaces: the modification
13595 * keeps its time, only its probability changes.
13596 *
13597 * @param old the @c update gate to replace, as found in
13598 * @c update_provenance
13599 * @param p the new probability, in [0,1]
13600 * @return the new @c update gate
13601 */
13602CREATE OR REPLACE FUNCTION replace_update(
13603 old UUID,
13604 p double precision
13605)
13606RETURNS UUID
13607LANGUAGE plpgsql
13608AS $$
13609DECLARE
13610 new_token UUID;
13611 old_row RECORD;
13612 schema_rec RECORD;
13613 table_rec RECORD;
13614 row_rec RECORD;
13615 new_x UUID;
13616 tracking TEXT := current_setting('provsql.update_provenance');
13617BEGIN
13618 IF old IS NULL OR p IS NULL THEN
13619 RAISE EXCEPTION 'replace_update: neither argument may be NULL';
13620 END IF;
13621 IF get_gate_type(old) <> 'update' THEN
13622 RAISE EXCEPTION 'replace_update: % is not an update gate', old
13623 USING HINT = 'Use provsql.replace_input() for a tuple''s own input gate.';
13624 END IF;
13625
13626 SELECT * INTO old_row FROM update_provenance WHERE provsql = old LIMIT 1;
13627 IF old_row IS NULL THEN
13628 RAISE EXCEPTION 'replace_update: % is not recorded in update_provenance', old;
13629 END IF;
13630
13631 new_token := public.uuid_generate_v4();
13632 PERFORM create_gate(new_token, 'update');
13633 PERFORM set_prob(new_token, p);
13634
13635 INSERT INTO update_provenance(provsql, query, query_type, username, ts,
13636 valid_time, xid, tx_token)
13637 VALUES (new_token, old_row.query, 'REPLACE', current_user,
13638 CURRENT_TIMESTAMP,
13639 -- The modification keeps its time: only its probability changes,
13640 -- and the rows will carry the new gate in place of the old one.
13641 old_row.valid_time,
13642 pg_current_xact_id(), transaction_token());
13643
13644 -- Off for the rewriting below, then back to what it was, for this
13645 -- transaction only: a session-level change would outlive it.
13646 PERFORM set_config('provsql.update_provenance', 'off', true);
13647
13648 FOR schema_rec IN
13649 SELECT nspname
13650 FROM pg_namespace
13651 WHERE nspname NOT IN ('pg_catalog','information_schema','pg_toast','pg_temp_1','pg_toast_temp_1')
13652 LOOP
13653 FOR table_rec IN
13654 EXECUTE format('SELECT tablename AS tname FROM pg_tables WHERE schemaname = %L', schema_rec.nspname)
13655 LOOP
13656 IF EXISTS (
13657 SELECT 1
13658 FROM information_schema.columns
13659 WHERE table_schema = schema_rec.nspname
13660 AND table_name = table_rec.tname
13661 AND table_name <> 'update_provenance'
13662 AND column_name = 'provsql'
13663 ) THEN
13664 FOR row_rec IN
13665 EXECUTE format('SELECT provsql AS x FROM %I.%I', schema_rec.nspname, table_rec.tname)
13666 LOOP
13667 new_x := substitute_gate(row_rec.x, old, new_token);
13668 IF new_x <> row_rec.x THEN
13669 EXECUTE format('UPDATE %I.%I SET provsql = $1 WHERE provsql = $2',
13670 schema_rec.nspname, table_rec.tname)
13671 USING new_x, row_rec.x;
13672 END IF;
13673 END LOOP;
13674 END IF;
13675 END LOOP;
13676 END LOOP;
13677
13678 PERFORM set_config('provsql.update_provenance', tracking, true);
13679
13680 RETURN new_token;
13681END;
13682$$;
13683
13684-- The base validity mapping is a plain view over the data-modification log:
13685-- update_provenance is append-only and never has its provsql rewritten, so a
13686-- view stays correct (unlike a tracked table's mapping, which must be a
13687-- maintained mapping table -- see create_provenance_mapping(maintained)).
13688CREATE VIEW provsql.time_validity_view AS
13689 SELECT valid_time AS value, provsql AS provenance FROM provsql.update_provenance;
13690
13691/** @} */
13692
13693SET search_path TO public;
13694
13695-- Final constants-cache refresh: same rationale as at the end of
13696-- provsql.common.sql. On PG14+ this file is appended after the common
13697-- script, so this is the last statement of the generated install script;
13698-- the refresh must come after every object has been created for the
13699-- installing session's memoized constants to be complete.
13700SELECT provsql.reset_constants_cache();