> ## 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
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.
In your Databricks workspace, click your profile icon and select **Settings**.
Under **Workspace admin**, select **Identity and access**. Next to **Service principals**, click **Manage**.
Click **Add service principal**. Open the **Service principal** dropdown and select **Add new service principal to account and workspace**.
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**.
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.
Open the service principal, select **Secrets**, and click **Generate secret**.
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 dropdown and click **Generate**.
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.
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.
Select **SQL Warehouses** in the sidebar and open the warehouse Unblocked should use.
Click **Permissions**, search for your service principal, and select it. Give it **Can use** permission and apply the change.
Confirm that the principal has **Can use** access on the selected warehouse. You will choose this warehouse in Unblocked after connecting.
Choose either the Catalog UI or a SQL script to grant the same read access.
Open **Catalog** in the sidebar, expand your catalog, and select the schema you want Unblocked to access. Open **Permissions** and click **Grant**.
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**.
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 ``, ``, and `` 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 ``
TO ``;
GRANT USE SCHEMA ON SCHEMA ``.``
TO ``;
GRANT SELECT ON SCHEMA ``.``
TO ``;
```
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).
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.
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 ``.
```sql theme={null}
GRANT USE CATALOG ON CATALOG ``
TO ``;
GRANT USE SCHEMA ON SCHEMA ``.``
TO ``;
GRANT SELECT ON TABLE ``.``.``
TO ``;
```
Use these grants instead of schema-wide **SELECT**. Schema-wide grants also apply to objects created later.
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 `` and `` with your catalog name and the service principal's **Client ID**.
```sql theme={null}
GRANT USE CATALOG ON CATALOG ``
TO ``;
GRANT USE SCHEMA ON CATALOG ``
TO ``;
GRANT SELECT ON CATALOG ``
TO ``;
```
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.
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.
In the Unblocked sidebar, click **Settings**, then **Data Sources**, then **Connect another data source**, and select **Databricks**.
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**.
Under **SQL Warehouse**, choose the warehouse you granted the service principal permission to use. Unblocked uses it to query Databricks.
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.
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.
You can update the warehouse and catalog selection from **Settings** › **Data Sources** › **Databricks**.
## 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.