 |
ProvSQL SQL API
Adding support for provenance and uncertainty management to PostgreSQL databases
|
|
ProvSQL SQL API
Adding support for provenance and uncertainty management to PostgreSQL databases
|
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. | |
| 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 |
Functions for visualizing and exporting provenance circuits in various formats.
| 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.
| token | root provenance token |
| compiler | compiler or in-process meta-route to use; empty (the default) picks the highest-preference available compiler |
| 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.
| token | root provenance token |
| compiler | external compiler or in-process meta-route to invoke; empty (the default) picks the highest-preference available compiler |
| 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.
| token | root provenance token |
| compiler | compiler or in-process meta-route to use; empty (the default) picks the highest-preference available compiler |
| UUID provsql.provenance | ( | ) |
Return the provenance token of the current query result tuple.
| 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.
| 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.
| REVOKE ALL ON FUNCTION provsql.set_tool_enabled | ( | TEXT | name, |
| BOOLEAN | enabled ) |
Enable/disable a tool; errors on an unknown tool name.
Superuser-only.
| 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.
| TEXT provsql.to_provxml | ( | UUID | token, |
| REGCLASS | token2desc = NULL ) |
Return an XML representation of the provenance circuit.
| token | root provenance token |
| token2desc | optional mapping table for gate descriptions |
| 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.
| name | bare executable (e.g. 'd4') or an absolute 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.
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.
| 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.
| 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>".
| token | root provenance token |
| 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.
| 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 |
| TABLE provsql.tseytin_cnf_mapping | ( | UUID | token | ) |
| 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.
| token | root provenance token |
| REVOKE ALL ON FUNCTION provsql.unregister_tool | ( | TEXT | name | ) |
| TEXT provsql.view_circuit | ( | UUID | token, |
| REGCLASS | token2desc, | ||
| INT | dbg = 0 ) |
Return a DOT or TEXT visualization of the provenance circuit.
| token | root provenance token |
| token2desc | mapping table for gate descriptions |
| dbg | debug level (0 = normal) |
| 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.
| 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.enabled |
| CREATE OR REPLACE VIEW tools AS SELECT provsql.endpoint |
| CREATE OR REPLACE VIEW tools AS SELECT provsql.executable |
| CREATE OR REPLACE VIEW tools AS SELECT provsql.input_formats |
| CREATE OR REPLACE VIEW tools AS SELECT provsql.kind |
| CREATE OR REPLACE VIEW tools AS SELECT provsql.name |
Read-only view of the registered tools.
| CREATE OR REPLACE VIEW tools AS SELECT provsql.operations |
| 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 |