# Overview ODD is an open-source, community-driven data discovery platform — ML-first, end-to-end microservices lineage, flexible data quality integration, and catalogs ML experiment metadata and lineage. ## About ODD The open-source Data Discovery Platform improves productivity, collaboration, and governance of modern data products and teams: * Free open-source and community-driven * ML first citizen * End-to-end microservices lineage support * Flexible data quality integration options * ML experiment metadata and lineage cataloged end-to-end (generated by the collectors, rendered in the catalog) To use Platform solutions more effectively apply [**ODD Specification**](https://github.com/opendatadiscovery/opendatadiscovery-specification/blob/main/specification/specification.md). It contains best practices for managing your metadata. Its theoretical topics and examples help to build an effective data discovery process. Also the Spec covers data engagement and data federation problems. ### The platform for your business ![](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-3d23aeec284e2b3ff1d91b3dbfd7adde88baf59a%2Faudience.png?alt=media) ODD's **target audience** is any data team regardless of its' size. It can be enterprises or large-scale companies challenging data mesh concept, small and mid-scale companies seeking OSS data catalogue solution and also DS teams aiming at better data governance.\ \ ![](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-e2996884869ca3c2313143d1d898221a571484c4%2Falltogether.png?alt=media) **An ecosystem for all data team members**. Platform functionality covers requirements of Data Scientists and Engineers, Product and Project Managers as well as Data Analysts, Architects, QA and BI Engineers. ### Solution matrix ODD can benefit a team at the following SDLC stages and team functions: ![](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-90a3947df89294293ba31d651edb0e5e5c3d6176%2Fsdlc.png?alt=media) ## Pain points ### Onboarding to data Every time a newcomer joins a data team, one faces a challenge of data management processes learning. Unfortunately, it may provoke overcommunication, reading irrelevant documentation and spending much time to pick out meaningful information.\ ODD solutions help figure out data sources, find owners of this data, check DBs structures and get many other attributes that are necessary for working activities. ### Data discovery The more data a team has the more complicated connections occur between assets and components. ODD provides a search tool with AI-powered suggestion and flexible filters. Also the Platform supports a description option, so you can get detailed info about data entities. ### Data observability A problem of observability lack starts when irrelevant data appears in one's production cycle. To clarify when and where this data is and avoid delay use ODD's lineage diagram and flexible alert system. ## Features Dive into ODD opportunities with a [list of ODD features](/features/features). ## Use cases See the [most popular use cases](/use-cases/use-cases) for different titles of your data team. # Main Concepts Core vocabulary and mental model for the Open Data Discovery project — what the pieces are, how they fit together, and where to dive deeper. This page introduces the core vocabulary of the Open Data Discovery (ODD) project. It is a **map** — each concept gets a short definition and a link to its canonical deep-dive page. > **Not the Business Glossary.** ODD Platform ships an in-app **Business Glossary** feature (term entities you can link to datasets, term-to-term relationships, ownership). That is a different thing from this docs page. See the [Business Glossary](/features/data-glossary/business-glossary) feature page for the product feature. ## The architecture chain Metadata flows from data systems into the platform along two paths — **pull** (a collector polls the source) and **push** (an adapter embedded inside the source's runtime emits directly to the platform): * **Pull path:** Data source ← Pull adapter (wrapped as a **Plugin** inside a **Collector**) → ODD Platform * **Push path:** Data source's application runtime → **Push adapter** → ODD Platform The producer-side concepts: * **Data source** — a system holding data or data-adjacent metadata: a database, a warehouse, a BI tool, an ML training registry, an orchestrator. * **Adapter** — a set of scripts that map metadata from a source system (PostgreSQL, MySQL, Airflow, Kafka, …) to the ODD specification — Data Entities, data types, lineage edges, quality tests. An adapter's job is **extract-and-map**, nothing more. Adapters come in two flavours: **pull** (reads from the source on a schedule) and **push** (emits from inside the source's runtime). An adapter never runs alone; it is either hosted by a collector (pull) or packaged as a push adapter (push). * **Plugin** — a *configured* adapter instance inside a collector. One plugin carries one adapter's connection and schedule settings (source host, database, credentials, cadence). A single collector can host many plugins — multiple instances of the same adapter type (e.g., two PostgreSQL plugins pointing at different hosts or databases) or plugins for different adapter types. * **Collector** — a container of **pull** adapters plus the runtime around them: adapter launcher, logging system, Platform-API client, configuration reader, scheduling. A collector is what you deploy; the pull adapters inside it are the mappers, and each one is configured via a plugin. The canonical implementation is `odd-collector` with 40+ bundled pull adapters; specialist collectors exist for AWS, GCP, Azure, and data profiling. A collector is **not** a synonym for "pull adapter". The collector authenticates to the platform with a static, plaintext shared-secret token (no expiry, no overlap window — rotating it instantly breaks the running collector until it is reconfigured); see [Build and run collectors](/developer-guides/build-and-run/build-and-run-odd-collectors) for the token's full security contract. * **Push adapter** (also known as **push-client**) — a push-strategy adapter; the source initiates the data flow and the adapter knows the platform's endpoint. Push adapters ship in three deployment shapes: * **In-process plugin / extension** — embedded in the source system's own runtime: a dbt plugin, a Great Expectations checkpoint action, an Airflow plugin, a Spark listener. The most common shape today. * **Standalone gateway** — a separate service that source systems push to (today's only example: [`odd-tracing-gateway`](/integrations/integrations/odd-tracing-gateway), which receives OpenTelemetry traces). Operator-mental-model is "push"; the Platform-side leg is a pull hidden behind the gateway's standalone deployment. * **Direct SDK / CLI use** — push via a CLI or library call from custom code (`odd-cli` invocation, custom Python using `odd-models-package`). All three shapes are extract-and-map adapters; what differs from a pull adapter is deployment topology — the adapter does not live in a collector container. * **ODD Platform** — the central server: stores the metadata, provides search, lineage, ownership, alerts, DQ dashboards, and the UI. Pick **pull** when the source is a data store and you want point-in-time snapshots on a cadence — most data-source integrations work this way, since the source is passive and the collector drives. Pick **push** when the source is an application already running code we can instrument — Airflow DAGs, dbt runs, Spark jobs, Great Expectations validations — and you want each run's lineage and results reported as they happen. Some ecosystems combine both: a pull collector indexes the catalog while a push-client reports per-run lineage. See [Architecture.md](/introduction/architecture) for the diagram, [developer-guides/build-and-run/build-and-run-odd-collectors.md](/developer-guides/build-and-run/build-and-run-odd-collectors) for deployment detail, and the [specification's push-model note](https://github.com/opendatadiscovery/opendatadiscovery-specification/blob/main/specification/specification.md#push-model) for protocol-level detail. ## ODDRN **ODDRN** (**Open Data Discovery Resource Name**) is the unique, stable string that identifies every entity in the system — a dataset, a column, a data source, a pipeline run, a transformer. Producers (collectors, push adapters, custom agents) must generate an ODDRN for each entity they report so the platform can recognise the same entity across ingests, across producers, and over time. ODDRNs are what make cross-system lineage possible. **Format.** Every ODDRN starts with a double slash and the data-source family, followed by the connection coordinates that uniquely locate the entity in the world — host for self-hosted databases, AWS account ID + region for cloud services, etc. The format follows REST URL conventions: ``` //postgresql/host/1.2.3.4/databases/ex_database/schemas/public/table/ex_table ``` where: * `1.2.3.4` — the PostgreSQL instance host * `ex_database` — the target database * `public` — the target schema * `ex_table` — the target table **Usage.** ODDRNs power the [Ingestion API](#odd-specification) — the same string identifying the same entity across ingests is what lets the platform decide whether to create new entities, update existing ones, or delete obsolete ones on each payload. Operators rarely see ODDRNs directly; they become relevant when writing a custom agent. To assist, ODD ships open-source generator libraries for [Python](https://pypi.org/project/oddrn-generator/) and [Java](https://mvnrepository.com/artifact/org.opendatadiscovery/oddrn-generator-java); the [Build a custom collector](/developer-guides/build-and-run/custom-collectors) walkthrough covers the Python pattern end-to-end, including which `Generator` subclass to use per source family. **Known limitation.** All consumers of the Ingestion API must use the **same** ODDRN string for the **same** entity. Since ODDRNs encode connection coordinates, this means agents reporting on the same data infrastructure must agree on hostnames or static IPs — coordinate identifiers across your deployment if multiple agents touch the same source. A malformed ODDRN does not fail loudly on the consumer side: an entity whose ODDRN prefix the platform cannot recognise as a known data-source family is grouped under a catch-all **Other** bucket in the [Directory](/features/data-discovery/directory) browse view rather than under its real source type. Generate ODDRNs with the producer-side libraries above, which enforce the format; a typo in a hand-built ODDRN surfaces as a misfiled entity, not an error. ## ODD Specification The [**ODD Specification**](https://github.com/opendatadiscovery/opendatadiscovery-specification) is the wire contract between producers (collectors, push-clients) and the platform — the Ingestion API schema. It decouples the two sides: any producer that speaks the specification can feed any compliant platform. This is what makes custom agents and third-party collectors possible. ## Data Governance map A structured view of how ODD's functionality maps onto recognised data governance pillars. Use this to answer "does ODD do X?" for your governance framework. * **Data Discovery** — *available.* The core of the platform: catalog search with multiple facets, entity pages (datasets, transformers, consumers, quality tests, ML models), tags, ownership, and the Directory view. See the [Data Discovery](/features/data-discovery) pillar landing for the four entry paths (Search, Directory, Tagging, Data Entity Groups & Domains) and the Catalog Overview home page. * **Data Lineage** — *available.* Upstream and downstream lineage across the full entity model, not just datasets — pipelines, ML experiments, and quality tests all participate, plus microservices traced through OpenTelemetry. See the [Data Lineage](/features/data-lineage) pillar landing. * **Data Quality** — *available.* Per-entity test results surfaced on entity pages, the catalog-wide Data Quality dashboard, and operator-set Minor / Major / Critical SLA statuses. See the [Data Quality](/features/data-quality) pillar landing and [Visibility for Data Quality Engineer](/use-cases/use-cases/dq-visibility). * **Data Modeling** — *partially available.* [Data Entity Groups](/features/data-discovery/groups-domains) (DEGs) for logical grouping and entity relationship / ERD views today. Schema evolution signals (backwards-incompatible change triggers) are surfaced in alerts. See [Dataset schema diff](/features/data-discovery/schema-diff) and the [Data Modelling](/features/data-modelling) pillar. * **Data Glossary** — *available.* The in-app **Business Glossary** feature — term entities with term-to-term and term-to-data-entity linking, ownership, tags. Distinct from this Main Concepts page: Business Glossary is a product feature, Main Concepts is documentation. See the [Data Glossary](/features/data-glossary) pillar landing and the [Business Glossary](/features/data-glossary/business-glossary) reference. * **Master Data Management (incl. Reference Data Management)** — *partially available.* **Lookup Tables** provide operator-managed reference data as first-class entities in the catalog. Full MDM semantics (golden records, survivorship rules, stewardship workflows) are not part of ODD today — what ships is reference-data management. See the [Master Data Management](/features/master-data-management) pillar landing and the [Lookup Tables](/features/master-data-management/lookup-tables) feature page. * **Data Cost** — *roadmap.* Cost attribution to datasets, pipelines, and owners is not implemented today. * **Data Security (governance-level)** — *roadmap.* Data classification, sensitivity tagging, PII/PHI handling, and fine-grained data-access control sit on the roadmap. **This is different from platform-access security** (who can log in, what roles they have, what policies apply to the UI/API) — that is already shipped and documented under [configuration-and-deployment/enable-security/README.md](/configuration-and-deployment/enable-security). ### Pillar differentiation The six available / partially-available pillars are conceptually distinct because each captures a different *operator workflow*: * **Data Discovery** is **location-oriented** — finding existing entities by search, browse, or home-page surfacing. Entities come from collectors and push adapters; this pillar provides the navigation paths into the catalog. * **Data Modelling** is **contract-oriented** — describing how a dataset is queried ([Query Examples](/features/data-modelling/query-examples)) and connected ([Relationships / ERDs](/features/data-modelling/relationships)). The dataset itself comes from outside; the platform records intent and structure on top. * **Master Data Management** is **operator-curated reference data** — the canonical lookup tables managed inside the platform. There is no external source; the platform is the system of record. * **Data Lineage** is **connection-oriented** — describing how entities flow into and out of each other across pipelines and microservices. The lineage is the cross-pillar record because every entity has a structure, a meaning, a location, a quality signal, *and* a lineage. * **Data Glossary** is **meaning-oriented** — naming and describing the concepts the data represents. Terms are first-class catalog entities with their own lifecycle, ownership, RBAC, and search surface; not metadata attached to other entities. * **Data Quality** is **correctness-oriented** — test results, anomaly classes, dataset SLAs. Every catalogued dataset has a quality story, even if it is only "no checks defined". That difference shows up in where the data lives: Data Modelling artefacts attach to existing entities; Master Data artefacts *are* entities (Lookup Tables exist as Data Entities of type `LOOKUP_TABLE`); Data Quality results are pushed in by external frameworks; Lineage edges are computed from the connection graph. The six pillars sit alongside each other in the Data Governance map above, not nested. ## AI aspects ODD integrates AI/GenAI capabilities in a few places: * **GenAI assistant** — opt-in proxy from a single platform endpoint to an external AI service the operator runs (the platform does not embed an LLM). API-only today. One naming hazard worth flagging here: `genai.request_timeout` is the **wait-for-model-response** timeout (in minutes) — how long the platform waits for the external service's reply, not a send/request budget — and it is read once at startup, so a change requires a restart. See the [GenAI assistant](/features/active-platform-features/genai) page for configuration, the external service contract, and operator caveats. * **Data profiling** — automatic statistical profiles for datasets (null ratios, distributions, cardinality) via `odd-collector-profiler`. Surfaces on entity pages. * **ML experiment / model lineage** — experiments and trained models are first-class entities with their own lineage edges; useful for reproducibility and governance of ML pipelines. ## Terms & Aliases A living record of synonyms and aliases users may search for. If you know a feature by a different name, start here. | Canonical term | Also known as | What it is | Details | | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | Server-to-server (S2S) authentication | Machine-to-machine (M2M) tokens, M2M auth | Static API-key authentication for programmatic clients | [s2s.md](/configuration-and-deployment/enable-security/authentication/s2s) | | Ingestion authentication filter | Ingestion filter, ingestion API key | Token-based auth for `/ingestion/**` — independent of UI auth, off by default | Ingestion authentication in [Enable security](/configuration-and-deployment/enable-security) | | Collector secrets backend | Alternative secrets backend | Store collector credentials in an external secret store (AWS SSM) instead of YAML | [collectors-secrets-backend.md](/configuration-and-deployment/collectors-secrets-backend) | | Health endpoint | Health check, healthcheck, monitoring endpoints, liveness/readiness probe target, `/actuator/health` | Unauthenticated Spring Boot Actuator endpoint reporting platform health; the probe target for load balancers and Kubernetes. Sibling `/actuator/prometheus` serves runtime metrics. | [Health and monitoring](/configuration-and-deployment/health-and-monitoring) | | ODDRN | Open Data Discovery Resource Name | Stable string identifying every entity in the system | [ODDRN section above](#oddrn) | | Business Glossary (feature) | Glossary, Terms | In-app feature for managing term entities and linking them to datasets — not this Main Concepts page | [Business Glossary](/features/data-glossary/business-glossary) under [Data Glossary](/features/data-glossary) | | Data Entity Group | DEG | Logical grouping of data entities inside the catalog | [Data Entity Groups & Domains](/features/data-discovery/groups-domains) under [Data Discovery](/features/data-discovery) | | ML Experiments | ML Experiment Logging (deprecated) | A Data Entity Group collecting the entities produced by one training run — inputs, jobs, models, artifacts. Catalog view, not a metrics tracker. | [Data Entity Groups & Domains → Relationship to ML Experiments](/features/data-discovery/groups-domains#relationship-to-ml-experiments) | | ODD Specification | Ingestion API spec, ingress API | Wire contract between producers and the platform | [opendatadiscovery-specification](https://github.com/opendatadiscovery/opendatadiscovery-specification) | | Integration | — | Umbrella term for any path metadata takes from a source into the Platform — collectors (pull) and push adapters (push). Prefer in user-facing prose unless direction (pull/push) matters. | [Integrations hub](/integrations/integrations) | | Adapter | — | Source→spec mapper (push or pull); extract-and-map only, never runs alone. Classified by **strategy** (pull / push) and **deployment shape**. | [The architecture chain](#the-architecture-chain) | | Pull adapter | — | Pull-strategy adapter — reads from the source on a cadence; the adapter knows the source endpoint and credentials. Today always paired with the collector-hosted deployment shape (configured via a plugin). | [The architecture chain](#the-architecture-chain) | | Plugin | Adapter instance, adapter config | A configured pull-adapter instance inside a collector. Push adapters do not use the plugin term. | [The architecture chain](#the-architecture-chain) | | Collector | Pull-adapter container (informal) | Container of pull adapters + runtime; the collector-hosted deployment shape. **Not** a synonym for "pull adapter". | [The architecture chain](#the-architecture-chain) | | Push adapter | Push-client (client-server framing) | Push-strategy adapter — the source initiates the data flow. Three deployment shapes: **in-process plugin / extension** (dbt, GE, Airflow, Spark), **standalone gateway** (`odd-tracing-gateway`), **direct SDK / CLI use** (`odd-cli`). Used when the discussion is about extract-and-map mechanics. | [The architecture chain](#the-architecture-chain) | | Push-client | Push adapter (extract-and-map framing) | Same component as **Push adapter**, framed from client-server topology — a producer-side client of the Platform server using push strategy. Used when the discussion is about deployment topology or network position. | [Architecture.md](/introduction/architecture) | | Standalone gateway | Push-adapter standalone shape, OTel gateway, tracing gateway | A push-adapter deployment shape: a separate service that source systems push to over an externally-defined wire protocol (today: OpenTelemetry/OTLP), with the Platform pulling the inferred entities. Today's only example is [`odd-tracing-gateway`](/integrations/integrations/odd-tracing-gateway). Distinct from in-process plugins (which live inside a source tool's runtime) and from collectors (which host pull adapters). | [`integrations/auxiliary/odd-tracing-gateway.md`](/integrations/integrations/odd-tracing-gateway) | | Catalog Overview page | Overview page, Main page, Data Entity Report (deprecated as page synonym) | The catalog's home page — main search, top tags, domains, the per-class **Entities** report, directory, and (when auth is on) owner association. Distinct from a data entity's own **Overview tab**, which is the per-entity landing view inside a detail page. | [Data Discovery](/features/data-discovery) (the bucket landing the home page surfaces) | | Master Data Management | MDM, Reference Data Management, Reference Data | The Data Governance pillar covering operator-curated reference data managed inside the platform. ODD ships the Reference-Data subset (Lookup Tables); golden records / survivorship / stewardship workflows are not part of ODD today. | [master-data-management.md](/features/master-data-management) | | Lookup Tables | Reference tables, Master Data tables | Operator-curated reference tables managed inside the platform — schema, data, RBAC, API surface. Exposed in the catalog as Data Entities of type `LOOKUP_TABLE`. UI section: **Master Data** top-level tab. | [lookup-tables.md](/features/master-data-management/lookup-tables) | | Slack alert webhook | Slack notifications, Slack incoming webhook | Outgoing-only HTTP POST of alert messages into a Slack channel via `notifications.receivers.slack.url`. One-way write — no thread state, no replies read back. **Distinct** from the Slack collaboration app. Consumer: `SlackNotificationSender` (gated by `@ConditionalOnProperty(name = "notifications.receivers.slack.url")`). | [Enable Alert Notifications](/configuration-and-deployment/odd-platform#enable-alert-notifications) | | Slack collaboration app | Slack Events API, Slack OAuth integration, Data Collaboration Slack | Full Slack app for in-app per-entity discussion threads — OAuth (`datacollaboration.slack-oauth-token`) plus the [Slack Events API](https://docs.slack.dev/apis/events-api/) webhook to read replies back into the platform; bidirectional. **Distinct** from the Slack alert webhook. Routes gated by `@ConditionalOnDataCollaboration` (returns `404 Not Found` when `datacollaboration.enabled=false`). | [Enable Data Collaboration](/configuration-and-deployment/odd-platform#enable-data-collaboration) | | Multilingual UI | i18n, internationalisation, locale switching, language switching | Seven-locale (en/es/ch/fr/ua/hy/br) UI shell translation bootstrapped at SPA startup; the active locale persists per browser device in `localStorage`. API surface and operator-authored content stay in their source language. | [Multilingual UI](/features/multilingual-ui) | New aliases get added as they're discovered. If you notice a term that is missing or ambiguous, open an issue or a PR — the goal is that searching any common name lands you on the right page. # Architecture The structural mental model of an Open Data Discovery deployment — five-stage data flow, the components that run where, and the architectural concerns that cross every component. This page is the **structural mental model** of an Open Data Discovery deployment — what runs where, how metadata flows from a source system to a user's screen, and which architectural concerns cross every component. It is the front door before [Features](/features/features), [Integrations](/integrations/integrations), and [Configure ODD Platform](/configuration-and-deployment/odd-platform). For the producer-side vocabulary used here (Adapter, Plugin, Collector, Push adapter), see [Main Concepts → The architecture chain](/introduction/main-concepts#the-architecture-chain); this page operates in **client-server topology framing** (Push-client, Collector, Platform, Server). ![](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-afdf516ec0a91c5436272691485be0e37b834cb4%2Farchitecture_collector.png?alt=media) ## Data flow Metadata moves through five stages between a source system and a catalog user: 1. **Produce.** A source system has metadata that needs to surface in the catalog — a database schema, a job graph, a dbt manifest, a Spark lineage event, a Lookup-Table row. 2. **Ingest.** A producer (Collector or Push-client) sends metadata to the platform's Ingestion API. Pull producers (Collectors) poll on a schedule; push producers (in-process plugins, gateways, SDK callers) emit on the source's own cadence. Both speak the [ODD Specification](https://github.com/opendatadiscovery/opendatadiscovery-specification) — the wire contract. 3. **Store.** The platform writes the metadata to PostgreSQL keyed by [ODDRN](/introduction/main-concepts#oddrn). Same-ODDRN means same entity across ingests, across producers, over time — that is what makes cross-system lineage possible. 4. **Query.** UI calls and external scripts hit the Platform API (`/api/...`). Reads serve the catalog (search, lineage, alerts, glossary, query examples, relationships); writes mutate the catalog (ownership, tags, alert status, halt configuration, lookup-table rows). See the [API Reference hub](/developer-guides/api-reference) for the full surface. 5. **Render.** The platform UI (served from the same process) renders the catalog: search, entity pages, lineage graphs, alert tabs, the Directory drill-down, the Catalog Overview home page. The Push-client / Collector split is **only at stage 2** — every later stage is identical regardless of which producer family fed the catalog. ## Deployment topology | Component | What it is | What an operator deploys | Configuration home | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Platform (Server)** | The Spring-Boot application: Ingestion API, Platform API, UI, scheduled jobs (housekeeping, alerting, data-collaboration sender). | One Platform process plus PostgreSQL. | [`configuration-and-deployment/odd-platform.md`](/configuration-and-deployment/odd-platform). | | **Collector** | Container of **pull** adapters plus the runtime around them (adapter launcher, logger, Platform-API client, scheduler). The canonical implementation is [`odd-collector`](https://github.com/opendatadiscovery/odd-collectors/tree/main/odd-collector); cloud-specific siblings are [`odd-collector-aws`](https://github.com/opendatadiscovery/odd-collectors/tree/main/odd-collector-aws), [`odd-collector-azure`](https://github.com/opendatadiscovery/odd-collectors/tree/main/odd-collector-azure), [`odd-collector-gcp`](https://github.com/opendatadiscovery/odd-collectors/tree/main/odd-collector-gcp), and [`odd-collector-profiler`](https://github.com/opendatadiscovery/odd-collector-profiler). | One Collector container per cloud / source-family group, each holding many configured **plugins** (one per source instance). | [`developer-guides/build-and-run/build-and-run-odd-collectors.md`](/developer-guides/build-and-run/build-and-run-odd-collectors). | | **Push-client (in-process plugin)** | A push-strategy adapter that runs **inside** the source system's runtime — a dbt plugin, an Airflow plugin, a Great Expectations checkpoint action, a Spark listener, an `odd-cli` invocation. | Installed alongside the source application; emits metadata on the source's own cadence. | Per-tool repos under [opendatadiscovery on GitHub](https://github.com/opendatadiscovery); see [Integrations](/integrations/integrations). | | **Push-client (standalone gateway)** | A push-strategy adapter that runs as its own service. Source systems push over an externally-defined wire protocol (today: OpenTelemetry/OTLP for [`odd-tracing-gateway`](/integrations/integrations/odd-tracing-gateway)); the gateway processes the input and exposes the inferred entities for the Platform / a collector to pull through the standard adapter-contract entities API. | One gateway process per network perimeter that needs aggregated push ingress. | [`integrations/auxiliary/odd-tracing-gateway.md`](/integrations/integrations/odd-tracing-gateway). | | **UI** | Single-page React application served from the Platform process at `/`. | Same process as the Platform — operators do not deploy the UI separately. | (Configured indirectly through `odd.platform-base-url`; see [Configure ODD Platform](/configuration-and-deployment/odd-platform).) | Centralised: the Platform (one server, one PostgreSQL) and the UI (served from the same process). Distributed: every Collector and every Push-client lives in or beside its source system. The reason ODD scales to many sources is that the producer side is horizontally distributable while the catalog stays a single coherent surface. ## Cross-cutting concerns A landing-level pointer per concern; every link below has its own canonical home with the full operator detail. * **Authentication.** UI / Platform-API auth (Disabled / Login form / OAUTH2 / LDAP) plus separate Server-to-server (S2S) tokens for programmatic clients plus an independent Ingestion-API filter for producer traffic. See [Enable security](/configuration-and-deployment/enable-security) — the three surfaces are deliberately decoupled. * **Alerting.** Platform-detected (failed jobs, failed DQ tests, schema-incompatible changes, distribution anomalies) and externally-injected (Prometheus AlertManager via `/ingestion/alert/alertmanager`). Dispatch goes to in-app tabs, optional Slack webhook, optional email. See [Active platform features → Alerting](/features/active-platform-features/alerting) and [Active platform features → Notifications](/features/active-platform-features/notifications), with the operator-side configuration on [Configure ODD Platform → Enable Alert Notifications](/configuration-and-deployment/odd-platform#enable-alert-notifications). * **Lineage.** Cross-system upstream / downstream graphs at entity granularity, plus group lineage for Data Entity Groups (including ML experiments). See [Data Lineage → Data Objects Lineage](/features/data-lineage/data-objects) and the [API Reference → Lineage](/developer-guides/api-reference/lineage) sub-page. * **Search.** Free-text plus seven facets — Datasource, Type, Namespace, Owner, Tag, Groups, Statuses. Complemented by the Directory's hierarchy-driven browse. See [Data Discovery](/features/data-discovery) and the dedicated [Search and Filtering](/features/data-discovery/search) page for the per-facet semantics and the per-result transparency icons. * **Attachments.** Per-entity files (PNG / PDF / docs) stored locally or to a REMOTE S3-compatible bucket. The default is the **local file system** at `/tmp/odd/attachments` — a path under `/tmp` that container runtimes typically wipe on restart, so attachments saved under the default do not survive a platform restart. Switch to `REMOTE` (S3-compatible) storage for any deployment where attachments must persist. See [Configure ODD Platform → Attachment storage](/configuration-and-deployment/odd-platform#attachment-storage) for the operator caveats. * **Data Collaboration.** Optional Slack-based per-entity discussion threads (full Slack app via OAuth + Events API webhook). Distinct from the alert webhook. See [Active platform features → Data Collaboration](/features/active-platform-features/data-collaboration) and [Configure ODD Platform → Enable Data Collaboration](/configuration-and-deployment/odd-platform#enable-data-collaboration). * **GenAI proxy.** Optional thin proxy from the platform to an external AI service the operator runs. The platform itself does not embed an LLM. See [Active platform features → GenAI assistant](/features/active-platform-features/genai). ## Pull vs Push — when to choose which Both topologies feed the same catalog through the same Ingestion API. The choice is operational: * **Pull (Collector)** when the source is a **passive data store** (database, warehouse, BI tool, ML registry, message broker) and you want **point-in-time snapshots on a cadence**. The Collector drives; the source has no awareness of the catalog. Most data-source integrations work this way. * **Push (Push-client)** when the source is an **already-running application** that you can instrument — Airflow DAGs, dbt runs, Spark jobs, Great Expectations validations, your own services calling `odd-cli` — and you want **per-run lineage and results reported as they happen**. The source drives; latency from event to catalog is bounded by the producer's own emit cadence. * **Both at once** is normal: a pull Collector indexes the warehouse catalog while an Airflow Push-client reports per-run lineage on top of it. For the in-the-spec view of push-strategy producers, see the [push model section of the ODD Specification](https://github.com/opendatadiscovery/opendatadiscovery-specification/blob/main/specification/specification.md#push-model). ## ODDRN **ODDRN** (Open Data Discovery Resource Name) is the stable string that identifies every entity in the system — a dataset, a column, a data source, a pipeline run. Producers generate an ODDRN for each entity they emit so the platform can recognise the same entity across ingests, across producers, and over time. ODDRN is what makes cross-system lineage possible, what makes idempotent ingests possible, and what gives the AlertManager webhook its `entity_oddrn` routing key. Operators rarely interact with ODDRNs directly — they become relevant when authoring a custom adapter. See [ODDRN](/introduction/main-concepts#oddrn) for the format, examples, and the generator libraries for Python and Java; see [Build a custom collector](/developer-guides/build-and-run/custom-collectors) for the end-to-end Python pattern. ## Where to read the code The mapping from this overview to the actual code lives in the workspace's navigation domain pages — `navigation/domains/{feature}.md` files maintain controller / service / configuration / UI pointers per feature so a reader does not need to grep. The contributor-facing entry points on the public doc tree are: * [GitHub organization overview](/developer-guides/github-organization-overview) — every ODD repository with a one-line summary. * [Build and run](/developer-guides/build-and-run) — Platform and Collector build / deploy walkthroughs, plus the [Build a custom collector](/developer-guides/build-and-run/custom-collectors) developer guide. * [Main Concepts](/introduction/main-concepts) — the producer-side vocabulary (Adapter / Plugin / Collector / Push adapter / Data source) and the Data Governance map (which pillars ODD covers, which are roadmap). * [API Reference](/developer-guides/api-reference) — the canonical hub for every HTTP endpoint, with per-feature sub-pages. # Overview One-page index of ODD Platform's most important features — a quick-scan surface that points each feature at its canonical home, API surface, and operator-configuration keys. This page is the **one-page index** of ODD Platform's most important features — a quick-scan surface for discovering what the platform does. For step-by-step walkthroughs and configuration detail, follow the cross-links from each feature's section to its dedicated page: each feature below points at (a) its **canonical home** — for read-oriented features, one of the six governance pillars ([Data Discovery](/features/data-discovery), [Data Modelling](/features/data-modelling), [Master Data Management](/features/master-data-management), [Data Quality](/features/data-quality), [Data Lineage](/features/data-lineage), [Data Glossary](/features/data-glossary)); for operator-mutating UI workflows, the [Management](/features/management) section; for the platform's event-driven, opt-in behaviours (alerts, notifications, activity tracking, data collaboration, GenAI), the [Active platform features](/features/active-platform-features) section; (b) its **API surface** under the [API Reference](/developer-guides/api-reference) hub; and (c) its **operator-configuration keys** under [Configure ODD Platform](/configuration-and-deployment/odd-platform). For the broader vocabulary and the [Data Governance map](/introduction/main-concepts#data-governance-map), see [Main Concepts](/introduction/main-concepts). [Metadata Storage](#metadata-storage)\ [Search and Filtering](/features/data-discovery/search)\ [End-to-end Data Objects Lineage](/features/data-lineage/data-objects)\ [End-to-end Microservices Lineage](/features/data-lineage/microservices)\ [Data Quality Test Results Import](/features/data-quality/test-results-import)\ [Alerting](/features/active-platform-features/alerting)\ [ML Experiments](/features/data-discovery/groups-domains#relationship-to-ml-experiments)\ [Manual Object Tagging](/features/data-discovery/tagging)\ [Data Entity Groups & Domains](/features/data-discovery/groups-domains)\ [Catalog Overview page](/features/data-discovery/catalog-overview)\ [Directory](/features/data-discovery/directory)\ [Dictionary terms](/features/data-glossary/business-glossary)\ [Activity Feed for Monitoring Changes](/features/active-platform-features/activity-feed)\ [Data Collaboration](/features/active-platform-features/data-collaboration)\ [Dataset Quality Statuses (SLA)](/features/data-quality/sla-statuses)\ [Dataset schema diff](/features/data-discovery/schema-diff)\ [Associating Terms with Data Entities through Descriptive Information](/features/data-glossary/business-glossary#term-to-entity-associations)\ [Adding Business Names for Data Entities and Dataset Fields](/features/data-discovery/business-names)\ [Entity description](/features/data-discovery/entity-description)\ [Custom metadata](/features/data-discovery/custom-metadata)\ [Per-column annotation](/features/data-discovery/per-column-annotation)\ [Integrating Vector Store Metadata](/features/data-discovery/vector-stores)\ [GenAI assistant](/features/active-platform-features/genai)\ [Data Modelling](/features/data-modelling)\ [Query Examples](/features/data-modelling/query-examples)\ [Relationships and ERDs](/features/data-modelling/relationships)\ [Data Quality Dashboard](/features/data-quality/dashboard)\ [Filters to Include and Exclude Objects from Ingest](/integrations/integrations/ingestion-filters)\ [Data Entity Statuses](/features/data-discovery/statuses)\ [Alternative Secrets Backend](/configuration-and-deployment/collectors-secrets-backend)\ [Lookup Tables](/features/master-data-management/lookup-tables)\ [Integration Wizards](/integrations/integrations/integration-wizard)\ [Data Entity Attachments](/features/data-discovery/attachments)\ ["Recommended" panel on the main page](/features/data-discovery/catalog-overview#recommended)\ [Custom navigation links](https://docs.opendatadiscovery.org/features/pages/YH2ILihhfTPfYTyBhtw2#additional-navigation-links-odd.links)\ [Metadata stale](/features/data-discovery/metadata-stale)\ [Machine-to-Machine (M2M) tokens](/configuration-and-deployment/enable-security/authentication/s2s)\ [Multilingual UI](/features/multilingual-ui) {% hint style="info" %} **Looking for the HTTP API?** Every Platform endpoint is documented at [API Reference](/developer-guides/api-reference) — grouped by feature area, with operation IDs, paths, and back-links to each feature page. {% endhint %} ## Metadata Storage The platform's metadata storage is a single PostgreSQL database that holds every catalog entity, every lineage edge, every term, and the full-text search index — no extra Elasticsearch / Solr / Neo4j services to deploy. Metadata is processed near-real-time as collectors and push adapters report it; storage capacity scales with the underlying PostgreSQL cluster. For the deployment topology and how metadata flows from a source system to the catalog screen, see [Architecture → Data flow](/introduction/architecture#data-flow); for the operator-side configuration of the database itself, see [Configure ODD Platform → PostgreSQL Configuration](/configuration-and-deployment/odd-platform#postgresql-configuration). ## Search and Filtering The catalog's query-oriented entry path — type a term, narrow by seven facets (Datasource / Type / Namespace / Owner / Tag / Groups / Statuses), and find data entities across names and metadata in seconds. Search is available across the Catalog, Query Examples, Master Data, Management, and Dictionary tabs. See the dedicated [Search and Filtering](/features/data-discovery/search) page under [Data Discovery](/features/data-discovery) for the seven facets, the per-result information / question icons, and the indexing / ranking technical detail. ## End-to-end Data Objects Lineage Upstream and downstream lineage across the full ODD entity model — datasets, transformers, transformer runs, quality tests, consumers, data inputs, data entity groups (including [ML experiments](/features/data-discovery/groups-domains#relationship-to-ml-experiments)), and entity relationships — rendered as a per-entity Lineage tab plus the dedicated Group lineage endpoint that returns the union of a [Data Entity Group](/features/data-discovery/groups-domains)'s children's lineage. See the dedicated [Data Objects Lineage](/features/data-lineage/data-objects) page under [Data Lineage](/features/data-lineage) for the entity-class participation table, the `lineage_depth` and `expanded_entity_ids` query parameters, and the Group lineage endpoint. ## End-to-end Microservices Lineage Microservice call lineage rendered alongside data-object lineage — sourced from OpenTelemetry traces ingested through [`odd-tracing-gateway`](/integrations/integrations/odd-tracing-gateway) (the platform's only [standalone gateway](/introduction/main-concepts#the-architecture-chain) push adapter today). See the dedicated [Microservices Lineage](/features/data-lineage/microservices) page under [Data Lineage](/features/data-lineage) for the OpenTelemetry-to-ODD path and the gateway's role in the architecture chain. ## Data Quality Test Results Import The Platform ingests test results from [**Great Expectations**](/integrations/integrations/odd-great-expectations) and [**dbt tests**](/integrations/integrations/odd-dbt) (both push-clients in the ODD ecosystem), plus statistical profiles generated by [**odd-collector-profiler**](/integrations/integrations/odd-collector-profiler) (which uses Capital One's [DataProfiler](https://github.com/capitalone/DataProfiler) under the hood). Custom frameworks can push their own test results through the `POST /ingestion/entities` endpoint of the [ODD Specification](/introduction/main-concepts#odd-specification). See the dedicated [Test Results Import](/features/data-quality/test-results-import) page under [Data Quality](/features/data-quality) for the per-integration setup paths and the custom-framework escape hatch. ## Alerting The platform watches each catalogued entity for failed jobs, failed data-quality tests, backwards-incompatible schema changes, and externally-injected distribution anomalies — and tracks every alert through an `OPEN` → `RESOLVED` lifecycle with per-entity halt configuration and four navigation views (All / My Objects / Downstream / Upstream). For the alert types and what triggers each, the lifecycle and auto-cleanup rules, the halt-notification UI and its `Distribution anomaly` caveat, and the API surface, see the dedicated [Alerting](/features/active-platform-features/alerting) page under [Active platform features](/features/active-platform-features). For how alerts get out of the platform — Slack, email, generic webhook, plus the Prometheus AlertManager inbound webhook — see [Notifications](/features/active-platform-features/notifications). ## ML Experiments In ODD, an **ML experiment** is a [Data Entity Group](/features/data-discovery/groups-domains) of class `ML_EXPERIMENT` that collects the entities produced by a training run — input datasets, feature tables, training jobs, model instances, and resulting model artifacts — into one logical container. ML Experiments are not a separate feature surface; they reuse the DEG primitive for a specific workflow. See [Data Entity Groups & Domains → Relationship to ML Experiments](/features/data-discovery/groups-domains#relationship-to-ml-experiments) under [Data Discovery](/features/data-discovery) for the framing, the catalog-view-not-experiment-tracker positioning, and the lineage cross-link. ## Manual Object Tagging Lightweight labelling for data entities and columns — apply tags to drive faceted search, surface `Important`-flagged labels visually, and feed the Catalog Overview's Top tags chip strip. See the dedicated [Manual Object Tagging](/features/data-discovery/tagging) page under [Data Discovery](/features/data-discovery) for the tag application workflow, the three `TAG_*` RBAC permissions, and the read-side / Management-side split (this page is read-side; vocabulary curation lives at [Management → Tags](/features/management)). ## Data Entity Groups & Domains Logical containers that gather related entities (datasets, transformers, quality tests, consumers) under one umbrella with their own metadata, owners, tags, and terms. Flagging a DEG as a **domain** surfaces it on the [Catalog Overview page](/features/data-discovery/catalog-overview)'s Domains section as a top-level discovery surface. See the dedicated [Data Entity Groups & Domains](/features/data-discovery/groups-domains) page under [Data Discovery](/features/data-discovery) for the DEG metadata model, the Domain framing, the relationship to ML Experiments, and the Group lineage cross-link. ## Catalog Overview page The **Overview page** is the catalog's home page — a unified surface that combines [Search](/features/data-discovery/search), the [Directory](/features/data-discovery/directory) level-1 cards, [Top tags](/features/data-discovery/tagging), [Domains](/features/data-discovery/groups-domains), the per-class **Entities** report, the **Recommended** quick-jumps, and (when authentication is on) an Owner-association request. See the dedicated [Catalog Overview page](/features/data-discovery/catalog-overview) page under [Data Discovery](/features/data-discovery) for the per-section walkthrough, the Recommended panel sub-surface, and the disambiguation between the catalog's Overview *page* and a data entity's Overview *tab*. ## Directory The **Directory** is the catalog's browse-oriented entry point. It complements [Search](/features/data-discovery/search): where Search is query-driven, the Directory walks down a four-level hierarchy — **data source types → data sources → entity types → entities** — so an operator can drill into the catalog without typing a query. Reach for it when you know the kind of source you want to explore (PostgreSQL, Snowflake, Kafka, ...) but not the specific entity, or when you want a per-source coverage view. See the dedicated [Directory](/features/data-discovery/directory) page under [Data Discovery](/features/data-discovery) for the level-by-level walkthrough, the four backing API endpoints (`/api/directory`, `/api/directory/datasources`, `/api/directory/datasources/{id}/types`, `/api/directory/datasources/{id}`), and the relationship to the [Catalog Overview page](/features/data-discovery/catalog-overview) (which surfaces the Directory's level-1 cards inline on the home page). ## Dictionary terms Operator-curated term entities that name and describe the concepts your data represents. Terms are first-class catalog citizens with their own descriptions, owners, namespaces, RBAC, and links to data entities (description-text mentions and direct term-to-term links). See the dedicated [Business Glossary](/features/data-glossary/business-glossary) page under [Data Glossary](/features/data-glossary) for the full term-creation flow, the seven `TERM_*` permissions, term-to-term linking modes, the term-to-entity descriptive walkthrough, and the API surface. ## Activity Feed for Monitoring Changes The platform records every metadata change as a typed event on a global **Activity** page and on each entity's own **Activity** tab — entity lifecycle transitions, ownership changes, tag and term assignments, dataset-field edits, data-entity-group changes, and the alert-state transitions described above. The feed is the catalog's audit trail and its change-driven discovery surface. See the dedicated [Activity Feed](/features/active-platform-features/activity-feed) page under [Active platform features](/features/active-platform-features) for the seven facets on the global filter panel, the full event-type catalogue (grouped by the metadata area each event describes), and the configuration entry for retention partitioning. ## Data Collaboration ODD Platform's **Data Collaboration** feature lets users start in-app discussion threads anchored to specific data entities, with replies tracked back from a Slack workspace via OAuth + the [Slack Events API](https://docs.slack.dev/apis/events-api/). Conversations stay attached to the entity that anchored them, so an operator returning to a dataset months later can read the original threads — context, decisions, and follow-ups — without leaving the catalog. The feature is disabled by default (`datacollaboration.enabled=false`); for the per-entity Discussions-tab visibility caveat when disabled, the message-flow model, the disambiguation between this Slack app and the [Slack alert webhook](/features/active-platform-features/notifications#slack-incoming-webhook), and the operator-side setup, see the dedicated [Data Collaboration](/features/active-platform-features/data-collaboration) page under [Active platform features](/features/active-platform-features). {% hint style="warning" %} **Platform-feature toggles are captured at JVM boot and the top-level navigation chrome is invariant to the toggle state.** Three related properties operators should know: * **Boot-immutable.** The active feature set is read from configuration at JVM startup (`@Value` injection on the feature resolver's constructor) and frozen for the lifetime of the process. Runtime configuration changes — for example via Spring Boot Actuator's `/actuator/refresh` endpoint — are not reflected by the platform's feature-active endpoint or by the sub-page feature gates. To change a platform feature's enabled state, edit the configuration and **restart the JVM process**. * **Both keys must be present, or the platform fails to start.** The two feature flags `datacollaboration.enabled` and `notifications.enabled` are injected without a fallback default. A stock install is safe — the bundled `application.yml` supplies both keys set to `false` — but if you supply your own externalised `application.yml` (exactly the "edit the configuration and restart" workflow above) and **omit either key**, the platform aborts startup with an opaque `BeanCreationException: Could not resolve placeholder 'datacollaboration.enabled'` (or `notifications.enabled`). When overriding configuration, always carry both keys forward explicitly rather than copying only the line you want to change. * **Chrome-invariant.** The platform's top-level navigation tabs (Data Modelling, Data Collaboration-flavoured surfaces, etc.) are rendered regardless of the corresponding feature-flag setting. Feature-gated functionality **inside** those tabs honours the active feature set — sub-page affordances, write endpoints, and gated panels behave correctly when the flag is off — but the tab itself stays visible. Users disabling `datacollaboration.enabled=false`, for example, still see the Data Modelling tab on the toolbar; clicking it lands on a page whose feature-gated affordances are correctly hidden, but the tab itself is not removed. The operator-visible consequence is "the platform feature gating is consistent at the per-affordance level, not at the chrome level." Operators expecting "disabling a feature removes its tab" should know this is not how the platform's UI shell behaves today. The two configuration keys covered by this caveat are `datacollaboration.enabled` and `notifications.enabled` — the only two that flow through the boot-time feature resolver — plus any future platform-feature flag added under the same `@Value` boot-injection pattern. **`genai.enabled` is not one of them.** Despite sitting next to the two flags above in configuration, the GenAI assistant toggle does not flow through the feature resolver: it is re-read on every call at the service layer rather than snapshotted at boot, and it is not part of the active-feature set the chrome consults. A `genai.enabled` change therefore takes effect on the next request without a restart — but, like the two flags above, it does not add or remove a top-level navigation tab. {% endhint %} ## Dataset Quality Statuses (SLA) Operator-set **Minor / Major / Critical** severities on dataset test results, aggregated into a single dataset-level **SLA colour** (Green / Yellow / Red) that downstream BI reports import directly via the `/api/datasets/{id}/sla` endpoint. See the dedicated [Dataset Quality Statuses (SLA)](/features/data-quality/sla-statuses) page under [Data Quality](/features/data-quality) for the severity-setting workflow, the BI-report URL pattern, and the actual SLA-colour computation logic (which is **not** a direct severity-to-colour mapping — colours come from `SLACalculator` based on aggregate severity weights). ## Dataset schema diff The platform compares each dataset's metadata between revisions and surfaces every change — added columns, removed columns, type changes, renames — as a visual side-by-side diff on the dataset's Structure tab. Backwards-incompatible changes additionally raise a [Backwards-incompatible schema change](/features/active-platform-features/alerting#backwards-incompatible-schema-change-what-triggers-it) alert. See the dedicated [Dataset schema diff](/features/data-discovery/schema-diff) page under [Data Discovery](/features/data-discovery) for the revision history walkthrough, the diff illustrations, and the link to the alert rule. ## Associating Terms with Data Entities through Descriptive Information The Wikipedia-About-style walkthrough — adding business terms to the Dictionary, designating term owners, authoring rich descriptions, linking terms inline using the required format, and the reverse-search capability that surfaces every entity and column linked to a term. See the dedicated [Business Glossary → Term-to-entity associations](/features/data-glossary/business-glossary#term-to-entity-associations) section under [Data Glossary](/features/data-glossary) for the full step-by-step walkthrough with screenshots. ## Adding Business Names for Data Entities and Dataset Fields Operators can assign **business names** to data entities and to individual dataset fields — alternative human-readable labels that surface alongside the original technical names everywhere the entity is rendered. See the dedicated [Business names for data entities and dataset fields](/features/data-discovery/business-names) page under [Data Discovery](/features/data-discovery) for the per-entity and per-field workflows, the activity-feed audit-trail event, and the RBAC permissions. ## Entity description The platform's per-entity **Description** panel is a Markdown-authored prose surface — operators write rich descriptions of what an entity represents, with linked glossary terms inline. The rendered description surfaces on the entity's Overview tab and on several adjacent surfaces (search-result previews, lineage-node hovers, group cards) so the same authored prose travels with the entity wherever it appears. See the dedicated [Entity description](/features/data-discovery/entity-description) page under [Data Discovery](/features/data-discovery) for the Markdown authoring and render pipeline, the `DATA_ENTITY_DESCRIPTION_UPDATE` permission, the activity-feed event, and the cross-surface stored-XSS family admonition operators should review before opening the surface to less-trusted authors. ## Custom metadata Operators can attach typed custom fields to data entities — strings, integers, booleans, dates, URLs, JSON, and arrays — with the field definitions managed as a separate catalog and per-entity values authored on the entity's Metadata panel. INTERNAL fields are operator-curated; EXTERNAL fields arrive from collector-ingested metadata. See the dedicated [Custom metadata](/features/data-discovery/custom-metadata) page under [Data Discovery](/features/data-discovery) for the two-half architecture (FIELD catalogue read + per-entity VALUE write), the 7 supported types, the INTERNAL / EXTERNAL origin distinction, the per-entity permissions, and the 4 known limitations operators should know before depending on the feature. ## Per-column annotation On every dataset's **Structure** tab, each column carries a per-column composer that lets operators author five distinct annotations — column description, column tags, glossary terms, enum values, and a column-level business name — each gated by its own RBAC permission and emitting its own activity-feed event. See the dedicated [Per-column annotation](/features/data-discovery/per-column-annotation) page under [Data Discovery](/features/data-discovery) for the 5 sub-editors, the per-sub-editor permissions and audit-feed coverage, and the 3 operator-visible write-path caveats (including the silently-`403`s wiring-bug pair on `DATASET_FIELD_ADD_TERM` and the empty-array-clears-all-tags shape of `updateDatasetFieldTags`). ## Integrating Vector Store Metadata The platform recognises **vector-typed datasets** as a first-class catalog primitive — a dedicated `Vector Store` dataset type plus a `Vector` column data type — so vector tables sit alongside relational ones in search, lineage, and ownership. Today the recognition is wired up for PostgreSQL `pgvector` columns via [`odd-collector`](/integrations/integrations/odd-collector); other adapters can emit the same types by following the [specification](https://github.com/opendatadiscovery/opendatadiscovery-specification/blob/main/specification/entities.yaml). See the dedicated [Vector Store metadata](/features/data-discovery/vector-stores) page under [Data Discovery](/features/data-discovery) for the specification source, the adapter coverage, and how the type surfaces in the catalog. ## GenAI assistant The platform ships an opt-in **GenAI assistant** that proxies natural-language questions to an external AI service the operator runs separately. Disabled by default (`genai.enabled=false`); when turned on, exposes a single platform endpoint `POST /api/genai/ask` that forwards each question to `POST {genai.url}/query_data` and returns the answer. API-only today — no in-app UI affordance currently calls it. See the dedicated [GenAI assistant](/features/active-platform-features/genai) page under [Active platform features](/features/active-platform-features) for the configuration keys (with the operator-relevant defaults caveat — `genai.url` empty + `genai.request_timeout=0` will silently misconfigure if only `enabled=true` is set), the external AI service contract (`POST /query_data` with JSON `{"question": "..."}`), and the platform's `/api/genai/ask` request / response schemas. ## Data Modelling The **Data Modelling** section of the platform houses operator-curated artefacts that describe how data is intended to be used — canonical query examples and the entity-to-entity relationships that collectors extract or that operators define. It opens from the top-level navigation **Data Modelling** and exposes two sub-surfaces: **Query Examples** (the snippets below) and **Relationships / ERDs**. See the [Data Modelling overview](/features/data-modelling) for the section's structure, the UI entry points, and the RBAC permissions that gate each surface. ## Query Examples **Query Examples** are operator-curated SQL / KQL / Spark snippets attached to data entities and glossary terms — the canonical "how this dataset is used" surface. Snippets carry a description that doubles as a prompt-style explanation of intent, link to one or more datasets, and link to terms; a dedicated faceted search and a per-entity / per-term lookup surface them across the catalog. See the dedicated [Query Examples](/features/data-modelling/query-examples) page under [Data Modelling](/features/data-modelling) for the UI walkthrough, the seven `QUERY_EXAMPLE_*` RBAC permissions, the 16-endpoint API surface, and the term-linking workflow. ## Relationships and ERDs ODD Platform tracks entity-to-entity relationships as first-class catalog objects: **ERD edges** between table-class entities (derived from foreign-key constraints in the source) and **graph edges** between graph-store nodes. The dedicated **Data Modelling → Relationships** surface lists every relationship across all data sources, with a tab strip for filtering by ERD vs graph and a search input scoped to relationship names. See the dedicated [Relationships](/features/data-modelling/relationships) page under [Data Modelling](/features/data-modelling) for the cardinality model (`ONE_TO_EXACTLY_ONE` / `ONE_TO_ZERO_OR_ONE` / `ONE_TO_ONE_OR_MORE` / `ONE_TO_ZERO_ONE_OR_MORE`), the API surface, and the per-adapter ingestion coverage (PostgreSQL and Snowflake adapters surface ERD today; no adapter currently emits graph relationships). ## Data Quality Dashboard Catalog-wide quality view at `/data-quality` — three breakdown rings (Table Health / Test Results / Monitored Tables), six anomaly-class metrics (Assertion Tests / Column Values Anomalies / Freshness Anomalies / Schema Changes / Unknown Category / Volume Anomalies), and per-side filter sets (one for tables, one for tests; `AND`-only conjunction). See the dedicated [Quality Dashboard](/features/data-quality/dashboard) page under [Data Quality](/features/data-quality) for the per-anomaly-class definitions, the monitored-vs-unmonitored breakdown, and the two-side filtering model. ## Filters to Include and Exclude Objects from Ingest Pull adapters in ODD's collectors ingest **everything they can see** by default. Per-plugin **ingestion filters** scope a plugin to a regex-defined slice — `schemas_filter` (PostgreSQL, Snowflake), `filename_filter` (S3, Azure Blob, GCS), `datasets_filter` (BigQuery), `pipeline_filter` (Azure Data Factory), and similar — so the catalog stays focused on what teams care about. See the dedicated [Ingestion filters](/integrations/integrations/ingestion-filters) page under [Integrations](/integrations/integrations) for the include / exclude shape, the worked PostgreSQL example, and the per-adapter coverage matrix. ## Data Entity Statuses Every catalogued entity carries a status — `UNASSIGNED` (default), `DRAFT`, `STABLE`, `DEPRECATED`, or `DELETED` — that signals where it sits in its lifecycle. Statuses surface as a [Search](/features/data-discovery/search) facet, drive an Activity-feed event, and trigger a soft-delete TTL handled by the platform's housekeeping job. See the dedicated [Data Entity Statuses](/features/data-discovery/statuses) page under [Data Discovery](/features/data-discovery) for the per-status semantics, the operator workflow, the soft-delete TTL configuration, and the RBAC permission. ## Alternative Secrets Backend Store collector configuration — the Platform token, per-plugin database passwords, cloud-provider credentials — in an external secrets backend instead of plaintext in `collector_config.yaml`. Currently the AWS Systems Manager Parameter Store provider is supported; values from the backend override values set in the local YAML file. This feature is also known as the **collector secrets backend**. For the configuration reference, the region-resolution order, a worked SSM example, the required IAM permissions, and the known limitations (10-parameter pagination cap, no custom SSM endpoint, no timeout / retry override), see [Collector secrets backend](/configuration-and-deployment/collectors-secrets-backend). ## Lookup Tables **Lookup Tables** are operator-curated reference tables that live inside the ODD Platform itself rather than in an external source system — managed end-to-end (schema, data, versioning, RBAC), exposed in the catalog as standard Data Entities, and reachable both through the platform API and directly via PostgreSQL's `lookup_tables_schema`. Find them in the platform UI under the **Master Data** top-level tab → **Lookup Tables**. See the dedicated [Lookup Tables](/features/master-data-management/lookup-tables) page under [Master Data Management](/features/master-data-management) for the creation flow, supported field types, the Data tab walkthrough, the 9 `LOOKUP_TABLE_*` RBAC permissions, and the full `/api/referencedata/` API surface. ## Integration Wizards The **Integration Wizard** is an in-app UI under [**Management → Integrations**](/features/management) that helps operators bootstrap `collector_config.yaml`. Pick an integration, fill in a handful of source-specific fields, copy the rendered YAML snippet into your collector config — the wizard is a template generator, not an installer. See the dedicated [Integration Wizard](/integrations/integrations/integration-wizard) page under [Integrations](/integrations/integrations) for the per-card flow, the `META-INF/wizard/*.yaml` registry that backs it, the API surface (`GET /api/integrations`, `GET /api/integrations/{integration_id}`), the static-parameter substitution context (today only `platform_url`, sourced from `odd.platform-base-url`), and the wizard-vs-`collector_config.yaml` boundary. ## Data Entity Attachments Operators and users can attach **files** (images, PDFs, CSVs, TXT) and **links** (remote URLs) to any data entity for additional context — runbook PDFs, sample CSVs, dashboard screenshots, ticketing references. Attachments persist across re-ingests and can be edited or deleted at any time. See the dedicated [Data Entity Attachments](/features/data-discovery/attachments) page under [Data Discovery](/features/data-discovery) for the upload workflow, the storage-backend caveat (LOCAL is ephemeral; use REMOTE S3 / MinIO in production), and the [Attachment Storage Configuration](/configuration-and-deployment/odd-platform#attachment-storage-configuration) operator reference. ## "Recommended" panel on the main page The Recommended panel is a sub-surface of the [Catalog Overview page](/features/data-discovery/catalog-overview) that surfaces personalised quick-jumps for the signed-in user — recently-ingested owned entities, lineage neighbours, and the catalog's most-popular entities. See [Catalog Overview page → Recommended](/features/data-discovery/catalog-overview#recommended) under [Data Discovery](/features/data-discovery) for the four-column layout, the freshness indicator, the disambiguation from the Alerts → My Objects tab, and the [User-owner association](/configuration-and-deployment/enable-security/authorization/user-owner-association) prerequisite. ## Custom navigation links Operators can populate the App Info menu (the popup behind the information icon in the top-right toolbar) with their own links — runbooks, internal wikis, support channels, anything that helps users navigate from the catalog into the rest of the platform's surrounding ecosystem. Links are configured once on the platform side via the `odd.links[]` setting and surface to every signed-in user. For the configuration detail (YAML and env-var form, including the visibility caveat that every signed-in user can read the configured URLs), see [Configure ODD Platform → Additional navigation links](https://docs.opendatadiscovery.org/features/pages/YH2ILihhfTPfYTyBhtw2#additional-navigation-links-odd.links). Operationally part of the [Management](/features/management) section. ## Metadata stale Entities that have not been re-ingested for longer than `odd.data-entity-stale-period` (integer days; default `7`) are flagged with an orange clock icon next to their name everywhere they appear in the catalog — a discovery-time prompt that the metadata's freshness is uncertain. See the dedicated [Metadata stale](/features/data-discovery/metadata-stale) page under [Data Discovery](/features/data-discovery) for the freshness window's meaning, what the indicator does (and doesn't) signal, and the operator-side reference for tuning the value. ## Machine-to-Machine (M2M) tokens ODD Platform supports **server-to-server (S2S) API-key authentication** — a single shared static token presented in the `X-API-Key` header — for non-UI programmatic callers such as CI/CD jobs, ingestion pipelines, and automation scripts. Disabled by default; designed for trusted non-human callers and grants ADMIN-role access. For configuration, the header contract, the curl example, and security considerations (token rotation, HTTPS, blast radius), see [Server-to-server (S2S) authentication](/configuration-and-deployment/enable-security/authentication/s2s). Operationally part of the [Management](/features/management) section. ## Multilingual UI The platform's UI ships with seven locale translations — English (default), Spanish, Chinese, French, Ukrainian, Armenian, and Brazilian Portuguese (from 0.28.0) — loaded at SPA bootstrap and switchable from the **Select language** entry in the user-account menu on the toolbar. The active locale persists per browser device in `localStorage`; the API surface and operator-authored content (entity descriptions, glossary terms, custom-metadata field names, namespaces, tag names) remain in their source language regardless of the active locale. See the dedicated [Multilingual UI](/features/multilingual-ui) page for the 7 supported locales, the language-picker affordance in the user-account menu, the per-device-not-per-user persistence model, the missing-key fall-through behaviour, and the contribution workflow for adding new locales. # Data Discovery Top-level UI section for the catalog's two entry paths — query-oriented Search and hierarchy-oriented Directory — surfaced together on the Catalog Overview page. The **Data Discovery** section of ODD Platform is the home for finding entities in the catalog. The role is durable: anything that helps a user **locate** existing data — by typing a term, by walking a known structure, or by landing on the home page — belongs here. The section sits at the **operator-and-user front door**: most catalog interactions begin with one of the two entry paths surfaced from this pillar. ODD covers Data Discovery fully — both entry paths ship today, and the platform's home page renders them side by side as the catalog's first-encounter view. See the [Data Governance map](/introduction/main-concepts#data-governance-map) for the position of Data Discovery in the overall pillar set. Open it from the top-level navigation **Catalog** (Search-first landing) or **Directory** (hierarchy-first level-1 view). The Catalog Overview page surfaces both entry paths inline. ![Catalog Search results — entity-class tabs along the top (All / My Objects / Datasets / Transformers / Data Consumers / Data Inputs / Quality Tests / Groups / Relationships) with per-class counts; the Filters left-rail exposes Datasource / Namespace / Owner / Groups / Statuses facets. The result list shows mixed entity classes (LOOKUP\_TABLE, ENTITY\_RELATIONSHIP, DEG, DATASET, TRANSFORMER) — search and faceted filtering are how operators move from "I want a user-related entity" to a specific row.](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-9b425b1e87023001da81274872ac46c7939c388f%2Fsearch-facets.png?alt=media) ## Subsections The catalog's two entry paths plus the per-feature surfaces that mark up, classify, and signal freshness on the entities they reach. **Discovery entry paths** * [**Catalog Overview page**](/features/data-discovery/catalog-overview) — the catalog's **home page**. A unified surface that combines Search, the Directory's level-1 cards, Top tags, Domains, the per-class Entities report, the Recommended quick-jumps, and (when authentication is on) the Owner-association request. Most catalog sessions start here. * [**Directory**](/features/data-discovery/directory) — the catalog's **browse-oriented** entry point. Four-level drill-down (data source types → data sources → entity types → entities) backed by `/api/directory`. Use it when you know the *kind* of source but not the specific instance, when you're auditing per-source coverage, or when you're walking a teammate through the catalog. * [**Search and Filtering**](/features/data-discovery/search) — the catalog's **query-oriented** entry point. Free-text search across entity names plus seven facets (Datasource / Type / Namespace / Owner / Tag / Groups / Statuses). The query-driven counterpart to the Directory. **Per-entity detail surface** * [**Data entity detail page**](/features/data-discovery/entity-detail-page) — the destination of every catalog discovery. Covers the Overview tab composition, the class-driven panel matrix that decides which panels and tabs appear, the class/type badges in the header, the sidebar list truncation (Tags / Terms / Groups), and the per-panel permission map. The container surface that the annotation features below render onto. **Annotating discovered entities** * [**Entity description**](/features/data-discovery/entity-description) — operator-authored Markdown description on every data entity. The primary free-text annotation surface; rendered on the Overview tab and surfaced as the preview snippet on search-result rows, Recommended-tile cards, and Directory-level-4 entity rows. Carries a load-bearing security caveat on the platform's no-write-time-sanitisation posture across six Markdown surfaces. * [**Custom metadata**](/features/data-discovery/custom-metadata) — operator-curated typed key/value fields per data entity, plus the deployment-shared field catalogue that backs the autocomplete picker. Covers the seven supported field types, INTERNAL versus EXTERNAL (collector-ingested) origin, and four load-bearing caveats (silent no-op write, dropped `active` flag, unauthenticated catalogue enumeration, forensic silence on mutations). * [**Per-column annotation**](/features/data-discovery/per-column-annotation) — the column-level counterparts to the entity-level annotation surfaces on a dataset's Structure tab — description, tags, glossary terms, enum values, and business name editors per column. Covers the per-sub-editor permissions, the audit-feed events each sub-editor emits, and three operator-visible write-path caveats (a SecurityConstants wiring bug that silently 403s the field-level Add-term button for users with the documented permission, a bulk-replace enum-values endpoint disguised as create-one, and a tags PUT that silently clears every operator-curated tag on empty submission). * [**Manual Object Tagging**](/features/data-discovery/tagging) — apply tags to data entities and columns; the read-side counterpart to the Management → Tags vocabulary curation. Tags drive the Tag facet on Search and the Top tags chip strip on the Catalog Overview. * [**Data Entity Groups & Domains**](/features/data-discovery/groups-domains) — logical containers for related entities, plus the Domain framing that surfaces flagged DEGs on the Catalog Overview's Domains section. Includes the relationship to ML Experiments. * [**Business names**](/features/data-discovery/business-names) — alternative human-readable labels for data entities and dataset fields, surfaced alongside the technical name everywhere the entity is rendered. * [**Data Entity Statuses**](/features/data-discovery/statuses) — `UNASSIGNED` / `DRAFT` / `STABLE` / `DEPRECATED` / `DELETED` lifecycle markers; surface as a Search facet, drive an Activity-feed event, and trigger a soft-delete TTL handled by the housekeeping job. * [**Data Entity Attachments**](/features/data-discovery/attachments) — files (PDFs, CSVs, images) and remote-URL links attached to data entities for additional context. Storage backend operator-configurable; LOCAL is ephemeral. **Specialty cataloguing** * [**Vector Store metadata**](/features/data-discovery/vector-stores) — vector-typed datasets recognised as a first-class catalog primitive (dedicated `Vector Store` dataset type plus `Vector` column data type), surfaced today via the PostgreSQL `pgvector` adapter. **Change and freshness signals** * [**Dataset schema diff**](/features/data-discovery/schema-diff) — visual side-by-side comparison of dataset schema revisions, with backwards-incompatible changes additionally raising an alert. * [**Metadata stale**](/features/data-discovery/metadata-stale) — per-entity orange clock icon flagging entities not re-ingested for longer than `odd.data-entity-stale-period` (default 7 days). A discovery-time freshness prompt; not a runtime alert. ## Why this is a separate pillar For how Data Discovery relates to the other governance pillars (Data Modelling, Master Data Management, Data Lineage, Data Glossary, Data Quality), see [Main Concepts → Data Governance map → Pillar differentiation](/introduction/main-concepts#pillar-differentiation) — the canonical home for the six-pillar framing. ## Where to next * If you know what you're looking for and want to type a term → [Search and Filtering](/features/data-discovery/search). * If you don't know the exact name and want to drill down through known structure → [Directory](/features/data-discovery/directory). * For the surface that every discovery lands on — Overview tab composition, class-driven panels, badges, sidebar truncation, permissions → [Data entity detail page](/features/data-discovery/entity-detail-page). * If you want to label an entity for cross-cutting discovery → [Manual Object Tagging](/features/data-discovery/tagging). * If you want to gather related entities into a logical group or surface a domain on the home page → [Data Entity Groups & Domains](/features/data-discovery/groups-domains). * For the broader catalog vocabulary (Data Entity, Plugin, Push adapter, …) → [Main Concepts](/introduction/main-concepts). * For the position of Data Discovery among the other governance pillars → [Main Concepts → Data Governance map](/introduction/main-concepts#data-governance-map). # Catalog Overview page The catalog's home page — a unified surface combining Search, Directory cards, Top tags, Domains, the per-class Entities report, Recommended quick-jumps, and (when auth on) Owner association. The **Catalog Overview** is the catalog's home page — a single landing surface that combines every Data Discovery entry path the platform offers. A first-time user opening the platform lands here and reaches Search, the Directory's first level, the catalog's most-used tags, the Domains drill-down, a per-class Entities report, and (once they own data) personalised quick-jumps from one screen. The Catalog Overview is the user's first encounter with the catalog and the unified pivot that links every other Data Discovery surface. It does not introduce new functionality of its own — it surfaces the existing pillars in one place. ![Catalog Overview page rendered on a populated deployment — main search, top tags, the per-class Entities report, the source-type Directory, and the Recommended quick-jumps.](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-86818485b1aa72cc98ff548ef25a94244782cb37%2Fcatalog-overview.png?alt=media) ## Sections The page renders the following sections top-to-bottom. Three sections are conditional — Domains appears only when at least one [Data Entity Group](/features/data-discovery/groups-domains) is flagged as a domain; Directory appears only when at least one DataSource has been registered (a fresh deployment hides the band); and Owner association appears only when authentication is enabled and the signed-in user is not yet linked to an Owner. ### Main search Full-text search bar across the catalog. The same Search facets that the [Search and Filtering](/features/data-discovery/search) page exposes are reachable from here — typing a term lands on the Catalog page with the query pre-populated. ### Top tags The most-used tags across the deployment, rendered as one-click filter chips. Selecting a chip pre-filters the catalog to entities carrying that tag. Tag vocabulary is curated under [Management → Tags](/features/management); this surface is read-only. ### Domains *(conditional)* A list of [Data Entity Groups](/features/data-discovery/groups-domains) that have been flagged as domains, rendered as quick-jump tiles. The section appears only when at least one DEG is domain-flagged; on a fresh deployment it is hidden. ### Entities The per-class usage report — one card per [Data Entity class](/introduction/main-concepts) registered on the platform (Datasets, Transformers, Transformer Runs, Quality Tests, Quality Test Runs, Consumers, Inputs, [Groups](/features/data-discovery/groups-domains), Relationships — the list is platform-driven and grows when new classes ship). Each card shows the total number of entities of that class, the number of "unfilled" entities (those with only a title and no metadata, owners, tags, or related terms), and is clickable — clicking runs a pre-filtered search for that class. The Entities card grid is the catalog's coverage-at-a-glance surface: an operator scanning it sees per-class counts and the unfilled fraction, which together signal which classes need stewardship attention. ### Directory *(conditional)* Quick links into the source-system [Directory](/features/data-discovery/directory), grouped by data source type. This surface renders the same level-1 cards the standalone Directory page renders — clicking a card drills directly into level 2. The band appears only when at least one DataSource is registered on the platform. On a fresh deployment with no DataSources, the band is hidden; the standalone [Directory](/features/data-discovery/directory) page remains reachable through navigation but is empty until a DataSource starts producing entities. ### Recommended Personalised quick-jumps for the signed-in user, grouped into four columns. Surfaces recently-ingested owned entities and entities related to them through lineage, helping a returning user pick up where they left off without typing a search. The Recommended panel requires the signed-in user to be linked to an [Owner](/configuration-and-deployment/enable-security/authorization/user-owner-association); without the user-owner association in place, the Recommended panel is empty. On auth-disabled deployments (`auth.type=DISABLED`) the panel is **hidden from the home page entirely** — there is no user-owner identity to filter on, so the entire surface is removed rather than rendered with unfiltered data. The underlying `GET /api/dataentities/popular` REST endpoint that backs the Popular column remains reachable under DISABLED for any caller on the network. The four columns: 1. **My Objects** — the most recently ingested five data entities where the user is mentioned as an owner. 2. **Upstream Dependencies** — data entities that serve as direct origins to those the user owns. 3. **Downstream Dependencies** — entities that are direct targets of those the user owns. 4. **Popular** — the most-viewed data entities across the catalog, ranked by view count alone (highest first). See the caveat below — this ranking is trivially inflatable.

Wizards on Recommended panel

{% hint style="warning" %} **The Popular column ranks by view count alone, and view count is trivially inflatable — treat it as a rough popularity hint, not a trustworthy signal.** The only input to the Popular ranking is each entity's view count, sorted highest-first; there is no weighting by recency, ownership, or any other signal. View count, in turn, is bumped by **+1 every time a detail page is fetched**, with no rate limit, no per-user de-duplication, and no authentication required (one page-open registers one view as of 0.28.0 — releases up to 0.27.x double-counted each open; see [Data entity detail page → view count](/features/data-discovery/entity-detail-page#general-panel-view-count-caveats)). Because the `GET /api/dataentities/popular` endpoint and the detail-page read are both reachable on a deployment with authentication disabled (`auth.type=DISABLED`), a short scripted read loop can push any chosen entity to the top of the Popular column. Do not use the Popular ranking as evidence of real usage in audits or capacity decisions; cross-check against your own access logs. {% endhint %} Each tile carries a freshness indicator — an orange "time" icon signals stale entities (see [Metadata stale](/features/data-discovery/metadata-stale) for the freshness window and how operators tune it) and a per-class icon on the right indicates the entity type. Clicking a tile opens that entity's [detail page](/features/data-discovery/entity-detail-page), defaulting to the Overview tab. All four columns are rendered by a single shared list component, so they share rendering, sort, refetch, and pagination semantics. Each column shows up to five entries; there is no per-column "view more" affordance and no per-column sort or filter. A change that affects column rendering affects all four uniformly. {% hint style="warning" %} **`exclude_from_search` is a full-text-search signal only — it does not hide entities from the Recommended panel or from any other list surface.** The platform's nine list-shape consumers (the Popular column, the By-Owner list, the By-Term list, the DEG-experiment runs view, the entity dimensions surfaces, the entity-detail GET, and the query-suggestions endpoint) all read through a shared SQL helper that filters on soft-delete and hollow flags only — it does **not** apply the `exclude_from_search` predicate. The flag IS honoured on the full-text search path and on the count / statistics aggregates. An operator who toggles `exclude_from_search=true` on a staging or internal entity expecting it removed from the Recommended panel discovers it still appears there (and on By-Owner / By-Term / lineage list surfaces) until a platform-side fix lifts the predicate into the shared helper. Until that ships, treat the flag as a search-engine signal, not a platform-wide hide signal. {% endhint %} This surface is **distinct from the Alerts → My Objects tab**, which is a different feature with the same name (Alerts → My Objects scopes the alert list to the user's owned entities; Recommended → My Objects surfaces recently-ingested owned entities). See [Alerting → Alert views](/features/active-platform-features/alerting#alert-views-all-my-objects-downstream-upstream) for the distinction. ### Owner association *(conditional)* When authentication is enabled and the signed-in user is not yet linked to an [Owner](/configuration-and-deployment/enable-security/authorization/user-owner-association), this surface renders one of three states depending on whether the user has previously submitted a request. Once the user is bound to an Owner, the surface is replaced with the [Recommended](#recommended) panel (the four-column quick-jumps live in the same vertical band). | Branch | Trigger condition | What the user sees | Path forward | | ------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Form** | Signed in, no Owner binding, no prior request. | The Owner-association form with the Owner-name autocomplete and the **Send a request** button (see [User-owner association → For regular users](/configuration-and-deployment/enable-security/authorization/user-owner-association#for-regular-users)). | Submit the form; the request enters the admin-approval flow. | | **Pending** | Request submitted, status `PENDING`. | A "Request is being checked" screen with no cancel affordance — the request is one-shot. | Wait for an admin to approve or decline on Management → Associations → New requests. There is no self-service cancel today; see [User-owner association → Changing or removing your association](/configuration-and-deployment/enable-security/authorization/user-owner-association#changing-or-removing-your-association). | | **Declined** | Most recent request returned `DECLINED`. | A dismissable banner with the declined notice, followed by the request form so the user can submit a new request. | Dismiss the banner and submit a new request; note the banner dismiss is **per-session and not persisted** — see [User-owner association → If your request is declined](/configuration-and-deployment/enable-security/authorization/user-owner-association#if-your-request-is-declined). | | **Approved** | User bound to an Owner. | The four-column Recommended panel takes over the same vertical band — see [Recommended](#recommended) above. | The form is gone; quick-jumps replace it. | Pending Owner-association requests are routed to [Management → Associations](/features/management) for an operator with the `OWNER_ASSOCIATION_MANAGE` permission to approve. On auth-disabled deployments (`auth.type=DISABLED`) the section is hidden (no user identity, nothing to associate). ## Catalog Overview vs entity Overview tab {% hint style="info" %} **Two distinct things share the name "Overview".** The **Catalog Overview** described on this page is the catalog's home page — the unified surface combining Search, Directory, tags, Domains, Entities, Recommended, and the optional Owner association request. The [per-entity **Overview tab**](/features/data-discovery/entity-detail-page) is the landing tab inside any data entity's detail page — entity description, owners, tags, terms, custom metadata. They are different surfaces; do not confuse them when reading docs or filing bug reports. {% endhint %} ## Where to next * [Search and Filtering](/features/data-discovery/search) — the query-driven entry path the Catalog Overview surfaces at the top. * [Directory](/features/data-discovery/directory) — the hierarchy-driven entry path the Catalog Overview surfaces inline (level-1 cards). * [Data entity detail page](/features/data-discovery/entity-detail-page) — the destination of every Recommended tile, every Search result row, and every Directory entity row. * [Manual Object Tagging](/features/data-discovery/tagging) — the source data behind the Top tags chip strip. * [Data Entity Groups & Domains](/features/data-discovery/groups-domains) — the source data behind the Domains section. * [Metadata stale](/features/data-discovery/metadata-stale) — the freshness signal Recommended tiles render via the orange "time" icon. * [User-owner association](/configuration-and-deployment/enable-security/authorization/user-owner-association) — the operator-side configuration the Owner association section + the Recommended panel both depend on. * [Data Discovery overview](/features/data-discovery) — the bucket landing this page sits under. # 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](/features/data-discovery/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](/features/data-discovery/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.](https://3630572601-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGZJ5RdCEQxq16TnRL3Tq%2Fuploads%2Fgit-blob-f39ef315235f8cd527f7d220d3f44a8fe0254426%2Fdirectory.png?alt=media) ## 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) 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) 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) — 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) — the query-oriented counterpart, with seven facets. * [Data entity detail page](/features/data-discovery/entity-detail-page) — what you land on when you click an entity in the level-4 list. * [ODDRN](/introduction/main-concepts#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) — the deployment-side surface for restricting catalog read access in multi-team environments. * [Main Concepts → Data Discovery](/introduction/main-concepts) — where Search and the Directory sit in the broader governance map. # Search and Filtering Search and Filtering — the catalog's query-oriented entry point. Free-text search across entity names plus seven faceted filters. **Search** is the catalog's primary query-oriented entry path — type what you are looking for, and ODD finds entities matching across names, descriptions, and metadata. Where the [Directory](/features/data-discovery/directory) walks the catalog hierarchically, Search is free-text + faceted. With the user-friendly search interface, finding the information you need is easier than ever. Type your search query into the search bar and ODD does the rest. To get started, navigate to the main page of ODD Platform and select the **Catalog** tab. There you will find the **Search bar** and **Filter** options.

Type your search query into the search bar

## Faceted search The platform incorporates **faceted** search capabilities. This means you can refine your search results based on specific attributes, ensuring that you find exactly what you are looking for. The Filters panel on the Catalog page exposes seven facets: * **Datasource** — restrict results to entities ingested from a specific datasource (single-select). * **Type** — restrict results to one or more data entity types (e.g., `TABLE`, `JOB`, `DASHBOARD`; multi-select). Only shown after an entity-class tab is selected at the top of the Catalog (Datasets / Transformers / Data Consumers / Data Inputs / Quality Tests / Groups / Relationships). * **Namespace** — restrict to entities in a given namespace (single-select). Useful in multi-team setups where each team owns its own namespace and wants to see only its own datasets, jobs, and quality tests in one click. * **Owner** — show entities owned by one or more selected owners (multi-select). * **Tag** — show entities carrying one or more selected [tags](/features/data-discovery/tagging) (multi-select). * **Groups** — show entities that are members of one or more selected [Data Entity Groups](/features/data-discovery/groups-domains) (multi-select). Useful for narrowing the search to a logical project, domain, or pipeline group rather than a flat datasource list. * **Statuses** — show entities in one or more selected statuses (multi-select; e.g., `STABLE`, `DEPRECATED`).

Filters

## Result-class tabs Above the result list the Catalog page renders a tab strip — a second filter axis, independent of the Filters sidebar. Selecting a tab narrows the result list to entities of that class (or the personal scope, for `My Objects`) and unlocks the **Type** sidebar facet, which is hidden until a specific class is chosen. The nine tabs, left to right: | Tab | What it scopes to | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | **All** | Every entity matching the query and the active facets, regardless of class. | | **My Objects** | The subset of the above owned by the authenticated user. The personal-namespace tab. | | **Datasets** | Entities of class `SET` (tables, views, files, topics). | | **Transformers** | Entities of class `TRANSFORMER` (jobs, pipelines, dbt models). | | **Data Consumers** | Entities of class `CONSUMER` (microservices, BI dashboards). | | **Data Inputs** | Entities of class `INPUT` (source data feeds). | | **Quality Tests** | Entities of class `QUALITY_TEST` (test definitions; per-run history lives on the [detail page](/features/data-discovery/entity-detail-page)). | | **Groups** | Entities of class `ENTITY_GROUP` (Data Entity Groups, including domain-flagged ones). | | **Relationships** | Entities of class `RELATIONSHIP` (ERD relationship metadata). | The tab counts update with the active query and facet selection. The **Type** facet in the sidebar is class-conditional: it appears only once a specific class tab is selected (because type values are only meaningful within a class). ## Per-result transparency As you type your search and adjust filters, ODD dynamically responds, delivering results in seconds. Each entity in the search results is accompanied by an information and a question icon, offering additional clarity and insight:

The information icon shows you what you see in your search results

The question icon shows you why you see it in your search results

## Technical details The underlying constants used by the search engine are defined in [FTSConstants.java](https://github.com/opendatadiscovery/odd-platform/blob/main/odd-platform-api/src/main/java/org/opendatadiscovery/oddplatform/repository/util/FTSConstants.java). **Step 1.** Metadata ingested into the platform goes through indexing to improve search efficiency. **Step 2.** When you search or apply filters, the search engine processes your inputs by recognizing search terms, applying relevant constraints, and identifying metadata entries closely related to the query. **Step 3.** Next, ODD ranks these matching metadata entries based on a specific criteria and their relevance to your search.

Metadata ranking for search within ODD

## Known limitations and operator caveats The catalog search runtime carries several behaviours that are non-obvious from the UI alone. Each item below states what an operator might assume, what actually happens, and what to do today. ### The `/search/{id}` URL is a server-side session, not a frozen query The address bar on the Catalog page is `/search/{uuid}` once you've typed a query. The UUID is the primary key of a row in the platform's `search_facets` table — a server-side **session** that carries the query string, the facet selections, and the current page state. It is **not** an encoded snapshot of your search and **not** a saved search. Three consequences operators routinely bump into: * **Sharing a `/search/{uuid}` URL with a teammate hands them an interactive cursor, not a snapshot.** When they open the link they reach the same server-side row; if you keep clicking facets, their view drifts with yours. To share a frozen result, send the entity URLs (`/dataentities/{id}`) directly. (Opening a shared link — and reloading the page — loads the session as of 0.28.0; earlier releases had a front-end defect that silently discarded the pasted id and started a fresh empty session.) * **The session UUID is not bound to a user.** Any authenticated caller who has the UUID reaches the row; under `auth.type=DISABLED` the row is reachable anonymously. Treat the URL as you would any other unguarded internal link. * **Clicking the `Catalog` top-nav tab drops the UUID and starts a fresh session.** The "Catalog" link points at bare `/search`, which mints a new server-side row on the next keystroke. There is no "go back to my last search" affordance on the top nav — use the browser back button instead, or re-paste the previous URL. * **The session row is evicted by the housekeeping job.** A session row lives until 30 days after its last access (configurable via [`housekeeping.ttl.search_facets_days`](/configuration-and-deployment/odd-platform#housekeeping-settings-configuration)). Opening an evicted URL shows a "This search has expired" notice with a one-click **Start new search** recovery (as of 0.28.0; earlier releases silently dropped the dead id and opened a fresh empty session). Bookmarking a `/search/{uuid}` URL for long-term reference is still unreliable — for durable references, share entity URLs instead. ### Facet aggregators enumerate cross-owner data by default The Filters sidebar facets — Datasource, Namespace, Owner, Tag, Groups, Statuses, Type — list every value visible to the platform, with per-value counts that span the entire catalog. The Owner facet in particular returns the full Owner directory and per-owner counts to any authenticated caller; under `auth.type=DISABLED` the same lists are reachable anonymously. This is the catalog's **read-collaborative posture**: anyone who can read the catalog can see who owns what, which sources have how many entities, and which tags are most common. If your deployment must avoid exposing the Owner directory or cross-source enumeration to all authenticated users, treat catalog access as a privileged role and do not enable `auth.type=DISABLED` in production. {% hint style="info" %} **`tsquery` operator characters in the search box are treated as word separators.** PostgreSQL full-text search parses the query as a `tsquery`, so characters such as `( ) : & | ! '` are not searchable literals — the search box strips them and matches the remaining words as prefixes. A name like `user(id)` is searched as `user` and `id` (and still matches an entity called `user(id)`); a query made up of only these characters returns **No matches found**. The same handling applies to the Dictionary (term) search box. (As of 0.28.0; in earlier releases these characters were not stripped — such a query failed with HTTP 500 and persisted a broken `/search/{uuid}` session, reproduced on every later read of that URL until the housekeeping job evicted the row.) {% endhint %} ### The Datasource and Namespace dropdowns cap at 100 options The Filters sidebar fetches at most 100 datasources and 100 namespaces for the Datasource and Namespace single-select dropdowns. In a deployment with more than 100 of either, the dropdown silently shows the first 100 the API returned — with no `+N more`, no pagination, and no search-within-dropdown affordance. To filter by a source that does not appear, use the Search bar with a query that pre-narrows the result set (e.g. typing the namespace name as free text), then apply remaining facets. ### `exclude_from_search` is a full-text-search signal only The `exclude_from_search` flag on a data entity does what its name implies — it removes the entity from the platform's full-text search results — but **it does not remove the entity from the catalog's other list surfaces**. The predicate that honours the flag is added only on the full-text-search query paths. The Recommended panel's Popular column, the By-Owner list, the By-Term list, the DEG-experiment runs view, the entity dimensions surfaces, the entity-detail GET, and the query-suggestions endpoint each build their own list query and several of those queries never add the `exclude_from_search` predicate at all. An operator setting the flag on a staging or internal entity should expect it to disappear from search results but still appear on every other list surface in the platform. See the same caveat from the catalog-front-door angle on [Catalog Overview → Recommended](/features/data-discovery/catalog-overview#recommended). ### Clicking a result row records a view — and feeds the Popular ranking Each click on a result row navigates to the entity's [detail page](/features/data-discovery/entity-detail-page), which records a view on the entity's `viewCount` — exactly one per open as of 0.28.0 (releases up to 0.27.x double-counted each open as +2; see [Data entity detail page → view count](/features/data-discovery/entity-detail-page#general-panel-view-count-caveats)). The Catalog Overview's **Popular** and **Recommended** tiles read from the same counter, so routine browsing through search results still biases those rankings toward whatever entities you happened to open from search — every open counts, however you arrive (a search-row click and direct navigation to `/dataentities/{id}` record the same single view). Returning to the results with the browser back button does not add another view. ## Where else search appears Search and filtering are available not only in the Catalog tab, but in **Query examples**, **Master Data**, [**Management**](/features/management), and **Dictionary** tabs as well — each Management sub-tab (Datasources, Owners, Tags, …) has its own list-level filter. The Catalog-level full-text search across data entities is exclusive to the Catalog tab. ## Where to next * [Directory](/features/data-discovery/directory) — the hierarchy-driven counterpart for browsing without typing a query. * [Data entity detail page](/features/data-discovery/entity-detail-page) — the destination of every result-row click; explains the Overview tab composition you land on and the class-driven panel matrix. * [Manual Object Tagging](/features/data-discovery/tagging) — the Tag facet's source data. * [Data Entity Groups & Domains](/features/data-discovery/groups-domains) — the Groups facet's source data. * [Housekeeping Settings Configuration](/configuration-and-deployment/odd-platform#housekeeping-settings-configuration) — the `housekeeping.ttl.search_facets_days` knob that controls how long a `/search/{uuid}` session lives. * [Main Concepts → Data Governance map](/introduction/main-concepts#data-governance-map) — where Data Discovery (Search + Directory) sits among the governance pillars. # Data entity detail page The data entity detail page — composition of the Overview tab, class-driven panel matrix, badges, sidebar list truncation, and per-panel permission map. Where every catalog discovery lands. Clicking a data entity in [Search](/features/data-discovery/search), in the [Directory](/features/data-discovery/directory), in a [Catalog Overview](/features/data-discovery/catalog-overview) tile, in a lineage node, or in the [Activity feed](/features/active-platform-features/activity-feed) lands the user on the same per-entity detail page. The **Overview tab** is the default landing surface — a single composed page showing everything the catalog knows about the entity, with edit affordances gated by per-panel permissions and per-class composition rules. This page is the canonical reference for the detail-page composition itself. For the aspect-level deep dives — authoring the [Markdown description](/features/data-discovery/entity-description), curating [custom metadata](/features/data-discovery/custom-metadata), annotating [individual columns](/features/data-discovery/per-column-annotation) on a dataset's Structure tab, applying [tags](/features/data-discovery/tagging), curating [business names](/features/data-discovery/business-names), wiring [statuses](/features/data-discovery/statuses), attaching [files](/features/data-discovery/attachments), reading the [stale indicator](/features/data-discovery/metadata-stale), and grouping into [Data Entity Groups](/features/data-discovery/groups-domains) — follow the per-aspect pages cross-linked below. ## Overview tab composition The Overview tab renders a two-column grid for every catalogued entity: * **Main column (left)** — class-driven stats, Description, Attachments, Metadata, optional Expectations, optional Metrics. * **Sidebar (right)** — General identity + Owners, optional Data Quality panels, Groups, Tags, Terms. Twelve sub-panels combine on the surface: | Panel | Column | What it shows | Aspect page | | ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Class-driven stats | Main | A class-specific summary block — dataset structure card, transformer source/target list, consumer input list, quality-test datasets, data-input output list, relationship endpoints, or entity-group member set, depending on the entity's class. | [Main Concepts → Data Entity Class](/introduction/main-concepts) | | Description | Main | The entity's human-readable Markdown description, with linked terms inline. | [Entity description](/features/data-discovery/entity-description); [Business Glossary](/features/data-glossary/business-glossary) for the inline term-link surface. | | Attachments | Main | Files and remote-URL attachments uploaded for the entity. | [Data Entity Attachments](/features/data-discovery/attachments) | | Metadata | Main | Custom (operator-curated) and predefined (collector-ingested) metadata fields in one combined list. | [Custom metadata](/features/data-discovery/custom-metadata) | | Expectations | Main (conditional) | Renders only when the entity has quality-test expectations — parameters and linked URLs from the test definition. | [Test Results Import](/features/data-quality/test-results-import) | | Metrics | Main (conditional) | Renders only for datasets — column-level stats and metrics. | — | | General | Sidebar | Namespace, datasource link, source-side timestamps, view count (see the [view count caveats](#general-panel-view-count-caveats) below), ODDRN, and the Owners list. | [Authorization → Owners](/configuration-and-deployment/enable-security/authorization/owners) | | DQ SLA report | Sidebar (conditional) | Renders only for datasets with at least one quality-test report; shows the SLA roll-up. | [Quality Dashboard](/features/data-quality/dashboard) | | DQ test report | Sidebar (conditional) | Renders alongside the SLA report; shows the latest passed / failed / aborted totals. | [Quality Dashboard](/features/data-quality/dashboard) | | Groups | Sidebar | Data entity groups this entity belongs to. | [Data Entity Groups & Domains](/features/data-discovery/groups-domains) | | Tags | Sidebar | Tags applied to the entity. | [Manual Object Tagging](/features/data-discovery/tagging) | | Terms | Sidebar | Linked business-glossary terms. | [Business Glossary](/features/data-glossary/business-glossary) | The page header above the tabs shows the entity name, the class badges, the type badge, the [stale indicator](/features/data-discovery/metadata-stale), the [status](/features/data-discovery/statuses), and (where applicable) the "Edit business name" / "Edit group" / "Share" buttons. Header affordances follow the same per-class and per-permission rules as the Overview composition; see [Class and type badges](#class-and-type-badges) below. Below the Overview tab, additional class-driven tabs appear — **Structure** (datasets only; see [Per-column annotation](/features/data-discovery/per-column-annotation) for the column-level composer that lives on this tab), **Lineage** (most classes; see [Data Lineage](/features/data-lineage)), **Test reports** and **History** (quality tests, transformer runs), **Linked entities** (per-class linkage), **Discussions** (when [Data Collaboration](/features/active-platform-features/data-collaboration) is enabled), and **Activity** (the [per-entity Activity feed](/features/active-platform-features/activity-feed) audit trail). Which tabs appear depends on the entity's class set; the next section names the mapping. ### General panel — view count caveats The General panel's **view count** is the running total of times this entity's detail page has been fetched. One version note and one caveat are worth knowing before you read or rely on the number. {% hint style="info" %} **One page-open registers one view as of 0.28.0 — releases up to 0.27.x counted +2.** In earlier releases each page-open fetched the entity detail twice (a front-end double-fetch), so a single visit added **2** to the number. From 0.28.0 a visit adds exactly 1. Counts accumulated on earlier releases overstate real visits by roughly a factor of two, and the counter is not rebased on upgrade — treat pre-0.28.0 numbers as a relative popularity hint, not an exact visit tally. {% endhint %} {% hint style="warning" %} **View count is the sole signal behind the home-page Popular ranking, and it is trivially inflatable.** The [Catalog Overview → Popular column](/features/data-discovery/catalog-overview#recommended) ranks entities by view count alone, highest first. View count is bumped on every detail-page fetch with no rate limit, no per-user de-duplication, and no authentication required, and on a deployment with authentication disabled (`auth.type=DISABLED`) both the detail-page read and the `GET /api/dataentities/popular` endpoint are reachable by any caller on the network. A short scripted read loop can therefore push any chosen entity to the top of the Popular column. Do not treat the view count or the Popular ranking as trustworthy usage evidence in audits or capacity decisions; cross-check against your own access logs. {% endhint %} ## Per-class panel matrix The set of panels and tabs visible on a detail page depends on the entity's **class** — the categorical taxonomy that drives every composition decision. A single entity can carry multiple classes (e.g. an ML training pipeline that is both `TRANSFORMER` and `ENTITY_GROUP`); each class contributes its own panels. | Class | Main-column stats panel | Tabs beyond Overview | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `SET` (Dataset) | Dataset structure card — column count, row count, source-side schema link. | Structure, Lineage, Test reports, History (when test runs exist), Linked entities, Discussions, Activity. | | `TRANSFORMER` (Job / Pipeline) | Sources and targets list, with unknown-source / unknown-target counts surfaced separately. | Lineage, History, Linked entities, Discussions, Activity. | | `TRANSFORMER_RUN` (Job run) | No main-column stats panel renders today — the parent transformer's panel does not propagate to its runs. Per-run details live in History. | Lineage, History (own row), Linked entities, Discussions, Activity. | | `CONSUMER` (Microservice / BI tool) | Input list and unknown-input count. | Lineage, Linked entities, Discussions, Activity. | | `INPUT` (Source data feed) | Output list and unknown-output count. | Lineage, Linked entities, Discussions, Activity. | | `QUALITY_TEST` | Suite name, suite URL, tested datasets, test parameters. | Test reports, History, Linked entities, Discussions, Activity. | | `QUALITY_TEST_RUN` | No main-column stats panel renders today — the parent quality test's panel does not propagate to its runs. Per-run reports live in History. | History, Linked entities, Discussions, Activity. | | `ENTITY_GROUP` (DEG) | Member list and the entity-group authoring affordances. | Group Lineage, Linked entities, Discussions, Activity. | | `RELATIONSHIP` (ERD) | Source / target endpoints, cardinality, and join semantics. | Linked entities, Discussions, Activity. | For the canonical class taxonomy and how collectors assign classes during ingestion, see [Main Concepts → Data Entity Class](/introduction/main-concepts). {% hint style="warning" %} **An entity may render no main-column stats panel — silently — for two distinct reasons.** First, if the entity's class array is empty, undefined, or contains a value the UI does not recognise. Second, if the entity is one of the **run** classes (`TRANSFORMER_RUN` or `QUALITY_TEST_RUN`) — both are recognised enum values but the panel switch has no case for them, so they fall through to the default no-render branch. In either case the rest of the Overview (Description, Attachments, Metadata, sidebar panels) still loads, but the class-specific summary block is absent with no visible placeholder. When an Overview is missing its expected stats panel, first check the per-class matrix above (run-classes are expected to be empty here); if the class is none of the run-classes, check the entity's class assignment at the collector — that is the most likely cause. {% endhint %} {% hint style="warning" %} **The right-column Data Quality section is hidden when a dataset has zero test reports — and when the report is still loading.** The DQ panels appear only when the entity is a dataset AND its test-report total is non-zero. A dataset with no quality tests configured renders no DQ section. A dataset whose test-report fetch is still in flight also renders no DQ section. Both states produce the same empty space in the sidebar; the only way to tell them apart today is to wait and re-check, or to inspect the network tab. Treat sidebar DQ absence as "no tests **or** still loading" rather than as a confirmed "this dataset has no quality coverage" signal. {% endhint %} ## Class and type badges The detail-page header renders the entity's class taxonomy as a row of badges next to the name: * **Class badges** — one chip per entry in the entity's class array. Each chip is colour-coded per class (palette resolved from the platform's UI theme — the colour identifies the class at a glance once you've learned the mapping). Hovering a badge surfaces the canonical class label (the short label is on the chip; the longer "normal" label is in the tooltip). * **Type badge** — one chip immediately to the right of the class badges, showing the entity's specific type (`TABLE`, `VIEW`, `JOB`, `DASHBOARD`, `ML_MODEL_TRAINING`, etc.). The type label is the formatter-stripped underscore-free upper-case form of the underlying enum value. {% hint style="info" %} **Class is the load-bearing taxonomy; type is descriptive.** The class array drives every per-class composition decision on the page — which stats panel renders, which tabs are visible, whether the DQ sidebar appears. The type is a finer-grained descriptive label collectors set alongside the class; it does not gate UI surfaces today. {% endhint %} A few operator-visible behaviours of the badge row to be aware of: * **No tooltip explains per-class consequences.** A badge names the class (e.g. `Dataset`, `Transformer`) but does not say "this class is why you see a Structure tab" or "this class is why this entity has source/target panels." The mapping is in [Per-class panel matrix](#per-class-panel-matrix) above; the header surface does not surface it directly. * **The type badge is not colour-coded.** Class badges use per-class colours; the type badge uses a uniform background regardless of type. A dense list (search results, directory list) is therefore class-coloured but type-uniform — operators scanning a list distinguish entities by class colour at a glance, by type only after reading the label. * **An entity with no recognised class renders no class badge — silently.** Combined with the matching stats-panel absence noted above, an unclassified entity is structurally indistinguishable from an entity whose class payload was lost in transit. If the badge row shows only a type badge and no class chips, treat the entity as ingestion-incomplete and check the collector. * **Multi-class entities overflow horizontally.** The badge row uses no-wrap layout, so an entity carrying four or more classes overflows the horizontal allocation rather than wrapping to a second line. In practice multi-class entities are uncommon; an ML model that is both `ENTITY_GROUP` and `TRANSFORMER` is the canonical case. The "Edit business name" button shares the same row, so heavy class overflow can compress the visible name. * **The `DCT` type is a deliberate special case.** The type-name slot accepts the standard collector enum plus the literal string `'DCT'` — the dbt-cloud type, surfaced on the badge alongside the collector-side enum. If you see a `DCT` type on a `TRANSFORMER`-class entity, that is the [`odd-dbt`](/integrations/integrations/odd-dbt) push-adapter ingestion chain. ## Sidebar list truncation (Tags / Terms / Groups) The sidebar's **Tags**, **Terms**, and **Groups** panels cap visible items to keep the surface from stretching vertically. The cap is panel-specific and a `View All (N)` toggle expands the full list inline: | Panel | Initial visible | Toggle | | ---------- | -------------------------- | ----------------------------------------------------------------- | | **Tags** | First 20 tags | `View All (N)` button at the panel foot when the list exceeds 20. | | **Terms** | First 20 linked terms | Same. | | **Groups** | First 10 group memberships | Same. | When a panel is truncated it shows an inline **`Showing 20 of N`** hint above the list (alongside the `View All (N)` toggle's count), so the truncation is visible at a glance without clicking. An entity with 20 or fewer tags shows neither the hint nor the toggle. {% hint style="info" %} **Tags are importance-ordered across the truncation cap.** The Tags panel sorts the **whole** tag set by importance (important tags first), then alphabetically, and *then* takes the visible window — so an entity's important tags appear in the first 20 even when it carries many more, and `View All` continues the same single ordering. The same importance ordering applies to the tag lists on the term detail page and on a dataset field. {% endhint %} {% hint style="info" %} **The Groups and Terms panels show the server's order.** These panels carry no importance signal, so the visible window (10 for Groups, 20 for Terms) and the expanded list render in the order the platform returns them. Do not rely on this order being alphabetical. {% endhint %} ## Permissions surface Every editable panel on the Overview tab evaluates its own permission set locally. The detail page does not declare a single "what can I edit on this entity?" permission map — each panel is gated independently. | Panel | Permissions evaluated for edit affordance | | ----------------- | ------------------------------------------------------------ | | Description | `DATA_ENTITY_DESCRIPTION_UPDATE` | | Attachments | `DATA_ENTITY_ATTACHMENT_MANAGE` | | Metadata (custom) | `DATA_ENTITY_CUSTOM_METADATA_CREATE`, `…_UPDATE`, `…_DELETE` | | General — Owners | `DATA_ENTITY_OWNERSHIP_CREATE`, `…_UPDATE`, `…_DELETE` | | Groups | `DATA_ENTITY_ADD_TO_GROUP`, `DATA_ENTITY_DELETE_FROM_GROUP` | | Tags | `DATA_ENTITY_TAGS_UPDATE` | | Terms | `DATA_ENTITY_ADD_TERM`, `DATA_ENTITY_DELETE_TERM` | The page header carries its own per-affordance permission gates: | Header affordance | Permission | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | | Business name (Add / Edit) | `DATA_ENTITY_INTERNAL_NAME_UPDATE` | | [Status](/features/data-discovery/statuses) change | `DATA_ENTITY_STATUS_UPDATE` | | [Data Entity Group](/features/data-discovery/groups-domains) edit (manually-created groups only) | `DATA_ENTITY_GROUP_UPDATE` | | [Share to Slack](/features/active-platform-features/data-collaboration) | No separate permission — gated only by the `DATA_COLLABORATION` feature toggle. | When auditing "what does role X see on this entity," cross-reference each row of the two tables above against the role's permissions via [Permissions](/configuration-and-deployment/enable-security/authorization/permissions). The detail page does not surface the role-to-affordance map in the UI; the audit lives in the role definitions. When the entity's [status](/features/data-discovery/statuses) is `DELETED`, several Overview-tab and header edit affordances are hidden regardless of the operator's permissions — soft-deleted entities are read-only in the UI until the status is reverted. See [Data Entity Statuses → DELETED-state read-only surface](/features/data-discovery/statuses) for the per-affordance breakdown. ## Where to next * [Catalog Overview page](/features/data-discovery/catalog-overview), [Search](/features/data-discovery/search), [Directory](/features/data-discovery/directory) — the three discovery entry paths that land an operator on this page. * [Entity description](/features/data-discovery/entity-description), [Custom metadata](/features/data-discovery/custom-metadata), [Per-column annotation](/features/data-discovery/per-column-annotation), [Manual Object Tagging](/features/data-discovery/tagging), [Business names](/features/data-discovery/business-names), [Data Entity Statuses](/features/data-discovery/statuses), [Data Entity Groups & Domains](/features/data-discovery/groups-domains), [Data Entity Attachments](/features/data-discovery/attachments), [Metadata stale](/features/data-discovery/metadata-stale) — per-aspect deep dives for the panels and header affordances on this page. * [Data Lineage](/features/data-lineage) — the Lineage tab on every entity detail page (class-dependent visibility). * [Activity Feed](/features/active-platform-features/activity-feed) — the per-entity Activity tab; the audit trail for every change applied through this surface. * [Main Concepts → Data Entity Class](/introduction/main-concepts) — the canonical class taxonomy whose enum values drive every per-class composition decision above. * [Permissions](/configuration-and-deployment/enable-security/authorization/permissions) — the role-definition surface where the per-affordance permissions on this page resolve. * [Data Discovery overview](/features/data-discovery) — the bucket landing this page sits under. # Entity description Operator-authored Markdown description on each data entity — the platform's primary free-text annotation, persisted verbatim and rendered through the same component as terms and columns. Every data entity in the catalog carries an **operator-authored description** — free-form Markdown that documents what the entity is for, who reads from it, what the columns mean, and any in-house context that the source system does not carry. The description appears on the entity's detail page as the primary narrative surface above the structural panels (schema, lineage, tags, terms), and it surfaces in search-result rows and the Recommended-tile previews as the first-encounter snippet. This page covers the authoring workflow, the supported Markdown surface, the permissions that gate editing, the audit trail, and a load-bearing security caveat that applies to **six** of the platform's free-text Markdown surfaces. ## Where to find it Open any data entity's detail page → **Overview** tab. The description occupies the top of the Overview body. Operators with the [`DATA_ENTITY_DESCRIPTION_UPDATE`](/configuration-and-deployment/enable-security/authorization/permissions) permission see an **Edit** affordance; readers without the permission see the rendered description and nothing else. The same description text is also surfaced as the **preview snippet** on: * [Search](/features/data-discovery/search) result rows. * The Recommended-tile cards on the [Catalog Overview](/features/data-discovery/catalog-overview) home page. * The [Directory](/features/data-discovery/directory)'s level-4 entity list rows. The full Markdown rendering happens on the Overview tab; the preview surfaces above render an abbreviated plain-text projection. ## Authoring the description The Edit affordance opens an inline Markdown editor (`@uiw/react-md-editor`) with split-pane preview. Operators type the description in Markdown; saving issues `PUT /api/dataentities/{id}/description` with a JSON body carrying the new description string. The platform persists the text **verbatim** into the `data_entity.internal_description` column (PostgreSQL `text`, no length cap, no transformation other than mapping the empty string to `null`). Supported Markdown surface — what the renderer understands and the editor previews: * Headings (`#`, `##`, `###`, …). * Bold, italic, strikethrough. * Inline and fenced code blocks (syntax highlighting on the fenced form via the renderer's highlighter). * Bulleted and numbered lists, including nested lists. * Links — `[text](https://...)` plus the auto-link convention `[[Namespace:Term]]` that resolves to a glossary term (see [Manual Object Tagging](/features/data-discovery/tagging) and the [Business Glossary](/features/data-glossary/business-glossary) for the term-linking workflow). * Tables (GitHub-flavored). * Raw HTML — the renderer parses embedded HTML (`rehype-raw`); as of 0.28.0 it then sanitises the parsed HTML (`rehype-sanitize`) before display, stripping scripts and event-handler / `javascript:` vectors. See the security caveat below. The editor is the only place to author the description; there is no API-only path that bypasses the editor's preview. Third-party API clients calling `PUT /api/dataentities/{id}/description` directly write the same field — the stored value is verbatim either way (HTML sanitisation happens at render time, not on write). ## Permissions Editing the description is gated by **one** permission: | Permission | What it gates | | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | [`DATA_ENTITY_DESCRIPTION_UPDATE`](/configuration-and-deployment/enable-security/authorization/permissions) | The Edit affordance on the Overview tab plus the `PUT /api/dataentities/{id}/description` endpoint. | The permission is bound to the data entity in the URL (per the platform's RBAC model — see [Permissions](/configuration-and-deployment/enable-security/authorization/permissions) for the full per-resource gating story). Operators without it see the rendered description but no Edit affordance. ## Activity trail Description edits emit a `DESCRIPTION_UPDATED` event on the [Activity Feed](/features/active-platform-features/activity-feed). The event carries the entity id, the editor's identity, and the timestamp — and, in its old-state / new-state payload, the **full previous description and the full new description**. The Activity Feed is therefore a content-diff log for description edits, not merely an audit-of-occurrence: the per-entity Activity tab on the detail page reconstructs both *that* a description changed and *what* it changed from and to. ## Security caveat — stored-XSS family across six Markdown surfaces The platform's description-authoring surfaces apply **no write-time HTML sanitisation** — operator-typed Markdown is persisted verbatim. Rendering is the defence point: as of **0.28.0** the platform's shared Markdown renderer sanitises parsed HTML (`rehype-raw` → `rehype-sanitize`) before display, so `