Discovery & health

Discover catalogs, schemas, tables, warehouses, clusters, and jobs from chat, and validate your Databricks source with live health tests.

Fabric Agents can automatically discover Databricks resources and run an enhanced health check against your workspace. Both use the credentials of your configured Databricks source.

Discovery tools

Nine session tools are available to the agent whenever a Databricks source is configured. All are read-only and allowed in Safe/Explore mode:

Tool	Databricks API	Returns
`databricks_discover_catalogs`	`GET /api/2.1/unity-catalog/catalogs`	Unity Catalog catalogs
`databricks_discover_schemas`	`GET /api/2.1/unity-catalog/schemas`	Schemas in a catalog
`databricks_discover_tables`	`GET /api/2.1/unity-catalog/tables`	Tables in a schema
`databricks_discover_warehouses`	`GET /api/2.0/sql/warehouses`	SQL warehouses
`databricks_discover_clusters`	`GET /api/2.1/clusters/list`	Clusters
`databricks_discover_jobs`	`GET /api/2.1/jobs/list`	Jobs
`databricks_discover_genie_spaces`	`GET /api/2.0/genie/spaces`	Genie spaces (empty if Genie is unavailable)
`databricks_discover_vector_indexes`	`GET /api/2.0/vector-search/indexes`	Vector Search indexes (empty if unavailable)
`databricks_discover_pipelines`	`GET /api/2.1/pipelines`	Lakeflow (DLT) pipelines

List endpoints follow next_page_token pagination automatically (up to 10 pages), so large workspaces are no longer truncated to the first page. Every request carries a User-Agent: fabric-agents/<version> header, so agent traffic is identifiable in Databricks audit logs, and all requests are host-validated, HTTPS-only, and never follow redirects.

Consumption reporting

A tenth tool, databricks_consumption_report, aggregates per-source cost, DBU, and token usage captured from Databricks API responses during the current app run — optionally including data-lineage events extracted from SQL statements the agent executed. Figures are best-effort attribution held in memory, not billing data; for authoritative costs, query system.billing.usage (see Platform services).

Example prompts

Ask the agent naturally — it maps your request to the appropriate tool:

Prompt	What it does
"List catalogs"	Calls `GET /api/2.1/unity-catalog/catalogs`
"Show tables in main.default"	Calls `GET /api/2.1/unity-catalog/tables?catalog_name=main&schema_name=default`
"List SQL warehouses"	Calls `GET /api/2.0/sql/warehouses`
"Show clusters"	Calls `GET /api/2.1/clusters/list`
"List jobs"	Calls `GET /api/2.1/jobs/list`

Discovery permissions

Resource	Minimum privilege	Why
Catalogs	`BROWSE` + `USE CATALOG`	Required to list and access catalogs
Schemas	`USE SCHEMA`	Required to list schemas within a catalog
Tables	`BROWSE` (list) / `SELECT` (read)	`BROWSE` for discovery; `SELECT` for data
Clusters	`CAN VIEW`	Required to list clusters
Jobs	`CAN VIEW`	Required to list jobs
SQL Warehouses	`CAN USE`	Required to list and query warehouses

Scaffold enrichment

Discovery also powers project scaffolding: when you run databricks init through the chat agent with a connected source, the handler discovers your first running warehouse, default catalog and schema, and first Genie space, then pre-fills the scaffolded project's .env.example with those non-secret IDs. See Harness bridge.

Live health tests

source test performs a live validation of your Databricks source in three stages:

Authentication — probes GET /api/2.0/preview/scim/v2/Me to verify the PAT or OAuth token is valid.
Unity Catalog reachability — lists catalogs to confirm BROWSE + USE CATALOG grants are present.
Compute visibility — lists SQL warehouses and clusters to confirm workspace permissions.

The result includes per-endpoint status lines and discovered resource counts (e.g. Connected. Found 4 catalogs, 2 warehouses, 3 clusters).

Running the test

fabric-cli source test databricks-pat
# or
fabric-cli source test databricks-oauth
# or
fabric-cli source test databricks-oauth-u2m

Interpreting results

Result	Meaning
`connected`	All checks passed. The source is ready for discovery and queries.
`error`	Authentication failed (401). Check credentials — regenerate the PAT or re-run the OAuth flow.
`disconnected`	The workspace is unreachable or endpoints returned server errors. Check the URL and network.
Warnings (`⚠`) on individual endpoints	Auth works but a specific API is unavailable or blocked. Verify the corresponding grants (e.g. `BROWSE` + `USE CATALOG` for Unity Catalog).

Authentication — PAT, M2M, and U2M setup
Harness bridge — scaffolding and deploy
Unity Catalog API docs

On this page