# Databricks

> Manage Databricks clusters, jobs, SQL warehouses, SQL statements and Unity Catalog with a personal access token.

Lets an agent operate a Databricks workspace through the REST API: list clusters and jobs, trigger a job run and check its status, list SQL warehouses, run SQL statements through the Statement Execution API, and browse Unity Catalog catalogs and schemas.

## What it can do

| Method | What it does |
| --- | --- |
| `databricks_clusters_list` | List all clusters with state, node type, and Spark version. |
| `databricks_jobs_list` | List jobs (optional limit, offset, name filter). |
| `databricks_job_run_now` | Trigger a job run immediately, returning a run_id. |
| `databricks_run_get` | Get the status and output of a job run. |
| `databricks_warehouses_list` | List SQL warehouses with state and size. |
| `databricks_sql_statement` | Execute a SQL statement on a warehouse and return columns/rows. |
| `databricks_catalogs_list` | List Unity Catalog catalogs. |
| `databricks_schemas_list` | List schemas inside a catalog. |
| `databricks_request` | Generic passthrough to any REST endpoint for full API coverage. |

## How to get your token

Databricks authenticates API calls with a **personal access token (PAT)** sent as a Bearer token.

1. Open your Databricks workspace.
2. Click your avatar -> **Settings** -> **Developer** -> **Access tokens** ([PAT docs](https://docs.databricks.com/aws/en/dev-tools/auth/pat)).
3. Click **Generate new token**, optionally set a comment and lifetime, and copy the token - it is shown only once.
4. Note your **workspace URL** from the address bar, e.g. `https://dbc-xxxxxxxx.cloud.databricks.com` (no trailing `/api`).

## Fields to fill

| FlyMyAI field | Where it comes from |
| --- | --- |
| `DATABRICKS_HOST` | Your workspace URL, e.g. `https://dbc-xxxxxxxx.cloud.databricks.com` |
| `DATABRICKS_TOKEN` | Settings -> Developer -> Access tokens -> Generate new token (kept private) |

## Troubleshooting

- **`403 Forbidden` / `Invalid access token`** - the token is wrong, expired, or was revoked. Generate a new one and re-paste it.
- **`PERMISSION_DENIED`** - the token's user lacks rights on that cluster, job, warehouse, or catalog. Use a token from a user with the needed permissions.
- **`databricks_sql_statement` returns `PENDING` / `RUNNING`** - the query did not finish within the wait window. Increase `wait_timeout` (up to `50s`) or fetch the result later by its statement_id via `databricks_request`.
- **`RESOURCE_DOES_NOT_EXIST`** - the job_id, run_id, or warehouse_id is wrong. List first, then use the returned ids.

## Links

- [Databricks REST API reference](https://docs.databricks.com/api)
- [Personal access token authentication](https://docs.databricks.com/aws/en/dev-tools/auth/pat)