> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/features/data-discovery/directory.md).

# Directory

The **Directory** is the catalog's **browse-oriented** entry point. Where [Search](/features/data-discovery/search.md) 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](/features/data-discovery/search.md) 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.](/files/quOH5Wp8Vc3ueZ9LuGzJ)

## 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](/introduction/main-concepts.md) 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.

{% hint style="warning" %}
**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](/configuration-and-deployment/enable-security.md) for the deployment-side stance.
{% endhint %}

### 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](/developer-guides/api-reference/directory.md) — 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](/features/data-discovery/search.md) — the query-oriented counterpart, with seven facets.
* [Data entity detail page](/features/data-discovery/entity-detail-page.md) — what you land on when you click an entity in the level-4 list.
* [ODDRN](/introduction/main-concepts.md#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](/configuration-and-deployment/enable-security.md) — the deployment-side surface for restricting catalog read access in multi-team environments.
* [Main Concepts → Data Discovery](/introduction/main-concepts.md) — where Search and the Directory sit in the broader governance map.