Databricks SQL Warehouse - Superblocks Docs

Databricks SQL Warehouse is a powerful data analytics and lakehouse platform that enables organizations to unify data engineering, data science, and business analytics at scale. Integrate Databricks SQL Warehouse with Superblocks to build internal tools and workflows that query, analyze, and update your Databricks data, empowering your team to automate processes, gain insights, and accelerate decision-making.

Setting up Databricks SQL Warehouse

Configure authentication

To access your Databricks warehouse, you’ll need to authenticate using a Databricks account. Superblocks provides several different ways to authenticate. See the Databricks documentation below for how to configure your preferred authentication method.

Method	Description
Personal access token (PAT)	Use a short or long-lived access token for a user or service principal.
Machine-to-machine OAuth	Configure OAuth client credentials for a service principal. Superblocks will exchange the client credentials with Databricks to retrieve a short-lived OAuth token.
OAuth token federation	Use OAuth tokens issued by your identity provider when users log in to Superblocks to authenticate with Databricks using the authenticated user’s permissions.

Add integration

In the web app, navigate to the Integrations page
Click Add integration
Search for Databricks SQL Warehouse and select it from the list of available integrations
Name the integration
Fill out the integration configuration as follows:

Personal access token based connection
Machine-to-machine OAuth
OAuth token federation

Field	Required	Description
Host	✓	Databricks instance host name
Port	✓	Port to use when connecting to your warehouse
HTTP Path	✓	HTTP path either to a DBSQL endpoint (e.g. `/sql/1.0/endpoints/1234567890abcdef`) or to a DBR interactive cluster (e.g. `/sql/protocolv1/o/1234567890123456/1234-123456-slid123`)
Default catalog	✗	An optional initial catalog to use
Default schema	✗	An optional initial schema to use
Access token	✓	Databricks personal access token

Field	Required	Description
Host	✓	Databricks instance host name
Port	✓	Port to use when connecting to your warehouse
HTTP Path	✓	HTTP path either to a DBSQL endpoint (e.g. `/sql/1.0/endpoints/1234567890abcdef`) or to a DBR interactive cluster (e.g. `/sql/protocolv1/o/1234567890123456/1234-123456-slid123`)
Default catalog	✗	An optional initial catalog to use
Default schema	✗	An optional initial schema to use
OAuth client ID	✓	Client ID associated with your service principal
OAuth client secret	✓	Client secret associated with your service principal

Field	Required	Description
Host	✓	Databricks instance host name
Port	✓	Port to use when connecting to your warehouse
HTTP Path	✓	HTTP path either to a DBSQL endpoint (e.g. `/sql/1.0/endpoints/1234567890abcdef`) or to a DBR interactive cluster (e.g. `/sql/protocolv1/o/1234567890123456/1234-123456-slid123`)
Default catalog	✗	An optional initial catalog to use
Default schema	✗	An optional initial schema to use
Subject token source	✓	Select Login identity provider to use the access token issued to Superblocks when users log in via SSO, or provide a Static token.
Token URL	✓	Databricks token URL. Choose a URL format based on the federation policy you previously configured. Workspace identity federation `https://<databricks-workspace-host>/oidc/v1/token` Account-wide token federation `https://<databricks-account-host>/oidc/accounts/<account-id>/v1/token`
Service Principal UUID	✗	Only required if using Workload identity federation. The service principal client ID to authenticate as.

Optionally, add more configurations to set credentials for different environments
Click Test Connection to check that Superblocks can connect to the data source
Click Create

Using Databricks SQL Warehouse in APIs

Once your Databricks SQL Warehouse integration is created, you can start using Databricks by writing SQL in Superblocks APIs.

Troubleshooting

If you run into issues, first see our guide on Troubleshooting Database Integrations. There are also several common errors you may see when using Databricks SQL Warehouse. The table below includes error messages, why they happen, and how to address them.

Error message	Why it’s happening & Resolution
`IntegrationTimeoutError: Failed to connect to warehouse. Connection timed out after <N>ms`	Reason Databricks warehouses can be configured to automatically hibernate after a period of inactivity. This timeout usually occurs when the warehouse is hibernating and did not restart within the timeout threshold of the agent. Resolution Retry the API/test connection after the warehouse has restarted, or increase the automatic hibernation time for your Databricks warehouse.
`IntegrationOAuthError: OAuth2 - "On-Behalf-Of Token Exchange" could not find identity provider token`	Reason You’ve selected Login identity provider as the subject token source when using OAuth token federation, but you are not currently logged in to Superblocks using an OIDC-based Identity Provider. Resolution Reach out to support@superblocks.com for assistance configuring SSO or migrating your SSO configuration to OIDC.
`Failed to process token: TOKEN_EXPIRED`	Reason The access token issued to Superblocks when you logged in, or the static token you’ve provided has expired. Resolution If using Login identity provider, log out of and back into Superblocks. If using a static token, obtain a new federated JWT from your identity provider.
`Failed to process token: TOKEN_INVALID (Ensure a valid federation policy has been configured)`	Reason Your Databricks account either does not have a federation policy configured, or the `subject_token` being sent to Databricks by Superblocks does not satisfy the policy. This can happen if the token is not a valid JWT, or has a different `aud` or `iss` than configured in the Databricks federation policy. Resolution Make sure the `aud` and `iss` configured in Databricks are the same `aud` and `iss` your IdP uses when issuing tokens to Superblocks. Make sure the Databricks federation policy points to a valid JWKS URI. By default, Databricks uses the URI provided at `<issuer-url>/.well-known/openid-configuration`. You may need to change this if your IdP uses a non-default authorization server or does not support a `/.well-known` discovery URL.

If you are encountering an error that’s not listed, or the provided steps are insufficient to resolve the error, please contact us at support@superblocks.com

​Setting up Databricks SQL Warehouse

​Configure authentication

​Add integration

​Using Databricks SQL Warehouse in APIs

​Troubleshooting

Setting up Databricks SQL Warehouse

Configure authentication

Add integration

Using Databricks SQL Warehouse in APIs

Troubleshooting