Directory

Directory — the browsable catalog. Walk down data source types → data sources → entity types → entities without typing a query.

The Directory is the catalog's browse-oriented entry point. Where Search is query-driven (you know what you're looking for and type a term), the Directory is hierarchy-driven (you don't yet know the exact entity name and want to drill down through known structure). It's the second of the two top-level navigation paths into the catalog.

When to use the Directory

Reach for the Directory when:

• You want to see what data sources are registered in the platform without scrolling through search facets.

• You know the kind of source (PostgreSQL, Snowflake, Kafka, Airflow, ...) but not the specific instance or entity.

• You're auditing per-source coverage — how many entities did the collector pull from each source, and which entity types are present.

• You're onboarding a teammate and want to walk them through the catalog visually before showing them search.

For everything else — full-text lookup, faceted filtering by tags / domains / owners — use the Search tab.

Directory level 1 — one card per ODDRN-prefix data source type registered in the platform; each card carries the type's display name and the total entity count across every data source of that type. Clicking a card drills down to level 2.

Navigation hierarchy

The Directory is a four-level drill-down. Each level is its own UI page (and its own API endpoint — see below).

Level	What you see	URL
1. Data source types	One card per ODDRN prefix that the platform's registered data sources resolve to (postgresql, snowflake, kafka, airflow, mysql, ...). Each card shows the type's display name and a total entity count across every registered source of that type.	/directory
2. Data sources of the selected type	The list of registered data source instances for the chosen type — name, ODDRN-derived properties (host, port, database, ...), and per-source entity count.	/directory/{type-prefix}
3. Entity types within the selected data source	The distinct Data Entity types present in the chosen data source (TABLE, FILE, KAFKA_TOPIC, JOB, JOB_RUN, DASHBOARD, VIEW, ML_MODEL_INSTANCE, ...) — the type dimension, not the broader entity class.	/directory/{type-prefix}/{data-source-id}/all (UI surfaces this on the data-source detail page)
4. Entities of the selected (data source, entity type) pair	The paged list of data entities matching both filters; click an entity to land on its detail page (Overview tab).	/directory/{type-prefix}/{data-source-id}/{type-id}

The Directory's first level also surfaces in a condensed form on the Catalog Overview home page under the "Directory" section — a quick-jump card grid that links directly into level 2.

Known limitations and operator caveats

The Directory's read posture and URL conventions carry several behaviours operators need to know before relying on them in a multi-team deployment.

Level 2 reflects every ODDRN path property to every authenticated caller

The level-2 response is built by walking each registered data source's ODDRN and emitting every property that contributes to the address as a column in the response. For PostgreSQL that means host and database; for Snowflake account and warehouse; for Kafka cluster and topic; for MySQL host and database; for BigQuery project. The level-2 table on /directory/{type-prefix} is the operator-visible projection of this reflection — the table's columns are derived from the first row's properties at render time, so the column set changes per data-source type but always reflects everything the collector chose to encode in the ODDRN.

Anyone with read access to the catalog can enumerate this inventory. The Directory endpoints carry no owner-scoping; any authenticated user can drill /api/directory/{type-prefix} and reach the full list of registered data sources of that type together with their reflected host / database / port / account / warehouse / cluster / topic / project strings. Under auth.type=DISABLED the same endpoint is anonymously reachable. The strings frequently double as DNS targets, firewall-rule names, cloud-account identifiers, or VPC names — treat catalog read access as you would access to that inventory. See Enable security for the deployment-side stance.

The level-4 count badge can disagree with the level-4 result list

The level-4 list endpoint (the paged result) and the level-4 count endpoint (the badge showing total entities) apply different filter predicates. In deployments that use the EXCLUDE_FROM_SEARCH flag to hide intermediate or transient entities from search but keep them browsable in the Directory, the count drops those entities while the list still shows them — so the page renders, for example, 30 rows under a "25 entities" header (or the reverse, depending on which page you land on). The mismatch is silent; there is no warning that the X-of-Y display has diverged from the row count you can scroll through.

If your collector layer uses EXCLUDE_FROM_SEARCH for entity hygiene, treat the level-4 count badge as advisory rather than authoritative when auditing per-source completeness.

The level-3 URL's third segment is the literal string all — not a numeric placeholder

Level-3 and level-4 URLs differ in shape:

• /directory/{type-prefix}/{data-source-id}/all — level 3 (every entity type of this source).

• /directory/{type-prefix}/{data-source-id}/{numeric-type-id} — level 4 (entities of one specific type).

The all segment is a load-bearing literal — the routing hook coerces the third segment to "no type filter" only when it matches all exactly, otherwise it runs it through a numeric parse. A typo (postgresql/123/dataset instead of postgresql/123/all) parses to NaN, which propagates as the type filter through the level-4 query — silently rendering a broken or empty view rather than a 404. Hand-constructing level-3 URLs is therefore brittle; the recommended path is to navigate via the UI's All tab (which always builds the URL correctly) and to bookmark the result.

If the level-3 URL is missing the third segment entirely (/directory/{type-prefix}/{data-source-id}), the platform redirects to /all automatically — that fallback is the safest hand-construction shape if you must type the URL.

API surface

The Directory's four backing endpoints are documented at API Reference → Directory — one GET endpoint per drill-down level under /api/directory, with the level-1 ODDRN-parsing implementation detail included alongside.

Where it sits in the UI

• Top-navigation Catalog drops the user on the Search-first landing.

• Top-navigation Directory opens the standalone level-1 view (/directory).

• Catalog Overview page → Directory section renders the same level-1 cards inline (so the home page surfaces both Search and Directory entry points side by side).

Where to next

• Search and Filtering — the query-oriented counterpart, with seven facets.

• Data entity detail page — what you land on when you click an entity in the level-4 list.

• ODDRN — the addressing scheme whose prefix is what the level-1 cards group by, and whose properties are what the level-2 columns reflect.

• Enable security — the deployment-side surface for restricting catalog read access in multi-team environments.

• Main Concepts → Data Discovery — where Search and the Directory sit in the broader governance map.