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

# Databricks

> Query Unity Catalog tables with SQL, and run and monitor Databricks jobs.

Databricks connects with a personal access token minted inside one workspace. Every call runs against that workspace's own host, so connect each workspace you want to reach separately - they appear as separate accounts to pick from.

## What you can do

**SQL** - run a statement on a SQL warehouse and get its rows back, and fetch the result of a long-running statement by id.

**Unity Catalog** - list catalogs, schemas and tables, and read one table's columns and types.

**Jobs and compute** - list SQL warehouses and clusters, list jobs, start a job run, and read a run's state and per-task results.

**Triggers** - none. Use it through the assistant in chat or as an action node in an automation.

## Get your credential

<Steps>
  <Step title="Open your Databricks settings">
    In Databricks, open your profile menu → **Settings** → **Developer** → **Access tokens**.
  </Step>

  <Step title="Generate a token">
    Click **Generate new token**, give it a lifetime, and copy it - Databricks shows it once.
  </Step>

  <Step title="Note the workspace URL">
    Copy the URL you sign in at, e.g. `https://dbc-1234abcd-5678.cloud.databricks.com`.
  </Step>
</Steps>

<Note>
  To narrow what arg.ai can reach, mint the token on a service principal that holds only the Unity
  Catalog grants you want it to have, rather than on your own account. A token always carries its
  owner's permissions, enforced by Databricks.
</Note>

## Connect

<Steps>
  <Step title="Open Integrations">
    In arg.ai, go to **Settings → Integrations** and click **Connect** on **Databricks**.
  </Step>

  <Step title="Enter the workspace URL and token">
    Paste the workspace URL and the token into the connect dialog.
  </Step>

  <Step title="Save">arg.ai checks the token against that workspace and connects it.</Step>
</Steps>

## Use it

* **In chat:** *"Which tables are in main.sales, and how many orders shipped late last week?"*
* **In an automation:** add a **Databricks** action node that runs a query on a warehouse, and chain later steps off its `rows`.

## How a query works

* **Find the schema first.** List catalogs, schemas and tables, then read the table definition, so the SQL is written against real column names rather than guessed ones.
* **Pick a warehouse.** A statement runs on a SQL warehouse, so list warehouses and pass the `warehouse_id`. A query against a stopped warehouse starts it, which Databricks bills.
* **Bind values, don't paste them.** Pass values as named parameters (`:name`) instead of interpolating them into the SQL text.
* **Long queries return an id.** If the statement is still running when the wait elapses, you get back `pending: true` and a `statement_id` to fetch the result with.
* **Results are the first chunk.** Large results come back flagged rather than paged - narrow the query or lower the row limit instead.

## What it costs

arg.ai charges nothing extra for the integration. Running SQL and starting job runs consume Databricks compute, billed by Databricks against your account.