Provenance output

Functions for visualizing and exporting provenance circuits in various formats. More...

Functions
TEXT	provsql.view_circuit (UUID token, REGCLASS token2desc, INT dbg=0)
	Return a DOT or TEXT visualization of the provenance circuit.
TEXT	provsql.compile_to_ddnnf_dot (UUID token, TEXT compiler='')
	Return a DOT visualisation of the d-DNNF compiled from the provenance circuit.
TEXT	provsql.compile_to_ddnnf (UUID token, TEXT compiler='')
	Return the compiled d-DNNF of a provenance circuit in the c2d / d4 ".nnf" TEXT interchange format.
jsonb	provsql.ddnnf_stats (UUID token, TEXT compiler='')
	Structural statistics of the d-DNNF a compiler produces for a provenance circuit.
TEXT	provsql.tseytin_cnf (UUID token, BOOLEAN weighted=TRUE, BOOLEAN mapping=TRUE)
	Return the DIMACS CNF (Tseytin transformation) of the provenance circuit.
jsonb	provsql.tseytin_cnf_mapping_json (UUID token)
	Map each DIMACS variable of tseytin_cnf back to its provenance input.
TABLE	provsql.tseytin_cnf_mapping (UUID token)
TEXT	provsql.tree_decomposition_dot (UUID token)
	Return a DOT visualisation of the tree decomposition of the provenance circuit.
BOOLEAN	provsql.tool_available (TEXT name)
	Report whether an external tool is on the backend's resolved PATH.
CREATE TABLE IF NOT EXISTS	provsql.tool_overrides (name TEXT PRIMARY KEY, removed BOOLEAN NOT NULL DEFAULT false, kind TEXT, executable TEXT, operations TEXT[], input_formats TEXT[], output_format TEXT, parser TEXT, preference INT, enabled BOOLEAN, dependencies TEXT[], argtpl TEXT, argtpl_circuit TEXT, endpoint TEXT)
	Persistent overrides overlaid on the compiled-in tool seed.
TABLE	provsql.tool_registry_list ()
	Set-returning listing backing the provsql.tools view.
VOID	provsql.register_tool (TEXT name, TEXT executable=NULL, TEXT kind='cli', TEXT[] operations=NULL, TEXT[] input_formats=NULL, TEXT output_format=NULL, TEXT parser=NULL, TEXT argtpl=NULL, TEXT argtpl_circuit=NULL, INT preference=0, BOOLEAN enabled=true, TEXT endpoint=NULL)
	Register a tool, or replace the RECORD with the same logical name.
VOID	provsql.unregister_tool (TEXT name)
	Unregister a tool; errors on an unknown tool name.
VOID	provsql.set_tool_enabled (TEXT name, BOOLEAN enabled)
	Enable/disable a tool; errors on an unknown tool name.
VOID	provsql.set_tool_preference (TEXT name, INT preference)
	Set a tool's preference; errors on an unknown tool name.
TABLE	provsql._probability_benchmark_one (UUID in_token, TEXT in_method, TEXT in_args=NULL)
	Time a single probability_evaluate call and return one row.
TABLE	provsql.probability_benchmark (UUID token, INT monte_carlo_samples=10000, TEXT weightmc_args='0.8;0.2')
	Time every probability-evaluation method on a single circuit token.
TEXT	provsql.to_provxml (UUID token, REGCLASS token2desc=NULL)
	Return an XML representation of the provenance circuit.
UUID	provsql.provenance ()
	Return the provenance token of the current query result tuple.
TEXT	provsql.where_provenance (UUID token)
	Compute where-provenance for a result tuple.

Variables
CREATE OR REPLACE VIEW tools AS SELECT	provsql.name
	Read-only view of the registered tools.
CREATE OR REPLACE VIEW tools AS SELECT	provsql.kind
CREATE OR REPLACE VIEW tools AS SELECT	provsql.executable
CREATE OR REPLACE VIEW tools AS SELECT	provsql.operations
CREATE OR REPLACE VIEW tools AS SELECT	provsql.input_formats
CREATE OR REPLACE VIEW tools AS SELECT	provsql.output_format
CREATE OR REPLACE VIEW tools AS SELECT	provsql.parser
CREATE OR REPLACE VIEW tools AS SELECT	provsql.preference
CREATE OR REPLACE VIEW tools AS SELECT	provsql.enabled
CREATE OR REPLACE VIEW tools AS SELECT	provsql.argtpl
CREATE OR REPLACE VIEW tools AS SELECT	provsql.argtpl_circuit
CREATE OR REPLACE VIEW tools AS SELECT	provsql.endpoint

Detailed Description

Functions for visualizing and exporting provenance circuits in various formats.

Function Documentation

_probability_benchmark_one()

TABLE provsql._probability_benchmark_one	(	UUID	in_token,
		TEXT	in_method,
		TEXT	in_args = NULL )

Time a single probability_evaluate call and return one row.

Helper for probability_benchmark. Returns the wall-clock duration of one probability_evaluate invocation along with its result; on error, fills probability with NULL and error with SQLERRM.

Source code

provsql.sql line 4222

compile_to_ddnnf()

TEXT provsql.compile_to_ddnnf	(	UUID	token,
		TEXT	compiler = '' )

Return the compiled d-DNNF of a provenance circuit in the c2d / d4 ".nnf" TEXT interchange format.

Companion to compile_to_ddnnf_dot (DOT, for viewing): this is the machine-readable form, suitable for feeding to an external d-DNNF reasoner / verifier or saving next to tseytin_cnf (same variable numbering). Accepts the same compiler / meta-route names.

Parameters

token	root provenance token
compiler	compiler or in-process meta-route to use; empty (the default) picks the highest-preference available compiler

Source code

provsql.sql line 3964

compile_to_ddnnf_dot()

TEXT provsql.compile_to_ddnnf_dot	(	UUID	token,
		TEXT	compiler = '' )

Return a DOT visualisation of the d-DNNF compiled from the provenance circuit.

Runs the requested external knowledge compiler and renders the resulting d-DNNF as a GraphViz digraph.

Parameters

token	root provenance token
compiler	external compiler or in-process meta-route to invoke; empty (the default) picks the highest-preference available compiler

Source code

provsql.sql line 3945

ddnnf_stats()

jsonb provsql.ddnnf_stats	(	UUID	token,
		TEXT	compiler = '' )

Structural statistics of the d-DNNF a compiler produces for a provenance circuit.

Compiles the circuit with the given compiler / meta-route (same names as compile_to_ddnnf_dot: d4, d4v2, c2d, minic2d, dsharp, panini-*, tree-decomposition, interpret-as-dd, default) and returns a jsonb object: nodes, edges, and / or / not / inputs counts, smooth, depth (longest path), treewidth (null when not computable), and compile_ms. Lets clients compare what each compiler produces on the same circuit.

Parameters

token	root provenance token
compiler	compiler or in-process meta-route to use; empty (the default) picks the highest-preference available compiler

Source code

provsql.sql line 3985

probability_benchmark()

TABLE provsql.probability_benchmark	(	UUID	token,
		INT	monte_carlo_samples = 10000,
		TEXT	weightmc_args = '0.8;0.2' )

Time every probability-evaluation method on a single circuit token.

Runs probability_evaluate against every method ProvSQL exposes: independent, possible-worlds, tree-decomposition, monte-carlo (with monte_carlo_samples samples), each of the four external compilers (d4 / c2d / minic2d / dsharp) via the compilation method, and weightmc with weightmc_args. Errors (uninstalled compiler, non-independent circuit, treewidth blowup, ...) are captured per row through the _probability_benchmark_one helper so the comparison table is always complete and the caller never has to surround the call with BEGIN / EXCEPTION.

Parameters

token	root provenance token
monte_carlo_samples	Monte-Carlo sample count
weightmc_args	epsilon;delta forwarded to weightmc

Source code

provsql.sql line 4270

provenance()

UUID provsql.provenance

(

)

Return the provenance token of the current query result tuple.

Source code

provsql.sql line 4321

register_tool()

REVOKE ALL ON FUNCTION provsql.register_tool	(	TEXT	name,
		TEXT	executable = NULL,
		TEXT	kind = 'cli',
		TEXT[]	operations = NULL,
		TEXT[]	input_formats = NULL,
		TEXT	output_format = NULL,
		TEXT	parser = NULL,
		TEXT	argtpl = NULL,
		TEXT	argtpl_circuit = NULL,
		INT	preference = 0,
		BOOLEAN	enabled = true,
		TEXT	endpoint = NULL )

Register a tool, or replace the RECORD with the same logical name.

The mutators guard at the C level too, but revoke from PUBLIC so the superuser requirement is visible in the catalog.

Parameters

name	logical id (e.g. 'd4-jm62300'); also the value provsql.fallback_compiler / the wmc tool selector use
executable	executable to resolve on PATH (defaults to name)
kind	'cli' (spawn executable) or 'kcmcp' (talk to the KCMCP server at endpoint)
operations	capabilities (KCMCP names): 'compile' / 'wmc' (and ProvSQL-local 'render')
input_formats	accepted inputs (KCMCP names): 'dimacs-cnf', 'circuit-bcs12' (listing 'circuit-bcs12' enables the native-circuit fast path)
output_format	result encoding (KCMCP names): 'ddnnf-nnf', 'decimal', 'rational', ... (local 'panini-dd' / 'ascii' where KCMCP has no code)
parser	CLI-only decode tag: 'nnf' (the tolerant d4 / c2d NNF reader), 'panini-dd', 'wmc-line', 'weightmc', 'ascii'
argtpl	command template; placeholders {in} / {out} (and {binary} / {tmpdir} / {pivotAC}). When it omits {binary}, the executable is prepended.
argtpl_circuit	command used when the 'circuit-bcs12' input is selected (a BC-S1.2 circuit rather than a CNF); only a tool accepting that input needs it
preference	ordering within an operation (higher first)
enabled	whether the dispatchers may select it
endpoint	for a 'kcmcp' RECORD, the server address: 'unix:/path' or 'host:port'

Superuser-only: a CLI RECORD runs an arbitrary command as the PostgreSQL OS user, and a kcmcp RECORD names a socket the server connects to.

Source code

provsql.sql line 4176

set_tool_enabled()

REVOKE ALL ON FUNCTION provsql.set_tool_enabled	(	TEXT	name,
		BOOLEAN	enabled )

Enable/disable a tool; errors on an unknown tool name.

Superuser-only.

Source code

provsql.sql line 4198

set_tool_preference()

REVOKE ALL ON FUNCTION provsql.set_tool_preference	(	TEXT	name,
		INT	preference )

Set a tool's preference; errors on an unknown tool name.

Superuser-only.

Source code

provsql.sql line 4203

to_provxml()

TEXT provsql.to_provxml	(	UUID	token,
		REGCLASS	token2desc = NULL )

Return an XML representation of the provenance circuit.

Parameters

token	root provenance token
token2desc	optional mapping table for gate descriptions

Source code

provsql.sql line 4314

tool_available()

BOOLEAN provsql.tool_available

(

TEXT

name

)

Report whether an external tool is on the backend's resolved PATH.

Uses the same find_external_tool() helper that the compilers (d4 / c2d / minic2d / dsharp / panini), model counters (ganak / sharpsat-td / dpmc via htb+dmc / weightmc), and visualisation wrappers (graph-easy, dot) themselves consult, so the result reflects exactly what a subsequent probability_evaluate or view_circuit call would see, including the provsql.tool_search_path GUC prepended to $PATH.

Names with a slash are treated as paths and tested directly via access(X_OK); bare names are resolved through /bin/sh's command -v under the backend's PATH.

Parameters

name	bare executable (e.g. 'd4') or an absolute path

Returns

true iff the tool resolves to an executable file

Source code

provsql.sql line 4067

tool_overrides()

CREATE TABLE IF NOT EXISTS provsql.tool_overrides	(	name TEXT PRIMARY	KEY,
		removed BOOLEAN NOT NULL DEFAULT	false,
		kind	TEXT,
		executable	TEXT,
		operations	TEXT[],
		input_formats	TEXT[],
		output_format	TEXT,
		parser	TEXT,
		preference	INT,
		enabled	BOOLEAN,
		dependencies	TEXT[],
		argtpl	TEXT,
		argtpl_circuit	TEXT,
		endpoint	TEXT )

Persistent overrides overlaid on the compiled-in tool seed.

Each row is the complete desired RECORD for a tool (added or modified) keyed by logical name, or a tombstone (removed = true) hiding a seeded default. The effective registry is the compiled seed with tombstoned names removed and the remaining rows upserted over it. Written only by the superuser-only register_tool / unregister_tool / set_tool_* functions; read back into each backend's in-memory registry on demand. Marked as a configuration table so pg_dump carries an operator's registrations.

tool_registry_list()

CREATE OR REPLACE VIEW tools AS SELECT available FROM provsql.tool_registry_list

(

)

Set-returning listing backing the provsql.tools view.

operations / input_formats / output_format use the KCMCP shared-registry names (see the KCMCP server protocol), so a CLI RECORD and a future kcmcp-server RECORD are comparable; parser is the CLI-only tag for how to decode the tool's raw output. argtpl is the command template ({in}/{out}/... placeholders). available is true iff executable (when set) and every dependency currently resolve on the backend's PATH.

Source code

provsql.sql line 4127

tree_decomposition_dot()

TEXT provsql.tree_decomposition_dot

(

UUID

token

)

Return a DOT visualisation of the tree decomposition of the provenance circuit.

Computes the min-fill decomposition used by the in-process knowledge compiler. The first line of the output is a comment of the form "// treewidth=<n>".

Parameters

token

root provenance token

Source code

provsql.sql line 4044

tseytin_cnf()

TEXT provsql.tseytin_cnf	(	UUID	token,
		BOOLEAN	weighted = TRUE,
		BOOLEAN	mapping = TRUE )

Return the DIMACS CNF (Tseytin transformation) of the provenance circuit.

Returns the same encoding the extension writes to a temp file before invoking d4 / c2d / minic2d / dsharp. With weighted true (the default), per-input probability weights are appended as w lines.

Parameters

token	root provenance token
weighted	include probability weights when true
mapping	prepend "c input <var> <UUID> <prob>" comment lines documenting which provenance input each variable stands for

Source code

provsql.sql line 4003

tseytin_cnf_mapping()

TABLE provsql.tseytin_cnf_mapping

(

UUID

token

)

tseytin_cnf_mapping_json()

jsonb provsql.tseytin_cnf_mapping_json

(

UUID

token

)

Map each DIMACS variable of tseytin_cnf back to its provenance input.

Returns one row per input gate: the variable index (matching tseytin_cnf and compile_to_ddnnf's NNF), the original-circuit UUID of that input, and its probability. Lets a satisfying assignment or weighted model count obtained from an external tool be read against the provenance circuit.

Parameters

token

root provenance token

Source code

provsql.sql line 4022

unregister_tool()

REVOKE ALL ON FUNCTION provsql.unregister_tool

(

TEXT

name

)

Unregister a tool; errors on an unknown tool name.

Superuser-only.

Source code

provsql.sql line 4193

view_circuit()

TEXT provsql.view_circuit	(	UUID	token,
		REGCLASS	token2desc,
		INT	dbg = 0 )

Return a DOT or TEXT visualization of the provenance circuit.

Parameters

token	root provenance token
token2desc	mapping table for gate descriptions
dbg	debug level (0 = normal)

Source code

provsql.sql line 3927

where_provenance()

TEXT provsql.where_provenance

(

UUID

token

)

Compute where-provenance for a result tuple.

Returns a TEXT representation showing which input columns contributed to each output column.

Source code

provsql.sql line 4330

Variable Documentation

argtpl

CREATE OR REPLACE VIEW tools AS SELECT provsql.argtpl

argtpl_circuit

CREATE OR REPLACE VIEW tools AS SELECT provsql.argtpl_circuit

enabled

CREATE OR REPLACE VIEW tools AS SELECT provsql.enabled

endpoint

CREATE OR REPLACE VIEW tools AS SELECT provsql.endpoint

executable

CREATE OR REPLACE VIEW tools AS SELECT provsql.executable

input_formats

CREATE OR REPLACE VIEW tools AS SELECT provsql.input_formats

kind

CREATE OR REPLACE VIEW tools AS SELECT provsql.kind

name

CREATE OR REPLACE VIEW tools AS SELECT provsql.name

Read-only view of the registered tools.

operations

CREATE OR REPLACE VIEW tools AS SELECT provsql.operations

output_format

CREATE OR REPLACE VIEW tools AS SELECT provsql.output_format

parser

CREATE OR REPLACE VIEW tools AS SELECT provsql.parser

preference

CREATE OR REPLACE VIEW tools AS SELECT provsql.preference