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, p_reportable_only boolean DEFAULT false)

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).
p_reportable_only	boolean	No	false = everything	true = only rows the minimum-report-interval rule stamped reportable.

Returns: jsonb — a flat list of objects, one per evaluated check (check ID, raw severity, confirmed severity, message, detail, reportable), 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 NULL, p_reportable_only boolean DEFAULT false)

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	empty = everything	Filters to this tier and everything at or above its rank. Must be one of the 8 ladder values (skipped/not_evaluable/ok/info/warning/invalid/critical/error_in_performing_check). Note 'warning'/'critical' also surface 'invalid'/'error_in_performing_check' rows, which outrank them — see How Threshold Evaluation Works.
p_reportable_only	boolean	No	false = everything	true = only rows the minimum-report-interval rule stamped reportable.

Returns: a result set (severity, category, check ID, check name, value, message, reportable), 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, whether it was dispatched via pg_relay, 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 — for a pg_relay-dispatched run that time is stamped by whichever relay worker lands the final result, so this is also the flag to poll before evaluating such a run; 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.

pghf.friendly_time(p_duration interval)

A pure formatting convenience — no built-in reporting function calls this itself, it's handed to DBAs for their own reporting queries. Turns an interval into a compact string ('3d 4h 5m 26s') instead of PostgreSQL's default interval text ('3 days 04:05:26').

Parameter	Type	Mandatory	Default	Description
p_duration	interval	Yes	—	Typically the result of subtracting two timestamptz values, e.g. now() - some_check.current_status_first_at.

Returns: text, or NULL if p_duration is NULL. Zero-valued units are dropped entirely, wherever they fall — interval '1 day 26 seconds' prints '1d 26s', not '1d 0h 0m 26s'; interval '75 minutes' prints '1h 15m', not '0d 1h 15m' or '1h 15m 0s'. The one exception: a zero (or sub-second) duration prints '0s' rather than an empty string. A negative interval prints with a leading - and otherwise-unsigned components, e.g. '-3d 4h'.

Assumes a day-time interval — the kind timestamptz subtraction always produces (days plus a sub-day remainder, no months). An interval carrying a month/year component (built by hand rather than from a timestamp difference, e.g. interval '1 month') has that part silently ignored; call justify_interval() first, or derive the interval from a timestamptz difference, if you need month-aware formatting. See Alert Status in the User Guide for a worked recipe, and psql Shortcuts for 56 ready-made psql variables built on it.

Continue to Retention.