> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks Toolkit

> Query Unity Catalog tables, run warehouse SQL, inspect lineage and notebooks with a Databricks PAT or service principal

The **Databricks** toolkit lets agents browse Unity Catalog (catalogs, schemas, tables), run SQL on a warehouse, fetch statement results, list warehouses and workspace objects, export notebooks, inspect table lineage, and review query history. Authentication uses a saved connection with either a **personal access token (PAT)** or an **OAuth M2M service principal** (client ID + secret).

Add it on the agent **Toolkits** tab and create or select a Databricks connection.

## Prerequisites

* A Databricks workspace and SQL warehouse the agent should use
* Either a PAT, or a service principal client ID and secret, with access to the catalogs and warehouses you need
* An agent you can edit

## Setup

1. Open the agent → **Toolkits** → add **Databricks**.
2. Create a connection with:
   * **Workspace host** (required) — for example `https://dbc-xxxx.cloud.databricks.com`
   * **SQL warehouse ID** (required)
   * **Either** a **personal access token**, **or** **client ID** + **client secret** for a service principal
3. Save the agent. `@`-mention Databricks tools in the personality prompt for catalog and SQL tasks.

## Available tools

### Unity Catalog & SQL

| Tool                     | Description                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **List Catalogs**        | Lists Unity Catalog catalogs (paginated).                                                                  |
| **List Schemas**         | Lists schemas in a catalog.                                                                                |
| **List Tables**          | Lists tables in a `catalog.schema`.                                                                        |
| **Get Table**            | Returns table metadata and column schema.                                                                  |
| **Run SQL**              | Runs SQL on the configured warehouse. Read-only by default unless writes are explicitly allowed in config. |
| **Get Statement Result** | Fetches or polls statement result chunks.                                                                  |
| **List Warehouses**      | Lists SQL warehouses.                                                                                      |
| **Query History**        | Lists recent SQL queries.                                                                                  |
| **Get Table Lineage**    | Returns upstream/downstream table lineage.                                                                 |

### Workspace & API

| Tool                       | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| **List Workspace Objects** | Lists notebooks and folders (bounded recursion).             |
| **Export Notebook**        | Exports notebook source.                                     |
| **Custom API Call**        | Calls a Databricks workspace REST endpoint on the same host. |

## Use cases

* Discover catalogs and table schemas before writing a query
* Run analytical SQL and summarize results in chat
* Inspect lineage for a table before changing a pipeline
* Export a notebook for review or troubleshooting

## Tips

* Access is limited to what the **PAT or service principal** can see (Unity Catalog grants and warehouse permissions).
* Notebook access can differ from UC table grants — exporting a notebook needs workspace ACLs (`CAN_READ` or higher).
* Prefer bounded SQL (`LIMIT`, filters) for interactive exploration.
* Store tokens and secrets in a saved connection — do not put them in the personality prompt.

## Troubleshooting

| Symptom                       | What to check                                                             |
| ----------------------------- | ------------------------------------------------------------------------- |
| Auth failed                   | Host URL, token or client credentials, and warehouse ID                   |
| Table or catalog not found    | UC grants for the identity; correct `catalog.schema` names                |
| SQL permission / write errors | Warehouse access; writes may be disabled unless `allow_writes` is enabled |
| Notebook export fails         | Workspace path and `CAN_READ` (or higher) on the notebook                 |
| Empty warehouse list          | Identity lacks warehouse permissions in the workspace                     |

## Related

* [Database](/agents/toolkits/database)
* [Airtable](/agents/toolkits/airtable)
* [Toolkits overview](/agents/toolkits/overview)