> 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.opendatadiscovery.org/features/data-discovery/directory.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.