![]() |
ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
|
The gate-building SQL functions the query rewriter calls once per row or per group, in C. More...
#include "postgres.h"#include "fmgr.h"#include "catalog/namespace.h"#include "catalog/pg_type.h"#include "parser/parse_coerce.h"#include "lib/stringinfo.h"#include "utils/array.h"#include "utils/builtins.h"#include "utils/hsearch.h"#include "utils/lsyscache.h"#include "utils/memutils.h"#include "utils/uuid.h"#include "agg_token.h"#include "gate_builders.h"#include "provsql_mmap.h"#include "provsql_utils.h"
Go to the source code of this file.
Classes | |
| struct | PlantedScope |
| A working table with planted gates. More... | |
| struct | PlantedEntry |
| struct | VarcharCast |
Macros | |
| #define | NAME_FLUSH 8192 |
| #define | WRITTEN_VALUES_MAX 65536 |
Functions | |
| static void | name_flush (StringInfo buf) |
Hash what buf holds, and empty it. | |
| static void | name_begin (StringInfo buf, const char *prefix) |
| Start the name of a gate address. | |
| static void | name_add_uuid (StringInfo buf, const pg_uuid_t *u) |
Append a UUID in the text form of uuid_out. | |
| static void | name_add_uuid_array (StringInfo buf, const pg_uuid_t *u, int n) |
Append the text form of a uuid[], "{u1,u2,...}". | |
| static pg_uuid_t | name_end (StringInfo buf) |
The version-5 UUID of the name accumulated in buf. | |
| static pg_uuid_t | constant_uuid (const char *text) |
The UUID text (one of the constants of provsql_utils.h). | |
| static const pg_uuid_t * | address_of_zero (void) |
| static const pg_uuid_t * | address_of_one (void) |
| static int | token_cmp (const void *a, const void *b) |
| static Datum | uuid_result (const pg_uuid_t *u) |
| static int | filtered_tokens (ArrayType *arr, const pg_uuid_t *neutral, pg_uuid_t **out) |
The elements of a uuid[] that are neither NULL nor neutral, in order. | |
| static pg_uuid_t | canonical_address (const char *canonical_prefix, const pg_uuid_t *children, int n) |
The canonical address, "<prefix>{sorted children}". | |
| static Oid | temp_table_oid (const char *name) |
OID of the temporary table name of this backend, if any. | |
| static void | planted_forget (PlantedScope *scope) |
| static PlantedScope * | planted_open_scope (const char *name, bool reset) |
Open the scope of the working table name, just (re)created: forget what was planted for the table it replaces, and for every working table that no longer exists. | |
| static bool | is_planted (const pg_uuid_t *address) |
| pg_uuid_t | provsql_plant_canonical (const char *work_name, gate_type type, const pg_uuid_t *children, int n, const pg_uuid_t *target, unsigned info1, unsigned info2) |
| Pre-create ("plant") a gate at the canonical address of a multiset of tokens, for the working table of the recursive CTE being lowered. | |
| Datum | planted_scope (PG_FUNCTION_ARGS) |
SQL entry point of planted_open_scope(), called by the drivers of recursive CTEs right after they (re)create the working table. | |
| Datum | plant_canonical (PG_FUNCTION_ARGS) |
SQL entry point of provsql_plant_canonical(). | |
| static pg_uuid_t | nary_gate (gate_type type, const char *plain_prefix, const char *canonical_prefix, const pg_uuid_t *children, int n) |
A gate of type type over children, unless this backend planted one at the canonical address of their multiset. | |
| Datum | provenance_times (PG_FUNCTION_ARGS) |
| โ of a list of tokens. | |
| static int | drop_neutral (const pg_uuid_t *tokens, int n, const pg_uuid_t *neutral, pg_uuid_t *out) |
| pg_uuid_t | provsql_build_times (const pg_uuid_t *tokens, int n) |
โ of n tokens: ๐ dropped, none gives ๐, one is returned. | |
| Datum | provenance_plus (PG_FUNCTION_ARGS) |
| โ of an array of tokens. | |
| pg_uuid_t | provsql_build_plus (const pg_uuid_t *tokens, int n) |
โ of n tokens: ๐ dropped, none gives ๐, one is returned. | |
| static char * | varchar_of_argument (FunctionCallInfo fcinfo, int argno) |
CAST(val AS varchar) of argument argno, as a C string. | |
| void | provsql_gate_builders_forget (void) |
Forget what gate_builders.c remembers of the store (planted gates, value gates written). | |
| static pg_uuid_t | value_gate (const char *prefix, const char *suffix, const char *extra) |
The value gate of the text str, at the address named name ("value" followed by str, or "null"). | |
| static Datum | semimod_gate (const pg_uuid_t *value_token, const pg_uuid_t *token) |
The semimod gate value_token โ token. | |
| static const pg_uuid_t * | semimod_token_argument (FunctionCallInfo fcinfo) |
| Datum | provenance_semimod (PG_FUNCTION_ARGS) |
The semimodule gate val โ token of an aggregated row. | |
| Datum | provenance_semimod_nullable (PG_FUNCTION_ARGS) |
provenance_semimod for the aggregates that see their NULL inputs (array_agg, json_agg, ...): a NULL value gives a gate over the constant value gate gate_null(). | |
| static bool | same_token (const pg_uuid_t *a, const pg_uuid_t *b) |
| Datum | provenance_semimod_nested (PG_FUNCTION_ARGS) |
The semimodule gate of a row whose value is itself an aggregate result: semimod(the inner aggregate's gate, token). | |
| Datum | provenance_semimod_flat (PG_FUNCTION_ARGS) |
The contributions semimod(v_i, token โ k_i) of the aggregate result val, whose gate aggregates the contributions semimod(v_i, k_i), for an aggregate of the same kind over it. | |
| Datum | provenance_aggregate (PG_FUNCTION_ARGS) |
The agg gate of a group, paired with the aggregate's value. | |
| Datum | provenance_monus (PG_FUNCTION_ARGS) |
token1 โ token2. | |
| pg_uuid_t | provsql_build_monus (const pg_uuid_t *token1, const pg_uuid_t *token2) |
token1 โ token2, with X โ X = ๐ โ X = ๐ and X โ ๐ = X. | |
| Datum | provenance_delta (PG_FUNCTION_ARGS) |
ฮด(token). | |
| pg_uuid_t | provsql_build_delta (const pg_uuid_t *token) |
ฮด(token), with ฮด(๐) = ๐ and ฮด(๐) = ๐. | |
| static bool | is_shift_of (const pg_uuid_t *sum, const pg_uuid_t *base) |
Is sum the gate of base plus a nonzero constant? | |
| static bool | cmp_impossible (const pg_uuid_t *left, Oid op, const pg_uuid_t *right) |
Does left op right hold in no world, by its shape alone? | |
| Datum | provenance_cmp (PG_FUNCTION_ARGS) |
The comparison gate left op right of a HAVING condition. | |
| Datum | annotate (PG_FUNCTION_ARGS) |
A transparent annotation gate over token, carrying extra. | |
| Datum | inversion_free_key (PG_FUNCTION_ARGS) |
The order key of an input on the inversion-free route, "K<factor> <bytes of root>:<root><bytes of sec>:<sec>". | |
| static pg_uuid_t | assumed_gate (const pg_uuid_t *token, const char *assumption, unsigned info1) |
The assumed wrapper of token under assumption, with info1 as the route tag (0 for none). | |
| Datum | provenance_assume (PG_FUNCTION_ARGS) |
Wrap token in the assumption marker assumption ('boolean' or 'absorptive'). | |
| Datum | assume_boolean (PG_FUNCTION_ARGS) |
The Boolean-assumption wrapper the safe-query rewriter puts on every per-row root, tagged PROVSQL_ROUTE_SQ_REWRITE. | |
| Datum | provenance_project (PG_FUNCTION_ARGS) |
The where-provenance project gate of token: its text lists, for each output position, the input position it comes from (NULL for a position given as 0), as '{{in,out},...}'. | |
| Datum | provenance_eq (PG_FUNCTION_ARGS) |
The where-provenance eq gate of token, equating positions pos1 and pos2 (its infos). | |
| Datum | provenance_arith (PG_FUNCTION_ARGS) |
The arith gate applying operator op (a provsql_arith_op, its info1) to children, in order. | |
Variables | |
| static const unsigned char | provsql_ns [UUID_LEN] |
uuid_ns_provsql(), the namespace of every gate address. | |
| static provsql_sha1_ctx | name_hash |
The hash of the name being built, which takes the buffer's content whenever it grows past NAME_FLUSH bytes: the name of a gate with millions of children (the agg of a SUM over millions of rows) is then never held whole. | |
| static HTAB * | planted = NULL |
| static PlantedScope * | planted_scopes = NULL |
| static PlantedScope * | planted_current = NULL |
| static int | planted_next_id = 0 |
| static HTAB * | written_values = NULL |
The gate-building SQL functions the query rewriter calls once per row or per group, in C.
These functions used to be PL/pgSQL. Each inner statement of a PL/pgSQL function runs through SPI, an executor start-up and shutdown of about 2 ยตs, and their keys went through the text form of uuid[] and back; at one call per output row this was most of the cost of provenance tracking. The C versions build the same gates at the same addresses: a gate is addressed by the version-5 UUID, in the ProvSQL namespace, of a text name ("times{u1,u2}", ...), and the names built here are, byte for byte, the ones the PL/pgSQL code built. The regression test gate_builders keeps the former bodies as reference functions and compares the two.
Definition in file gate_builders.c.
| #define NAME_FLUSH 8192 |
Definition at line 48 of file gate_builders.c.
| #define WRITTEN_VALUES_MAX 65536 |
Definition at line 527 of file gate_builders.c.
|
static |
Definition at line 125 of file gate_builders.c.


|
static |
Definition at line 118 of file gate_builders.c.


| Datum annotate | ( | PG_FUNCTION_ARGS | ) |
A transparent annotation gate over token, carrying extra.
The address hashes extra along with the child: two annotations of one token with different texts are different gates. NULL on a NULL token.
Definition at line 962 of file gate_builders.c.

| Datum assume_boolean | ( | PG_FUNCTION_ARGS | ) |
The Boolean-assumption wrapper the safe-query rewriter puts on every per-row root, tagged PROVSQL_ROUTE_SQ_REWRITE.
Definition at line 1044 of file gate_builders.c.

The assumed wrapper of token under assumption, with info1 as the route tag (0 for none).
Definition at line 1010 of file gate_builders.c.


|
static |
The canonical address, "<prefix>{sorted children}".
Sorting identifies a product with every reordering of its factors, which requires a commutative \(\otimes\), as in every semiring ProvSQL evaluates.
Definition at line 171 of file gate_builders.c.


Does left op right hold in no world, by its shape alone?
Recognised: x+c = x with c a nonzero constant, in either order, the comparison of a row's rank with itself shifted that a self-join on consecutive ranks builds for each row paired with itself. Cheap, and deliberately narrow: a row it rules out is one the rewriting may drop.
Definition at line 910 of file gate_builders.c.


|
static |
The UUID text (one of the constants of provsql_utils.h).
Definition at line 114 of file gate_builders.c.

The elements of a uuid[] that are neither NULL nor neutral, in order.
*out is palloc'd. Definition at line 146 of file gate_builders.c.

| Datum inversion_free_key | ( | PG_FUNCTION_ARGS | ) |
The order key of an input on the inversion-free route, "K<factor> <bytes of root>:<root><bytes of sec>:<sec>".
Strict.
Definition at line 989 of file gate_builders.c.
|
static |
Is sum the gate of base plus a nonzero constant?
The aggregate-value arithmetic builds x+c as a gate_arith PLUS over the token of x and a gate_value; tokens being content-addressed, the same x is the same token.
Definition at line 878 of file gate_builders.c.


|
static |
Append a UUID in the text form of uuid_out.
Definition at line 70 of file gate_builders.c.

|
static |
Append the text form of a uuid[], "{u1,u2,...}".
Definition at line 85 of file gate_builders.c.


|
static |
Start the name of a gate address.
The buffer opens with the namespace, which the version-5 UUID hashes in front of the name.
Definition at line 62 of file gate_builders.c.


|
static |
The version-5 UUID of the name accumulated in buf.
Definition at line 100 of file gate_builders.c.


|
static |
Hash what buf holds, and empty it.
Definition at line 51 of file gate_builders.c.


|
static |
A gate of type type over children, unless this backend planted one at the canonical address of their multiset.
Definition at line 360 of file gate_builders.c.


| Datum plant_canonical | ( | PG_FUNCTION_ARGS | ) |
SQL entry point of provsql_plant_canonical().
Definition at line 339 of file gate_builders.c.

|
static |
|
static |
Open the scope of the working table name, just (re)created: forget what was planted for the table it replaces, and for every working table that no longer exists.
Definition at line 263 of file gate_builders.c.


| Datum planted_scope | ( | PG_FUNCTION_ARGS | ) |
SQL entry point of planted_open_scope(), called by the drivers of recursive CTEs right after they (re)create the working table.
Definition at line 331 of file gate_builders.c.

| Datum provenance_aggregate | ( | PG_FUNCTION_ARGS | ) |
The agg gate of a group, paired with the aggregate's value.
The address hashes everything the gate records: the aggregate function and the scalar flag (info1 and the high bit of info2), the children, then the result type (the low bits of info2) and the value text (the extra), after a colon each. A gate's infos and text are written once, so what is written has to follow from the address: SUM(x) and AVG(x) over the same children, a scalar and a grouped aggregate, array_agg over integers and over their texts (same children, another result type), or a floating-point sum whose rounding depends on the plan, are all different gates. NULL children are rows whose value was NULL; they are dropped. No child gives ๐ for a group, and an agg gate without children for a scalar aggregation, whose value over no row is still defined.
Definition at line 732 of file gate_builders.c.

| Datum provenance_arith | ( | PG_FUNCTION_ARGS | ) |
The arith gate applying operator op (a provsql_arith_op, its info1) to children, in order.
Definition at line 1136 of file gate_builders.c.

| Datum provenance_assume | ( | PG_FUNCTION_ARGS | ) |
Wrap token in the assumption marker assumption ('boolean' or 'absorptive').
NULL on a NULL token.
Definition at line 1029 of file gate_builders.c.

| Datum provenance_cmp | ( | PG_FUNCTION_ARGS | ) |
The comparison gate left op right of a HAVING condition.
A comparison with a NULL operand is unknown in every possible world: the row is annotated ๐. Hence not strict: a NULL result would read as the neutral of โ and turn "unknown" into "certainly true".
Definition at line 927 of file gate_builders.c.

| Datum provenance_delta | ( | PG_FUNCTION_ARGS | ) |
ฮด(token).
A NULL token is an untracked source, ๐, and ฮด(๐) = ๐; ฮด(๐) = ๐.
Definition at line 846 of file gate_builders.c.

| Datum provenance_eq | ( | PG_FUNCTION_ARGS | ) |
The where-provenance eq gate of token, equating positions pos1 and pos2 (its infos).
Definition at line 1110 of file gate_builders.c.

| Datum provenance_monus | ( | PG_FUNCTION_ARGS | ) |
token1 โ token2.
A NULL second argument is the row without a match in the outer join of the difference: nothing to subtract, and X โ ๐ = X. (Not the NULL โก ๐ of provenance_times: each combinator reads NULL as its own neutral.) X โ X = ๐ and ๐ โ X = ๐ are applied as well.
Definition at line 807 of file gate_builders.c.

| Datum provenance_plus | ( | PG_FUNCTION_ARGS | ) |
โ of an array of tokens.
Strict.
A NULL token stands for a row absent from the disjunction: it reads as the โ-neutral ๐ and is dropped, like gate_zero itself. No survivor gives ๐, a single one is returned as it is. (The PL/pgSQL version returned, for no survivor, a plus gate without children: array_length of the empty selection is NULL, which sent that case to the general branch. Evaluators read such a gate as ๐, and stored circuits may contain it.)
Definition at line 435 of file gate_builders.c.

| Datum provenance_project | ( | PG_FUNCTION_ARGS | ) |
The where-provenance project gate of token: its text lists, for each output position, the input position it comes from (NULL for a position given as 0), as '{{in,out},...}'.
Definition at line 1060 of file gate_builders.c.

| Datum provenance_semimod | ( | PG_FUNCTION_ARGS | ) |
The semimodule gate val โ token of an aggregated row.
A NULL value does not take part in the aggregate (SQL aggregates skip NULL inputs; count(*) passes a constant 1): no gate, NULL is returned and provenance_aggregate drops it.
Definition at line 601 of file gate_builders.c.

| Datum provenance_semimod_flat | ( | PG_FUNCTION_ARGS | ) |
The contributions semimod(v_i, token โ k_i) of the aggregate result val, whose gate aggregates the contributions semimod(v_i, k_i), for an aggregate of the same kind over it.
token โ (โ k_i โ v_i) = โ (token โ k_i) โ v_i: the outer aggregate of the rows of the groups, in every semiring. An empty array for a NULL value, which the outer aggregate skips.
Definition at line 672 of file gate_builders.c.

| Datum provenance_semimod_nested | ( | PG_FUNCTION_ARGS | ) |
The semimodule gate of a row whose value is itself an aggregate result: semimod(the inner aggregate's gate, token).
The contribution of an outer aggregate that reads an aggregate result of another kind (an avg of a count, a max of a sum, an aggregate of an arithmetic expression over aggregates). Such a value is not one value of the database but one per possible world, so the M side of the semimod is the inner aggregate's own gate rather than a gate_value: an evaluator that reads a value per world (the sampler) resolves it, and the closed forms, which read the M side as a constant, decline it.
Definition at line 648 of file gate_builders.c.

| Datum provenance_semimod_nullable | ( | PG_FUNCTION_ARGS | ) |
provenance_semimod for the aggregates that see their NULL inputs (array_agg, json_agg, ...): a NULL value gives a gate over the constant value gate gate_null().
Definition at line 620 of file gate_builders.c.

| Datum provenance_times | ( | PG_FUNCTION_ARGS | ) |
โ of a list of tokens.
A NULL token is the token slot of an untracked source, which is certain: it reads as the โ-neutral ๐ and is dropped, like gate_one itself. No survivor gives ๐, a single one is returned as it is.
Definition at line 388 of file gate_builders.c.

ฮด(token), with ฮด(๐) = ๐ and ฮด(๐) = ๐.
Definition at line 857 of file gate_builders.c.


token1 โ token2, with X โ X = ๐ โ X = ๐ and X โ ๐ = X.
Definition at line 822 of file gate_builders.c.


โ of n tokens: ๐ dropped, none gives ๐, one is returned.
Definition at line 444 of file gate_builders.c.


โ of n tokens: ๐ dropped, none gives ๐, one is returned.
Definition at line 410 of file gate_builders.c.


| void provsql_gate_builders_forget | ( | void | ) |
Forget what gate_builders.c remembers of the store (planted gates, value gates written).
For circuit_cleanup, which may remove gates.
Definition at line 529 of file gate_builders.c.


| pg_uuid_t provsql_plant_canonical | ( | const char * | work_name, |
| gate_type | type, | ||
| const pg_uuid_t * | children, | ||
| int | n, | ||
| const pg_uuid_t * | target, | ||
| unsigned | info1, | ||
| unsigned | info2 ) |
Pre-create ("plant") a gate at the canonical address of a multiset of tokens, for the working table of the recursive CTE being lowered.
The gate, of type type (gate_plus or gate_times), has the single child target and the given infos; its address is remembered in this backend, where provenance_plus / provenance_times return it in place of an ordinary gate over children. Defined in gate_builders.c.
| work_name | working table the tokens belong to; NULL for the one declared last by planted_scope() |
| type | gate_plus or gate_times |
| children | the multiset the planted gate stands for |
| n | number of children |
| target | root of the certified circuit, the gate's single child |
| info1 | first info of the planted gate |
| info2 | second info of the planted gate |
Definition at line 292 of file gate_builders.c.


The semimod gate value_token โ token.
Definition at line 573 of file gate_builders.c.


|
static |
|
static |
OID of the temporary table name of this backend, if any.
Definition at line 232 of file gate_builders.c.

|
static |
|
static |
|
static |
The value gate of the text str, at the address named name ("value" followed by str, or "null").
Definition at line 540 of file gate_builders.c.


|
static |
CAST(val AS varchar) of argument argno, as a C string.
Definition at line 476 of file gate_builders.c.

|
static |
The hash of the name being built, which takes the buffer's content whenever it grows past NAME_FLUSH bytes: the name of a gate with millions of children (the agg of a SUM over millions of rows) is then never held whole.
Names are built one at a time, from name_begin to name_end.
Definition at line 47 of file gate_builders.c.
|
static |
Definition at line 226 of file gate_builders.c.
|
static |
Definition at line 228 of file gate_builders.c.
|
static |
Definition at line 229 of file gate_builders.c.
|
static |
Definition at line 227 of file gate_builders.c.
|
static |
uuid_ns_provsql(), the namespace of every gate address.
Definition at line 35 of file gate_builders.c.
|
static |
Definition at line 526 of file gate_builders.c.