Coverage & troubleshooting

What Unity Catalog grants and system.* schemas gate which queries — so you can tell in advance what will run — and what to do when a query returns nothing, a band reads NOT ASSESSED, or the dollars look off.

Prerequisites & enablement

Three reasons a table is empty

1. Unity Catalog isn’t enabled. System tables live in the UC system catalog — no UC-enabled workspace means no system.* at all.
2. The system schema isn’t enabled, or you can’t read it. Most schemas are opt-in (enabled per-schema by an account/metastore admin), and reads are privilege-scoped — a principal without USE CATALOG on system + USE SCHEMA + SELECT sees zero rows, not an error.
3. The feature was never used, or not in your window. A table only has rows once the underlying feature actually runs (a job executed, an endpoint got traffic, Predictive Optimization did work) — and only within its retention window.

Which system schemas are on by default

Only billing and compute are on without a deliberate enable step. The rest are opt-in — the single most common reason a query here returns nothing.

Preview status is per-table, not per-schema: even inside an enabled schema, tables such as query.history, serving.*, storage.*, parts of access, and ai_gateway.usage are still Public Preview / Beta, so they can be empty until Databricks rolls them out to your account and region.

If a query is empty — enable it

1. Find the schema. Read the query’s Requires line (or the Reads column in the matrix below) — it names the exact system.* schema the query needs.
2. Have an admin enable it (account/metastore admin) via the system-schemas API ↗:

   databricks system-schemas list   <metastore_id>
   databricks system-schemas enable <metastore_id> serving
   # ...or access / query / storage / lakeflow / ai_gateway

3. Grant read to non-admins — no grant means zero rows, not an error:

   GRANT USE CATALOG ON CATALOG system        TO `data-team`;
   GRANT USE SCHEMA  ON SCHEMA  system.serving TO `data-team`;
   GRANT SELECT      ON SCHEMA  system.serving TO `data-team`;

4. Expect no backfill. Collection starts only after enablement — historical rows are not filled in retroactively.
5. Still empty? The feature likely hasn’t run in your window (a Preview table, an endpoint with no traffic, a genuinely quiet account). That is a real answer, not a failure — the runner records it as NOT_ASSESSED, never a fake 0.

Common trap: serving / gateway tables look empty even though endpoints exist. system.serving.endpoint_usage only covers Model Serving endpoints with AI Gateway usage tracking on — not Vector Search, feature serving, or agent endpoints. Vector Search spend lands in system.billing.usage under billing_origin_product = ‘VECTOR_SEARCH’, which the cost_vector_search_spend query reads directly.

What one grant unlocks

Each query reads one or more system.* schemas. Granting SELECT on a schema (and enabling it for the metastore where it’s in preview) unlocks every query that reads it.

Sums exceed 100 because many queries read more than one system.* schema, so they are counted under each schema they touch. And a schema grant unlocks its queries but not always a whole domain: Cost, for example, includes one query (the workspace-name lookup, cost_workspace_names) that reads system.access, so a system.billing grant alone unlocks 22 of the 23 Cost queries — not the whole domain.

Why a query returns empty — gap reasons

Every query is tagged with the empty_if reasons it could legitimately return zero rows — a controlled vocabulary drawn from the library’s COVERAGE.md ↗. Read them fixable-first: the top rows are enablement and privilege gaps you can act on; the lower rows mean the feature simply hasn’t run yet. Each query’s own reasons appear in the Empty if column of the matrix below (and on the query itself). 18 always-on billing / reference queries carry no gap reason — they are effectively never empty.

Coverage matrix

Per query: its tier (how heavy), the exact grant it requires, the system.* tables it reads, and the empty-if reasons it could return nothing (hover a chip for the full reason). Tier is a labelled field heuristic for run order, not a Databricks classification: lite = GA schemas plus a single grant; standard = a commonly-enabled schema, usually a join or window; deep = a heavier scan or a preview / feature-gated table.

Troubleshooting