# Connect Databricks

> What your Databricks admin sets up, how you sign in, how live queries work, what the semantic layer switch reads, and how to fix the errors you're most likely to hit.

Connect · 6 min read · Updated 2026-10-28

Connect Databricks and Golden queries your SQL warehouse under the Unity Catalog permissions of the identity you connect as. Golden does not import the underlying tables. Query results return to Golden to draw your charts and may be cached for five minutes. This page covers setup, what happens after you connect, and how to read the errors.

## Before you start (for your Databricks admin)

- A SQL warehouse, and CAN USE permission on it for the identity Golden signs in as. For a token or service-principal connection, copy its Server Hostname and HTTP Path from the warehouse's Connection details tab.
- A way to sign in: each person's own Databricks account, a personal access token, or a service principal's OAuth Client ID and secret. Per-user sign-in is the default for a new saved connection; a service principal can keep a shared connection working when people change roles.
- Read access in Unity Catalog on the data you want in Golden.

```sql
GRANT USE CATALOG ON CATALOG main TO `golden-readers`;
GRANT USE SCHEMA ON SCHEMA main.sales TO `golden-readers`;
GRANT SELECT ON SCHEMA main.sales TO `golden-readers`;
```

*Example Unity Catalog grants. Swap in your own catalog, schema, and group.*

> **Note:** A new saved Databricks connection opens on Sign in with Databricks (per-user). Each person queries with their own Unity Catalog permissions. To use a personal access token or a service principal instead, change Authentication method; the credential fields and Save Connection button then appear. Per-user setup is not offered when adding a connection inside Create Analysis.

## Connect

1. In a space, click Create and choose Saved connection, then pick Databricks. Authentication method starts on Sign in with Databricks (per-user).
2. Name the connection, enter the Workspace URL in the sign-in setup card, and click Continue.
3. Follow Register an OAuth app in Databricks. Your Databricks admin registers the displayed Redirect URL in the Databricks account console, selects the SQL scope, and leaves Generate a secret unchecked for the public PKCE client.
4. Paste the resulting OAuth Client ID into the setup card and click Save. Under Connect your account, click Authorize.
5. Sign in with your own Databricks account. Once the connection is active, Golden opens the import wizard.

## Use a token or service principal instead

1. Change Authentication method to Personal access token (legacy) or Service principal (OAuth). This replaces the per-user setup card with the connection fields, the Semantic layer section, and Save Connection.
2. Enter Server Hostname and HTTP Path. Catalog and Schema are optional.
3. For a personal access token, paste the token. For a service principal, enter its Client ID and Client secret.
4. Click Save Connection. Golden tests the connection before saving it and opens the import wizard.

## Pick your data

After you connect, the import wizard opens with the title "Import Schema from <connection>". It has three tabs: Browse Tables, Query Builder, and Custom SQL.

- Browse Tables: search with "Search tables, columns, descriptions...", then tick up to 10 tables. Golden suggests relationships between them so you can chart across them.
- Query Builder: pick a table, columns, and filters, then click Preview Query to see the generated SQL. Copy SQL or Edit in Custom SQL takes it further.
- Custom SQL: write a single read-only SELECT. Validate Query checks it before you import. Anything that writes, or more than one statement, is refused with "Only read-only SELECT queries are allowed here".
- Click Import Schema to finish.

> **Tip:** Golden remembers the table list for up to 24 hours so the browser opens fast. If a table you just created is missing, click the refresh icon ("Refresh from the warehouse") or the Refresh button next to "Don't see your schema or table?".

The browser lists every catalog the token can see; the Catalog field doesn't narrow it. Workspaces without Unity Catalog show their databases instead. Metric views are listed with a "Metric view" tag and can be imported like any table — see Work with semantic views.

## How queries and refresh work

Import Schema saves the structure of your Databricks tables rather than importing their rows. Charts, filters, and AI questions use query results from Databricks. Golden may reuse a chart result for up to five minutes; when a fresh result is needed, it queries the warehouse again.

- Golden reuses a chart's result for 5 minutes, so flipping between sheets doesn't re-run the same query.
- There's no imported table copy to refresh on a schedule. Reopening a dashboard loads warehouse results, which may come from the five-minute chart-result cache.
- A serverless or auto-stopping warehouse starts when Golden queries it, so the first chart after a quiet spell can take a little longer.
- If a query is cancelled, times out, or fails while Golden is waiting for its result, Golden asks Databricks to cancel the running statement. Cancellation is best effort; if it fails, the statement may continue on the warehouse.

## Use semantic layer

For a token or service-principal connection, find Semantic layer and turn on Use the descriptions, tags and Certified status already set in Unity Catalog. Golden reads:

- Column comments become field descriptions.
- Column tags show on their fields. Common classification tags get friendly names, and some change how Golden treats the column.
- A system.certification_status tag of certified or deprecated marks the field accordingly.

The token needs to read the catalog's information_schema.column_tags and run DESCRIBE TABLE EXTENDED. To pick up changes later, open the dataset and click Refresh from semantic layer.

## Limits

| Limit | Value |
| --- | --- |
| Chart query time | 120 seconds. After that the chart shows a timeout error. |
| Rows in a table chart | 50,000. Totals are still computed over every row. |
| Queries running at once | 4 per dataset. The rest wait their turn. |
| Query rate | 600 per minute per account. Past that: "Too many queries right now. Please wait a moment and try again." |
| Tables per import | 10 |

## Troubleshooting

| What you see | What to do |
| --- | --- |
| insufficient privileges for this operation | Grant the token's identity USE CATALOG, USE SCHEMA, and SELECT on the data, and CAN USE on the warehouse. |
| the query timed out | Add filters or narrow the date range. A larger warehouse also helps. |
| Databricks result incomplete: received N of M rows | The warehouse dropped part of the result. Try again; if it repeats, narrow the query. |
| rejected client ID or secret | For a service principal connection. Check the Client ID and Client secret, and that the principal is enabled. |
| Tables you expect are missing | Check the token's Unity Catalog grants, then click Refresh in the browser. |

### Related

- [Set up a warehouse connection](https://goldenanalytics.com/docs/connector-setup)
- [Bring in a table with custom SQL](https://goldenanalytics.com/docs/custom-sql-tables)
- [Model several tables together](https://goldenanalytics.com/docs/multi-table-data-models)
- [Troubleshooting](https://goldenanalytics.com/docs/troubleshooting)

Source: https://goldenanalytics.com/docs/connect-databricks