> For the complete documentation index, see [llms.txt](https://docs.telm.ai/telmai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telm.ai/telmai/integrations/catalog-integration/databricks-unity-catalog.md). # Databricks Unity Catalog Read Databricks Unity Catalog metadata into Telmai for dataset discovery and monitor recommendations Telmai reads metadata from [Databricks Unity Catalog](https://docs.databricks.com/data-governance/unity-catalog/index.html) for dataset discovery, column schema, owners, and one-click monitoring of a workspace's tables. Unlike a metadata aggregator that spans many databases, Unity Catalog is the Databricks lakehouse's own governance layer. That shapes how the integration behaves: **one integration represents one workspace**, and a single Databricks connection serves every dataset discovered in it. {% hint style="info" %} This integration applies to Telmai **Databricks** data connections. To bring catalog metadata to assets from other connection types, use the [Actian Data Intelligence](/telmai/integrations/catalog-integration/zeenea.md) integration. {% endhint %} ## What Telmai reads | Metadata | How Telmai uses it | | ----------------------------- | ------------------------------------------------------------------------------------------- | | Catalogs, schemas, tables | Dataset discovery — populates the Catalog Browser | | Full column schema | Informs monitor recommendations and asset configuration | | Primary and foreign key flags | Read from `table_constraints`; informs uniqueness and relationship rules | | Table owner | Recorded as the dataset's steward | | Usage and popularity | 30-day read counts, normalized into a usage score that helps prioritize which tables matter | | Catalog Explorer links | Deep links back to the table in Databricks | By default Telmai harvests `MANAGED_CATALOG` and `FOREIGN_CATALOG` catalogs. Databricks system and internal catalogs, and `information_schema`, are excluded. ### Not yet available | Capability | Status | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lineage | Coming soon | | Tags, glossary terms, sensitivity labels | Not read from Unity Catalog. Critical data element tiers come from Telmai's AI classifier instead | | Data products | Not supported | | Writing data quality results back | Not supported. Write-back is available with [Actian Data Intelligence](/telmai/integrations/catalog-integration/zeenea.md#writing-results-back-to-actian-data-intelligence) | *** ## Step 1: Create a personal access token in Databricks Telmai authenticates to your Databricks workspace with a personal access token (PAT). 1. In your Databricks workspace, go to **Settings > Developer > Access tokens**. 2. Select **Generate new token**, give it a descriptive comment (for example, `telmai-catalog`), and set a lifetime. 3. Copy the token. Databricks displays it once. ### Required privileges The identity behind the token needs Unity Catalog read access — **`USE CATALOG`** on each catalog you want Telmai to read. ```sql GRANT USE CATALOG ON CATALOG TO ``; ``` {% hint style="warning" %} Without `USE CATALOG`, the catalog and everything beneath it is invisible to Telmai — the sync completes successfully but discovers no datasets. {% endhint %} Usage and popularity scores are collected by querying Databricks system tables through a SQL warehouse. If the token cannot reach a SQL warehouse, discovery still works and usage scores are simply absent. *** ## Step 2: Connect to Unity Catalog In Telmai, go to **Administration** and select **Catalog** from the left menu. | Field | Description | | --------------------- | ---------------------------------------------------------------------------------------------- | | Catalog Type | Select **Databricks Unity Catalog** | | Workspace URL | Your Databricks workspace URL, for example `https://adb-xxxx.azuredatabricks.net` | | Personal Access Token | The PAT created in Step 1. Leave blank when updating other fields to keep existing credentials | | Sync Interval (hours) | How often Telmai syncs metadata. Accepts values between 1 and 168 hours | Select **Save Changes**. Creating the integration runs a connection test and triggers an immediate first sync. **Sync Now** triggers a sync at any time thereafter. {% hint style="info" %} The integration name also labels the source row in the Catalog Browser, so give it a name that reads well there — for example, `Databricks Dev Workspace`. {% endhint %} {% hint style="warning" %} Only one catalog can be connected at a time. Remove the existing connection before connecting a different catalog. {% endhint %} ### Advanced Settings Advanced Settings are optional key/value settings that fine-tune how Telmai syncs your Unity Catalog integration. All of them have sensible defaults — for a typical setup, leave them empty. Use **+ Add Setting** to add one. | Property | Default | Description | | --------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `catalogs-include` | (empty — all catalogs) | Comma-separated list of catalog names to sync. When set, only these catalogs are harvested. Useful for limiting large workspaces to the catalogs you actually monitor. | | `catalogs-exclude` | (empty) | Comma-separated list of catalog names to skip. Applied after `catalogs-include`. | | `catalog-types` | `MANAGED_CATALOG,FOREIGN_CATALOG` | Which Unity Catalog catalog types are synced. By default, Databricks-managed system and internal catalogs are excluded. Set a blank value to disable type filtering entirely. | | `source-name` | (integration name) | Overrides the source label shown in Catalog Browser. By default, the integration's name is used. | | `usage-warehouse-id` | (picked automatically) | ID of the SQL warehouse Telmai uses to query Databricks system tables for usage (popularity) scores. By default, Telmai reuses the warehouse it detects for connection setup. Set this when your workspace has several warehouses and you want sync queries to run on a dedicated one, instead of waking or competing with the warehouse used for data scans. | | `usage-refresh-hours` | `0` (refresh on every sync) | Minimum number of hours between usage-score refreshes. Raise this (for example, to `24`) to reduce SQL warehouse wake-ups on cost-sensitive workspaces. | *** ## Step 3: Catalog Browser **Catalog Browser** is available in the sidebar under **Configure**. It is where you browse catalog-discovered datasets and manage which tables are connected for monitoring. ### Catalog Connections A Unity Catalog integration appears as **exactly one source** — the whole workspace. Datasets from every catalog and schema in that workspace live under it. * **Connected** — the source is linked to a Telmai Databricks connection. That one connection serves every dataset in the workspace. * **Not Connected** — the source has not yet been linked. ### Connecting the source Select **Connect** on the source to open a new Databricks connection form. Telmai prefills almost all of it from the workspace — host, port, catalog usage, and the HTTP path looked up live from the workspace's SQL warehouses. In most cases the only value you type is the Databricks token. {% hint style="info" %} Linking the source connects every dataset in the workspace in one action, and datasets discovered by later syncs are linked to the same connection automatically. The catalog and schema are recorded per asset, so a single connection covers them all. If the token could not read the workspace's SQL warehouses, the HTTP path is not prefilled — enter it manually. {% endhint %} ### All Sources The right panel shows all tables discovered from Unity Catalog, grouped into two sections: * **Connected tables** — already linked to Telmai assets * **Non connected tables** — discovered from the catalog but not yet monitored in Telmai Each table shows the following columns: | Column | Description | | -------------------- | ----------------------------------------------------------------------- | | Score | Current data quality score for the table | | Details | Number of columns | | Last changed | When the table was last updated in the catalog | | Why it's recommended | AI-generated explanation of why Telmai recommends monitoring this table | *** ## Intelligent Recommendations Telmai uses Unity Catalog metadata to prioritize which tables most need monitoring. The **Why it's recommended** column surfaces this reasoning for each table, drawing on: * Column schema and key constraints * Usage and popularity — how heavily the table has been read over the last 30 days * Ownership completeness * Critical data element tiers assigned by Telmai's AI classifier Select any table to open its **Catalog Details**, which shows the dataset's catalog metadata, the full AI recommendation with its reasoning and priority, connection status, and suggested timestamp columns. See [Monitor Recommendations](/telmai/monitoring-data/monitors-management/monitor-recommendations.md) for how recommended rules are reviewed and added. *** Metadata syncs on the interval configured in **Administration > Catalog**. Use **Sync Now** to trigger an immediate sync at any time. ## Related pages * [Catalog Integration](/telmai/integrations/catalog-integration.md) * [Actian Data Intelligence](/telmai/integrations/catalog-integration/zeenea.md) * [Databricks connector](/telmai/connect-to-data/data-connections/databricks.md) * [Monitor Recommendations](/telmai/monitoring-data/monitors-management/monitor-recommendations.md)