Reading the Catalog Without Table Access¶

Every catalog table already has open read access for everyone — that never changes (see The Access Model). But writing a query against them by hand means re-deriving the same joins every time — turning a check ID into its category's name, or a suite's membership into an ordered, human-readable list — and some deployments tighten catalog read access further than this framework's own default.

A matching pair of read-only functions exists for both reasons — one "get one, and raise if it's missing" function and one "list many, empty result is fine" function, per catalog entity:

SELECT * FROM pghf.get_check('PGHF01-003');                       -- one check, raises if it doesn't exist
SELECT * FROM pghf.list_checks(p_namespace_code => 'PGHF');        -- browse a namespace's checks
SELECT * FROM pghf.list_check_run_members('default');              -- a suite's contents, in order, by check ID
SELECT * FROM pghf.get_threshold('PGHF01-003');                    -- a check's default threshold
SELECT * FROM pghf.list_events(p_check_id => 'PGHF11-009');        -- a check's registered events

The "get" function always returns exactly one result and raises a clear error if the thing you asked for doesn't exist — the same "raise on not-found, never silently return nothing" rule the reporting functions in How Threshold Evaluation Works use for a nonexistent run. The "list" function returns zero or more rows and never errors on an empty result; its filter parameters default to "no filter, show everything."

The full set:

Entity	Get one	List several
Namespace	`get_namespace(namespace_code)`	`list_namespaces(p_only_active)`
Category	`get_category(namespace_code, category_code)`	`list_categories(p_namespace_code, p_only_active)`
Check	`get_check(check_id)`	`list_checks(p_namespace_code, p_category_code, p_include_retired)`
Suite	`get_check_run(run_key)`	`list_check_runs(p_only_active)`
Suite membership	—	`list_check_run_members(run_key)`
Threshold	`get_threshold(check_id, p_check_run_id)`	`list_thresholds(p_check_id)`
Event	`get_event(event_id)`	`list_events(p_check_id, p_only_active)`

There is no pattern-matching "list" function for checks — if you want to preview which checks a wildcard pattern like 'PGHF01-*' would match, without needing to add them to any suite, pghf.add_checks_matching() (covered in the Adding Your Own Checks book) already does exactly that in preview mode.

Full parameter and return details for every function above are in the Reference Guide.

Continue to Inactivating a Namespace or Category.