Required Role: Cora.ai Admin, plus a Databricks workspace admin
Connects to: A Databricks SQL warehouse with Unity Catalog tables
Prerequisites
- A Databricks workspace admin, who can create a service principal and its OAuth secret
- A SQL warehouse, and the catalog and schema that hold the tables you want to share
Setup steps
Live queries can read anything the service principal can read, not only the synced tables. Grant it only the data you want to share. Some workspaces give all users access to the workspace catalog by default, so check what the service principal can read before you connect.
1
Create a service principal and an OAuth secret
In your Databricks workspace, create a service principal for Cora.ai with the Databricks SQL access entitlement. Note its application ID: this is the client ID you enter in Cora.ai. Then, on its Secrets tab, generate an OAuth secret. In the Generate OAuth secret dialog:
- Choose BI Tools and keep the default access level, Read + Restricted query
- Set a lifetime from 1 to 730 days. Cora.ai cannot connect once the secret expires, and Databricks revokes a secret that is not used for 90 days
- Copy the secret value. Databricks shows it only once
2
Grant read access
Give the service principal the Can use permission on the SQL warehouse. Then grant it read access in Unity Catalog, using its application ID in backticks:
SELECT on the schema also covers tables you add later. To share fewer tables, grant SELECT on each table instead.3
Connect Databricks in Cora.ai
- Log into Cora.ai as an Admin
- Go to Settings → Integrations
- Find the Databricks row and click Connect
- In the Connection section, fill in the fields below, then click Connect. In Databricks, the hostname and HTTP path are under SQL Warehouses → your warehouse → Connection details
The connection is saved and the integration is turned on. The button changes to Save, and the status reads Connected.
4
Choose the tables to sync
There is no table picker yet. An Admin can ask Cora.ai in chat, for example “Sync the accounts and usage_daily tables from Databricks”, or your Cora.ai contact can set them up. Until then, Sources reads “No sources configured yet.” and nothing syncs.
What Cora.ai accesses
Reads: The tables you choose, in full, once a day (06:00 UTC by default). Chat answers from this synced copy. When you ask for live data, or for a table that is not synced, Cora.ai queries the warehouse directly. Writes: None. The OAuth scope makes every session read-only, so Databricks rejects any insert, update, delete, or schema change.Limits
- One catalog and one schema. A connection syncs tables from the catalog and schema you entered
- Full refresh only. Each sync reads every column of each table and replaces Cora.ai’s copy. Large tables take longer and use more warehouse compute
- Databricks hostnames only. Server Hostname must be on a Databricks domain, such as
cloud.databricks.com,azuredatabricks.net, orgcp.databricks.com. A custom domain, port, or path is refused - Stopped warehouses. A sync or live query starts a stopped warehouse. Databricks starts serverless warehouses in seconds, and pro and classic warehouses in about 4 minutes
- Live query size. A live query returns 1,000 rows by default and 5,000 at most. The warehouse stops it after 30 seconds of running
Security
Troubleshooting
- Save shows “Failed to save — Retry”. Check Server Hostname. It must be the workspace hostname only, on a Databricks domain. The same message shows for any refused save.
- Data stopped updating. A failed sync leaves the connector reading Connected, with the last successful Last Synced time. Ask Cora.ai in chat for the Databricks pipeline status.
invalid_client: Client authentication failedmeans Databricks refused the Client ID and Client secret. Check both, and check that the secret has not expired. - Connected, but nothing is syncing. If Sources reads “No sources configured yet.”, choose the tables (step 4). Also confirm Enable Integration is on.
- Rotating the secret. Generate a new secret in Databricks, enter it in Client secret, and click Save.
- A live query says “The Databricks SQL warehouse did not finish the query within 45 seconds. It may be starting up: retry the query shortly.” The warehouse is starting or busy. Ask again once it is running.

