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

# Databricks

> Connecting Databricks to Unblocked

> [!NOTE]
>
> **The Databricks integration is in beta.**

Connect Databricks to let Unblocked reference data from the catalogs you select when answering questions.

## Prerequisites

* A Databricks workspace administrator who can create a service principal and generate an OAuth secret.
* Permission to manage the SQL warehouse and grant privileges on the catalogs and schemas you want Unblocked to access.
* A SQL warehouse in the workspace you want to connect.

Use the same workspace throughout setup. The screenshots show example workspaces and the service principal name `unblocked`; use your own workspace, catalog, and schema names.

## Set up OAuth in Databricks

Before connecting in Unblocked, create a dedicated service principal, grant it access to a SQL warehouse and read access to the data you want indexed, and generate an OAuth secret restricted to SQL. This gives you the **Client ID** and **OAuth secret** that Unblocked needs.

**1. Open service principal settings**

In your Databricks workspace, click your profile icon and select **Settings**.

![Databricks profile menu with Settings selected](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/open-settings.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=800bbce2add7252c5e2487ab431be8b1)

Under **Workspace admin**, select **Identity and access**. Next to **Service principals**, click **Manage**.

![Identity and access settings with the Service principals Manage button](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/identity-and-access.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=dda477cdaa03c4befd5184c270b373bf)

**2. Create a service principal with SQL access**

Click **Add service principal**. Open the **Service principal** dropdown and select **Add new service principal to account and workspace**.

![Option to add a new service principal to the account and workspace](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/add-service-principal.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=76abfe1fcf8bfbb0d022ade39f197ee0)

Enter a name such as `unblocked`. Enable **Databricks SQL access** and leave the other entitlements off, including **Admin access**, **Unrestricted cluster creation**, and **Allow instance pool creation**. Click **Add service principal**.

![Service principal with Databricks SQL access enabled](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/sql-entitlement.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=276f56b6b6d45b3ded8bc351f2b72794)

> [!NOTE]
>
> If you already have a dedicated service principal, select it from the dropdown instead. Ensure it is assigned to this workspace and has the **Databricks SQL access** entitlement.

**3. Generate an OAuth secret**

Open the service principal, select **Secrets**, and click **Generate secret**.

![Service principal Secrets tab with the Generate secret button](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/secrets.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=8297653f59172a9b5feec556b61ca429)

Set **Lifetime (days)** according to your organization's rotation policy. The dialog accepts 1–730 days. Under **Scope**, select **BI Tools**, click **Add scope**, search for `sql`, and select **sql**. Close the **Add scope** dropdown. For **sql**, select **Read + Restricted query**, then click **Generate**.

![OAuth secret configuration with the sql scope set to Read + Restricted query](https://mintcdn.com/unblocked/gFg3BNZGUag3HRGf/img/databricks/sql-oauth-scope.png?fit=max\&auto=format\&n=gFg3BNZGUag3HRGf\&q=85\&s=0c08f8ad76f8e7426f9230f4dd7ae26e)

Copy the **Secret** and **Client ID** into your approved secret store before clicking **Done**. You will enter these in Unblocked. The Client ID is the service principal's application ID.

> [!WARNING]
>
> The secret is displayed only once. Keep it out of documentation and source control, and replace it before it expires.

The `sql` scope limits API access. You must also grant warehouse and data permissions in the following steps. See [Databricks OAuth setup](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) for details.

**4. Grant access to a SQL warehouse**

Select **SQL Warehouses** in the sidebar and open the warehouse Unblocked should use.

![SQL Warehouses list](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/sql-warehouses.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=da6c3745c005f2ca842e26f682355e83)

Click **Permissions**, search for your service principal, and select it. Give it **Can use** permission and apply the change.

![Warehouse permissions dialog with the unblocked service principal in search results](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/warehouse-permissions.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=a259cd3223103b3288d0b5c51bbd7d49)

Confirm that the principal has **Can use** access on the selected warehouse. You will choose this warehouse in Unblocked after connecting.

**5. Grant read access to your data**

Choose either the Catalog UI or a SQL script to grant the same read access.

> [accordion] Use the Catalog UI
>
> Open **Catalog** in the sidebar, expand your catalog, and select the schema you want Unblocked to access. Open **Permissions** and click **Grant**.
>
> ![Schema Permissions tab with the Grant button](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/schema-permissions.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=5c64afde6b27d9e56dd8e97180022d4d)
>
> Select your service principal. Choose the **Custom** privilege preset, select **SELECT**, and ensure **USE SCHEMA** is included. If the dialog reports missing access to the parent catalog, keep **Also grant USE CATALOG** checked. Click **Confirm**.
>
> ![Schema grant dialog with SELECT, USE SCHEMA, and the parent USE CATALOG grant selected](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/schema-grants.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=35bc2c2aa0747c87d16c9f666d3484c4)

> [accordion] Use a SQL script
>
> Open **SQL Editor** in your Databricks workspace and select a SQL warehouse. Run the following as a metastore admin, object owner, or user with permission to grant privileges on the catalog and schema.
>
> Replace `<catalog>`, `<schema>`, and `<service-principal-client-id>` with your values. Use the service principal's **Client ID** (application ID), not its display name, and keep the backticks around each identifier.
>
> ```sql theme={null}
> GRANT USE CATALOG ON CATALOG `<catalog>`
>   TO `<service-principal-client-id>`;
>
> GRANT USE SCHEMA ON SCHEMA `<catalog>`.`<schema>`
>   TO `<service-principal-client-id>`;
>
> GRANT SELECT ON SCHEMA `<catalog>`.`<schema>`
>   TO `<service-principal-client-id>`;
> ```
>
> These statements grant data access only. Complete the SQL warehouse **Can use** permission step above as well. See [Manage privileges in Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog/manage-privileges) for SQL grant requirements.

Repeat for each schema you want Unblocked to access. Granting `SELECT` on a schema covers its current and future tables and views. The principal needs `USE CATALOG` on each parent catalog and `USE SCHEMA` on each schema. See the [Unity Catalog privileges reference](https://docs.databricks.com/aws/en/data-governance/unity-catalog/access-control/privileges-reference).

> [!NOTE]
>
> For narrower access to [a single table or view](#grant-single-table-view), or broader access to an [entire catalog](#grant-entire-catalog), see the optional grant variations below.

> [accordion] Grant access to a single table or view (optional)
>
> For narrower access, grant **USE CATALOG** on the parent catalog and **USE SCHEMA** on the parent schema. Then open each allowed table or view in **Catalog**, select **Permissions**, and grant **SELECT** to your service principal.
>
> Alternatively, run the following in **SQL Editor** with permission to grant privileges on these objects. Replace the placeholders with your catalog, schema, table or view, and service principal's **Client ID**. For a view, replace `ON TABLE` with `ON VIEW` and use its name in `<table-or-view>`.
>
> ```sql theme={null}
> GRANT USE CATALOG ON CATALOG `<catalog>`
>   TO `<service-principal-client-id>`;
>
> GRANT USE SCHEMA ON SCHEMA `<catalog>`.`<schema>`
>   TO `<service-principal-client-id>`;
>
> GRANT SELECT ON TABLE `<catalog>`.`<schema>`.`<table-or-view>`
>   TO `<service-principal-client-id>`;
> ```
>
> Use these grants instead of schema-wide **SELECT**. Schema-wide grants also apply to objects created later.

> [accordion] Grant access to an entire catalog (optional)
>
> To let Unblocked read every schema, table, and view in a catalog, open the catalog in **Catalog**, select **Permissions**, and click **Grant**. Select your service principal and grant **USE CATALOG**, **USE SCHEMA**, and **SELECT**.
>
> Alternatively, run the following in **SQL Editor** with permission to grant privileges on the catalog. Replace `<catalog>` and `<service-principal-client-id>` with your catalog name and the service principal's **Client ID**.
>
> ```sql theme={null}
> GRANT USE CATALOG ON CATALOG `<catalog>`
>   TO `<service-principal-client-id>`;
>
> GRANT USE SCHEMA ON CATALOG `<catalog>`
>   TO `<service-principal-client-id>`;
>
> GRANT SELECT ON CATALOG `<catalog>`
>   TO `<service-principal-client-id>`;
> ```
>
> Catalog-level `USE SCHEMA` and `SELECT` apply to current and future schemas and their tables and views. Use these grants instead of schema-wide grants only when you want all of that data accessible to Unblocked.

> [accordion] Revoke Unblocked's access (optional)
>
> To stop the dedicated service principal from accessing this workspace, open **Settings** › **Identity and access** › **Service principals** › **Manage**. Select the principal and, under **Status**, uncheck **Active**.
>
> Deactivation prevents authentication and API access in this workspace while preserving the principal's permissions. Reactivating it restores access with those permissions. See [Deactivate a service principal](https://docs.databricks.com/aws/en/admin/users-groups/manage-service-principals#deactivate-a-service-principal).

## Connect in Unblocked

With your workspace URL, OAuth secret, and Client ID ready, connect Databricks in Unblocked.

**1. Connect Databricks**

In the Unblocked sidebar, click **Settings**, then **Data Sources**, then **Connect another data source**, and select **Databricks**.

**2. Enter your workspace and OAuth credentials**

Enter the following values:

* **Workspace URL**: The URL of the Databricks workspace where you assigned the service principal and granted warehouse access.
* **OAuth secret**: The secret you generated for the service principal.
* **Client ID**: The service principal's application ID, shown when you generated the secret.

Click **Connect**.

![Unblocked Databricks setup form with Workspace URL, OAuth secret, and Client ID fields](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/connect.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=e5e763de2e6d95d601a6bafb5eda8bab)

**3. Choose your environment and SQL warehouse**

Under **Environment**, choose **Production** for real business data or **Development** for test and sample data.

Under **SQL Warehouse**, choose the warehouse you granted the service principal permission to use. Unblocked uses it to query Databricks.

**4. Select your catalogs**

Under **Catalog Access**, use **Find catalogs** to filter the list. Select the catalogs you want Unblocked to index, then click **Save Settings**. Unblocked starts indexing your selected catalogs.

![Databricks settings with Environment and SQL Warehouse dropdowns, catalog checkboxes, and the Save Settings button](https://mintcdn.com/unblocked/USjkacQOZ7fvSVWH/img/databricks/catalog-selection.png?fit=max\&auto=format\&n=USjkacQOZ7fvSVWH\&q=85\&s=98c465ecd5025401540faa84fa5306bc)

**5. Wait for indexing to complete**

Unblocked shows **Processing** for Databricks on the **Data Sources** page while indexing is in progress. Unblocked will not use Databricks to answer questions until indexing completes.

![Connected Data Sources page showing Databricks with Processing status](https://mintcdn.com/unblocked/pdI0jd7AYVQgj7dD/img/databricks/indexing.png?fit=max\&auto=format\&n=pdI0jd7AYVQgj7dD\&q=85\&s=3a2ca58afd826c408fc104a9037eef3d)

You can update the environment, warehouse, and catalog selection from **Settings** › **Data Sources** › **Databricks**. A new warehouse takes effect as soon as you select it. Click **Save Settings** to apply changes to the environment or catalogs.

## Troubleshooting

* **Connection fails:** Check the workspace URL, Client ID, and OAuth secret. Confirm that the secret has not expired and includes the `sql` scope.
* **No SQL warehouses found:** Confirm that the principal is assigned to the connected workspace, has **Databricks SQL access**, and has **Can use** permission on a warehouse. Reload the page after updating permissions.
* **No catalogs found or queries fail with a permission error:** Confirm `USE CATALOG`, `USE SCHEMA`, and `SELECT` on the data you want Unblocked to access.
* **A catalog shows "(temporarily unavailable)":** Unblocked can't currently access that catalog. Its checkbox is disabled until the catalog is available again, and an existing selection is kept. Confirm that the service principal still has access to the catalog.
