PostgreSQL I/O functions and cast for the agg_token composite type. More...

#include "postgres.h"
#include "fmgr.h"
#include "catalog/pg_type.h"
#include "utils/uuid.h"
#include "utils/numeric.h"
#include "utils/fmgrprotos.h"
#include "utils/builtins.h"
#include "access/xact.h"
#include "executor/spi.h"
#include "access/htup_details.h"
#include "provsql_utils.h"
#include "agg_token.h"

Include dependency graph for agg_token.c:

Go to the source code of this file.

Functions
void	agg_token_set_value (agg_token aggtok, const char val, size_t len)
	Set the value of `aggtok` to the `len` first bytes of `val`.
const char *	agg_token_value_cstring (const agg_token *aggtok)
	The value of `aggtok`, as a C string.
Datum	agg_token_in (PG_FUNCTION_ARGS)
	Parse an `agg_token` value from its text representation.
Datum	agg_token_out (PG_FUNCTION_ARGS)
	Produce a display string for an `agg_token`.
Datum	agg_token_cast (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `text`, returning only the UUID part.
static bool	agg_token_val_is_null (const agg_token *aggtok)
	True when an `agg_token` value string cannot carry a number.
static void	warn_conversion_once (const char *target)
	The "provenance information is lost" warning of a conversion, once for a statement and for each target type.
static void	warn_ordering_once (void)
	The "sorted on the plain value" warning, once for a statement.
static bool	text_is_number (const char *v)
	Whether `v` is the text of a number, as `numeric_in` would read it: the check a comparison makes before parsing, since parsing what is not one would raise where a comparison must not.
Datum	agg_token_btree_cmp (PG_FUNCTION_ARGS)
	Order two `agg_token` values by the value each carries.
Datum	agg_token_to_numeric (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `numeric`, extracting only the value.
Datum	agg_token_value (PG_FUNCTION_ARGS)
	Extract the running value of an `agg_token` as `numeric`.
Datum	agg_token_to_float8 (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `double` precision, extracting only the value.
Datum	agg_token_to_int4 (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `integer`, extracting only the value.
Datum	agg_token_to_int8 (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `bigint`, extracting only the value.
Datum	agg_token_to_bool (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `boolean`, extracting only the value.
Datum	agg_token_to_text (PG_FUNCTION_ARGS)
	Cast an `agg_token` to `text`, extracting only the value.
Datum	agg_token_plain_text (PG_FUNCTION_ARGS)
	The value of an `agg_token` as `text`, NULL for a NULL value, without the "provenance information is lost" warning.
Datum	row_number_as_rank (PG_FUNCTION_ARGS)
	The `agg_token` of `rank()` standing for `row_number()`.

Detailed Description

PostgreSQL I/O functions and cast for the agg_token composite type.

Implements the three SQL-callable C functions that back the agg_token type:

agg_token_in() – text → agg_token (input function)
agg_token_out() – agg_token → text (output function)
agg_token_cast() – agg_token → text (cast, extracts the UUID part)

The on-wire text format is ( UUID , value ) where UUID is the 36-character hyphenated UUID of the provenance gate and value is the aggregate running value.

Definition in file agg_token.c.

Function Documentation

◆ agg_token_btree_cmp()

Datum agg_token_btree_cmp ( PG_FUNCTION_ARGS )

Order two agg_token values by the value each carries.

An agg_token is a value and a provenance, and the value is the one the data as it is gives: ordering by it – ORDER BY, DISTINCT, a GROUP BY that sorts – is ordering by that one value, which another possible world need not agree with. The warning says so, once for the statement rather than once per comparison, since a sort makes n log n of them.

A token with no value (an aggregate over no row) sorts first, as a NULL does under NULLS FIRST; two numbers are compared as numbers and anything else by its text, so that the order is total whatever the aggregate's own type.

Definition at line 314 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_cast()

Datum agg_token_cast ( PG_FUNCTION_ARGS )

Cast an agg_token to text, returning only the UUID part.

This is used when the caller needs the provenance circuit UUID stored in the token rather than the aggregate value.

Returns: Text datum containing the UUID string of the token.

Definition at line 182 of file agg_token.c.

◆ agg_token_in()

Datum agg_token_in ( PG_FUNCTION_ARGS )

Parse an agg_token value from its text representation.

Expected format: "( UUID , value )" with a single space around the comma and at the outer parentheses. Raises ERROR on malformed input.

Returns: Pointer to the newly allocated agg_token.

Definition at line 96 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_out()

Datum agg_token_out ( PG_FUNCTION_ARGS )

Produce a display string for an agg_token.

Default: returns "value (*)" (the running value followed by " (*)"), matching EXPLAIN and direct CAST to text. Where the value is SQL NULL it is "(*)" alone: SQL writes nothing for a NULL, so writing "NULL" would put four characters where a reader expects none, and a text client would read them as data.

When the provsql.aggtoken_text_as_uuid GUC is on, returns the underlying provenance UUID instead. This is the form ProvSQL Studio enables per session so agg_token cells in a result table expose the circuit root UUID for click-through; the user-facing "value (*)" string is recovered via the provsql.agg_token_value_text(uuid) helper.

Returns: C-string representation of the agg_token.

Definition at line 147 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_plain_text()

Datum agg_token_plain_text ( PG_FUNCTION_ARGS )

The value of an agg_token as text, NULL for a NULL value, without the "provenance information is lost" warning.

The internal accessor of the rewriter's sort keys: an ORDER BY on an aggregate result sorts on this value, read in the aggregate's type, while the column itself keeps its agg_token.

Definition at line 522 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_set_value()

void agg_token_set_value	(	agg_token *	aggtok,
		const char *	val,
		size_t	len )

Set the value of aggtok to the len first bytes of val.

A value too long for agg_token::val keeps its first AGG_TOKEN_PREFIX_LEN bytes, marked by AGG_TOKEN_TRUNCATED in the last byte; aggtok must be zeroed.

Definition at line 36 of file agg_token.c.

Here is the caller graph for this function:

◆ agg_token_to_bool()

Datum agg_token_to_bool ( PG_FUNCTION_ARGS )

Cast an agg_token to boolean, extracting only the value.

The value of a boolean aggregate (bool_or, bool_and, every). Emits a WARNING that provenance information is lost during the conversion.

Returns: Boolean datum parsed from the aggregate value string.

Definition at line 472 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_to_float8()

Datum agg_token_to_float8 ( PG_FUNCTION_ARGS )

Cast an agg_token to double precision, extracting only the value.

Emits a WARNING that provenance information is lost during the conversion.

Returns: Float8 datum parsed from the aggregate value string.

Definition at line 402 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_to_int4()

Datum agg_token_to_int4 ( PG_FUNCTION_ARGS )

Cast an agg_token to integer, extracting only the value.

Emits a WARNING that provenance information is lost during the conversion.

Returns: Int32 datum parsed from the aggregate value string.

Definition at line 425 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_to_int8()

Datum agg_token_to_int8 ( PG_FUNCTION_ARGS )

Cast an agg_token to bigint, extracting only the value.

Emits a WARNING that provenance information is lost during the conversion.

Returns: Int64 datum parsed from the aggregate value string.

Definition at line 448 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_to_numeric()

Datum agg_token_to_numeric ( PG_FUNCTION_ARGS )

Cast an agg_token to numeric, extracting only the value.

Emits a WARNING that provenance information is lost during the conversion.

Returns: Numeric datum parsed from the aggregate value string.

Definition at line 350 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_to_text()

Datum agg_token_to_text ( PG_FUNCTION_ARGS )

Cast an agg_token to text, extracting only the value.

Unlike agg_token_cast which returns the UUID part, this returns the aggregate value as text. Emits a WARNING that provenance information is lost during the conversion.

Returns: Text datum containing the aggregate value string.

Definition at line 494 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_val_is_null()

bool agg_token_val_is_null ( const agg_token * aggtok )

static

True when an agg_token value string cannot carry a number.

An empty or literal "NULL" value string (an aggregate whose value is SQL NULL) must convert to SQL NULL rather than feed the type-input function a string it rejects.

Definition at line 208 of file agg_token.c.

Here is the caller graph for this function:

◆ agg_token_value()

Datum agg_token_value ( PG_FUNCTION_ARGS )

Extract the running value of an agg_token as numeric.

Unlike agg_token_to_numeric, this does not emit the "provenance information is lost" warning: it is the internal accessor used by the provenance-preserving agg_token arithmetic operators (which keep the provenance in a gate_arith circuit), where no provenance is dropped.

Returns: Numeric datum parsed from the aggregate value string.

Definition at line 379 of file agg_token.c.

Here is the call graph for this function:

◆ agg_token_value_cstring()

const char * agg_token_value_cstring ( const agg_token * aggtok )

The value of aggtok, as a C string.

The value stored in the token, or, when it is only a prefix, the value of its gate, read with provsql.agg_token_value_text; the prefix is returned if the gate gives none that starts with it.

Definition at line 55 of file agg_token.c.

Here is the caller graph for this function:

◆ row_number_as_rank()

Datum row_number_as_rank ( PG_FUNCTION_ARGS )

The agg_token of rank() standing for row_number().

The two are equal when the ORDER BY of the window leaves no ties; with ties, SQL itself does not determine which row gets which number. The rank is what is tracked: when row_number differs from it, a warning says so, once per statement.

Parameters

rank	The `agg_token` of the rank of the row.
row_number	The row number PostgreSQL gave the row.

Returns: rank.

Definition at line 545 of file agg_token.c.

Here is the call graph for this function:

◆ text_is_number()

bool text_is_number ( const char * v )

static

Whether v is the text of a number, as numeric_in would read it: the check a comparison makes before parsing, since parsing what is not one would raise where a comparison must not.

Definition at line 273 of file agg_token.c.

Here is the caller graph for this function:

◆ warn_conversion_once()

void warn_conversion_once ( const char * target )

static

The "provenance information is lost" warning of a conversion, once for a statement and for each target type.

A conversion runs for every row, and so did its warning: a query over a large relation wrote one line per row, which says nothing the first does not and which has filled a server log before. The statement is identified by provsql_stmt_serial, which the executor hook bumps for the user's outermost statement; a conversion outside any statement of the user (a direct call in a function the rewriting runs) warns once as well.

Definition at line 224 of file agg_token.c.

Here is the caller graph for this function:

◆ warn_ordering_once()

void warn_ordering_once ( void )

static

The "sorted on the plain value" warning, once for a statement.

Definition at line 258 of file agg_token.c.

Here is the caller graph for this function:

Functions

Detailed Description

Function Documentation

◆ agg_token_btree_cmp()

◆ agg_token_cast()

◆ agg_token_in()

◆ agg_token_out()

◆ agg_token_plain_text()

◆ agg_token_set_value()

◆ agg_token_to_bool()

◆ agg_token_to_float8()

◆ agg_token_to_int4()

◆ agg_token_to_int8()

◆ agg_token_to_numeric()

◆ agg_token_to_text()

◆ agg_token_val_is_null()

◆ agg_token_value()

◆ agg_token_value_cstring()

◆ row_number_as_rank()

◆ text_is_number()

◆ warn_conversion_once()

◆ warn_ordering_once()