Reporting

pghf.get_raw_result(p_run_id uuid, p_check_id text)

Returns one check's raw-result record for one run — the full collection detail (status, what was observed, any explanatory note, and a documentation link), not just the evaluated "value" a summary function reports.

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Must reference an existing run.
p_check_id	text	Yes	—	Check to look up within that run.

Returns: the raw-result record. Raises an error if the run doesn't exist, or if it exists but has no raw result for that check (it may not have been a member of that run's suite).

pghf.get_results_json(p_run_id uuid)

A read-only summary of one run's evaluations, for machine consumers — a notification pipeline, a webhook, a dashboard backend. Runs with elevated privileges so it works without a direct read grant on the (not openly readable) underlying tables — see The Access Model.

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Must reference an existing run (any run, not only one from the current session).

Returns: jsonb — a flat list of objects, one per evaluated check (check ID, raw severity, confirmed severity, message, detail), ordered by check ID. Raises an error for a nonexistent run; returns an empty list (not a null value) if the run exists but has no evaluations yet.

pghf.get_results_sql(p_run_id uuid, p_min_severity text DEFAULT 'ok')

A read-only relational result set for one run, for humans — run this in psql and read it directly, worst severity first. Same elevated-privilege reasoning as pghf.get_results_json().

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Must reference an existing run.
p_min_severity	text	No	'ok'	Filters to this tier and everything more severe. 'ok' (the default) shows everything. Must be one of ok/info/warning/critical.

Returns: a result set (severity, category, check ID, check name, value, message), ordered worst-severity-first, then by category and check ID. Raises an error for a nonexistent run, or an invalid p_min_severity.

pghf.get_run(p_run_id uuid)

Returns one plain run record — metadata not already surfaced by pghf.list_runs()/pghf.get_run_status() (who or what triggered it, the server's PostgreSQL version, whether it's a Spock cluster, the target PostgreSQL version if any, and free-text notes).

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Run to look up.

Returns: the run record. Raises an error if not found.

pghf.get_run_status(p_run_id uuid)

Reports whether a run actually finished — neither reporting function above tells you this, so a consumer polling for "anything critical?" can't otherwise distinguish a genuinely clean run from one that crashed partway through (an interrupted collection run still leaves every check collected up to that point fully committed, so its partial results look entirely plausible on their own).

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Must reference an existing run.

Returns: a result set including whether collection is complete, whether evaluation is complete, and how many checks were expected versus actually observed and evaluated. Collection is considered complete once the run has a finish time recorded; evaluation is considered complete once every observed check has also been evaluated. The "expected" count reflects the suite's current membership, not a point-in-time snapshot — suite membership isn't tracked historically — so treat it as a sanity check rather than an exact match for an older run. Raises an error for a nonexistent run.

pghf.list_raw_results(p_run_id uuid, p_status text DEFAULT NULL)

Lists raw-result records for one run — full per-check collection detail, the same rationale as pghf.get_raw_result() above.

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Must reference an existing run.
p_status	text	No	empty = all	Filters to COLLECTED, SKIPPED, or ERROR.

Returns: zero or more raw-result records, ordered by category and check ID. Raises an error if the run doesn't exist or the status filter is invalid.

pghf.list_run_config(p_run_id uuid)

Lists the extra configuration a run was given at collection time (target version, tables checked with amcheck, tables checked with pg_visibility) — useful for working out why a check depending on one of these reported itself as skipped.

Parameter	Type	Mandatory	Default	Description
p_run_id	uuid	Yes	—	Must reference an existing run.

Returns: zero or more configuration key/value records, ordered by key. Raises an error if the run doesn't exist.

pghf.list_runs(p_run_key text DEFAULT NULL, p_since timestamptz DEFAULT NULL, p_until timestamptz DEFAULT NULL, p_limit int DEFAULT 50)

The entry point for discovering a run at all when you don't have direct table access — lists available runs, most recent first, together with a count of each result type from both the collection side and the evaluation side (all zero for a run that hasn't been evaluated yet, which isn't an error).

Parameter	Type	Mandatory	Default	Description
p_run_key	text	No	empty = every suite	Scope to one suite's runs.
p_since	timestamptz	No	empty	Only runs starting at or after this time.
p_until	timestamptz	No	empty	Only runs starting at or before this time.
p_limit	int	No	50	Caps how many recent runs are returned. Empty = unbounded.

Returns: a result set ordered by start time, most recent first.

Continue to Retention.