Skip to main content
Connect your Databricks workspace so the agent can reach your lakehouse two ways. Genie answers plain-language questions over a curated Genie Space. The SQL warehouse runs queries from your notebooks. By default, Qualia queries Databricks as you, so Unity Catalog enforces your own permissions on both paths. For example, a table you can’t SELECT stays hidden from the agent too.
  • A SQL warehouse query runs on the warehouse you select, so you need access to that warehouse as well as the data.
  • A Genie question runs on the compute inside the Genie Space, so you need permission to run the Space. Unity Catalog still decides which rows come back.
Qualia has the Databricks permissions of whoever it queries as. To prevent writes, grant only read access to the tables you want to explore.

Prerequisites

Your workspace needs:
  • Unity Catalog, with at least one catalog you want Qualia to read.
  • A SQL warehouse. Serverless is recommended, because it starts in seconds where a classic warehouse can take minutes.
  • A Genie Space covering the tables the agent should answer questions about.
  • Partner-powered AI features turned on in workspace admin settings, because Genie doesn’t answer without them.
  • An OAuth application registered in your Databricks account console. Databricks doesn’t support automatic app registration, so you can’t skip this.
Registering the OAuth application needs access to the Databricks account console. In Qualia Cloud, saving the workspace configuration also needs an organization admin in Qualia. On desktop you configure it yourself.

Required privileges

Each person who signs in needs these in Databricks. None of them require workspace admin rights.

Register the OAuth application

In the Databricks account console, create an OAuth application:
1

Copy the client ID

Note the client ID. Create a client secret too if you want a confidential client. A public client works without one.
2

Add the redirect URL

Add the Redirect URL shown in Settings > Integrations > Databricks. It must match exactly.
  • If you use Qualia Cloud, it ends in /api/databricks/callback on your Qualia API host.
  • If you use the desktop app, it defaults to http://127.0.0.1:8020/api/databricks/callback.
3

Grant the scopes

Grant sql, genie, unity-catalog, offline_access, openid, email, and profile.

Connect Qualia

Databricks settings have two steps. Step 1, Workspace points Qualia at a workspace and its OAuth application. Step 2, Your access is your personal sign-in, available once step 1 is saved.
1

Open Databricks settings

Go to Settings > Integrations > Databricks.
2

Describe the workspace

Enter the Workspace URL as a hostname, such as dbc-a1b2c3d4-e5f6.cloud.databricks.com, and pick its Cloud.
3

Paste the client credentials

Paste OAuth client ID, and OAuth client secret if you created one. Confirm Redirect URL matches what you registered.
4

Save

Click Save and continue.
5

Sign in

Under Your access, click Sign in with Databricks and authorize.
6

Choose what to query

Qualia runs Workspace checks and lists the Genie Spaces and SQL warehouses you can reach. Click Use next to one of each. A failed check names the grant that fixes it.
You can also pick a Default catalog and schema, which sets what an unqualified table name resolves against. Generated SQL still uses full catalog.schema.table names, so the default is a convenience. What happens next depends on how you use Qualia:
  • If you use Qualia Cloud, every other member signs in individually from the same page. The workspace, warehouse, Genie Space, catalog, and schema are shared, and only an organization admin can change them. Each authorization stays personal.
  • If you use the desktop app, the configuration and the authorization are both yours alone.

Finish sign-in by hand on desktop

If desktop sign-in doesn’t complete, paste the callback address yourself. After you authorize, copy the full address from the browser, even if the page shows a connection error, and paste it into Callback URL. You need this in three cases:
  • The browser never returns to Qualia. Click Didn’t return to Qualia? Paste the callback URL under the sign-in button.
  • Another program holds the callback port. Qualia says another process is already using it. Free the port, or change the port in Redirect URL, save, and register the new URL in Databricks.
  • Qualia runs on a remote backend or over SSH. The callback lands on the machine running the browser, so paste it from there.

Query as a service principal

In Qualia Cloud, an admin can make every query run as one Databricks service principal instead of each person. Then the service principal’s Unity Catalog grants apply to everyone, and no answer is attributable to an individual. Keep Query as on Each person if you want per-user governance. Each person is the default, and the only option on desktop. Service principal uses token federation, so you store no secret in Qualia. Qualia doesn’t accept personal access tokens.

Set up token federation

1

Create the service principal

In the Databricks account console, go to User management > Service principals and create one. Grant it CAN USE on the SQL warehouse, USE CATALOG and USE SCHEMA on the parents, and SELECT on the tables.
2

Switch Qualia to the service principal

In Settings > Integrations > Databricks, under Authentication method, set Query as to Service principal. Enter the Service principal application ID. Leave Federation audience blank unless your policy needs a specific one, then save.
3

Copy the policy values

A Federation policy section appears with the exact values Qualia signs, each with a copy button. They are specific to your organization.
4

Add the federation policy in Databricks

In the account console, open the service principal and add a federation policy with the copied values. Leave token signature validation empty.
Under Service principal, nobody signs in individually, so step 2 has no Sign in with Databricks button. The warehouse and Genie Space pickers appear once you save, listing what the service principal can reach.

Connect through Partner Connect

If you start from the Qualia tile in Databricks Partner Connect, Databricks provisions the workspace details for you. An organization admin lands on the settings page with the workspace filled in, confirms it, then picks a warehouse and Genie Space. Partner Connect provisions Qualia Cloud only. Re-running the tile for a connected workspace updates it instead of creating a second connection. If your trial lapses, Qualia disables the connection without deleting it. Re-run the tile after you convert to restore it.

Query from a notebook

Ask the agent, or call the Databricks helper yourself from Python, R, or Julia:
Python returns a pandas DataFrame, R a data.frame, and Julia a column table that DataFrame accepts. All three take catalog and schema arguments that override the connection’s defaults. To check which workspace, warehouse, catalog, and schema a notebook uses without exposing the token, call qualia_databricks.workspace_info(), databricks_workspace_info(), or Qualia.Databricks.workspace_info(). Pass values as parameters instead of building them into the SQL string, so the warehouse treats them as data and never as SQL:
In Python, query opens its own connection each time. For several statements, use connect, which returns a reusable DB-API connection:
Always use the three-level catalog.schema.table name. A bare table name resolves against the connection’s default, which is the most common cause of an unexpected “table not found”.
The R and Julia helpers cap a single result at 25 MiB, a Databricks API limit. Aggregate or add LIMIT in SQL instead of pulling a whole table into the kernel. Python has no such cap.
The Python helper needs databricks-sql-connector[pyarrow]. Qualia Cloud kernels already have it. On desktop, the first query reports it missing and the agent offers to install it, once per kernel environment.

Ask Genie

With a Genie Space selected, the agent can ask it a question in plain language. The answer shows Powered by Genie with a link to the Space that produced it. Genie knows the joins and business definitions your admin curated, so it is often a better first stop than SQL against unfamiliar tables. Genie returns an answer to read, not data in your notebook. Use Genie to orient, then query through the helper when you need values to compute on. A Genie answer can’t serve as evidence, the runtime values that back a finding.

Manage the connection

  • Expired authorization: if settings say your Databricks authorization expired, click Sign in with Databricks again.
  • Rotate the client secret: enter the new value in OAuth client secret and save. Leaving the field blank keeps the stored secret, and existing sign-ins survive the rotation.
  • Disconnect: removes your own authorization. In Qualia Cloud, other members stay connected.
  • Remove: under Remove connection, deletes the workspace configuration and every authorization it covers. In Qualia Cloud only an organization admin can do this.
Query results stay in your notebook, and Genie answers stay in chat, after you disconnect.

Troubleshooting