> For the complete documentation index, see [llms.txt](https://docs.seemoredata.io/external-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/integration-with-seemore.md).

# Integration with Seemore

{% hint style="info" %}
**Required role to configure:** [Admin](https://docs.seemoredata.io/external-docs/fundamentals/settings/user-roles.md) or higher.

Users with lower roles can view this feature but cannot change its configuration.
{% endhint %}

Before starting, complete [Create Databricks Service Principal and Privileges](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md). You'll need:

* The **workspace URL**, and the **client ID** and **secret** of the service principal.
* A SQL warehouse that the service principal has **Can use** on, in each region you want SeeMore Data to fetch.

To start, go to **Marketplace** in SeeMore Data, select **Add integration**, and choose **Databricks**. The setup has up to three steps:

1. **Setup integration**: the integration's name.
2. **Connected region**: sign in, then check a SQL warehouse in the region of the workspace you enter.
3. **Other regions**: check a SQL warehouse in each other region of your account. This step appears only when your account has workspaces in another region.

Then you can add an AWS integration for AWS billing. There is no pricing step: SeeMore Data reads your rates from your account's billing system tables.

### Connected region <a href="#connected-region" id="connected-region"></a>

#### Sign in <a href="#credentials" id="credentials"></a>

The step opens with the workspace and the service principal that SeeMore Data signs in with:

* **Workspace URL**: the workspace where you created SeeMore Data's SQL warehouse. SeeMore Data finds the account's other workspaces from here. The format depends on your cloud:
  * AWS — `<workspace>.cloud.databricks.com`
  * Azure — `adb-<id>.<n>.azuredatabricks.net`
  * GCP — `<id>.gcp.databricks.com`
* **Service principal client ID**: the client ID (application ID) of the service principal you created.
* **Service principal secret**: the Databricks OAuth secret generated for that service principal. On Azure, this is the secret generated in Databricks, not a Microsoft Entra client secret.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2Fgit-blob-523e12399f3d460fc5c4feac377a94db9decb48d%2Fdatabricks-credentials.png?alt=media" alt="The Connected region step before the sign-in, with fields for the workspace URL, the service principal client ID and the service principal secret, above the Test connection button"><figcaption><p>Three values from the setup page. The SQL warehouse comes after the sign-in.</p></figcaption></figure>

Then select **Test connection**. The test signs in as the service principal, reads which Unity Catalog region the workspace is in, and lists the workspace's SQL warehouses. It doesn't use a SQL warehouse, so nothing starts in your account. Until the test passes, the line beside **Finish setup** says *"Test the connection to continue."*

When the test passes, the form collapses to **Signed in to** your workspace, with its cloud and region. Select **Edit** to change the credentials.

When the test fails, **Could not sign in** says why, and who can fix it. For example:

* *"Databricks rejected the client ID or the secret, or the service principal is not added to this workspace."* Check the client ID and the secret, and [step 3](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#add-to-workspace) of the setup page.
* *"Give the service principal the Databricks SQL access and Workspace access entitlements in \<workspace>."* See [step 3](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#add-to-workspace) of the setup page.
* *"The service principal secret is missing the OAuth scopes …"* Create a new secret, as described in [step 1](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#create-service-principal) of the setup page.
* *"This workspace's IP access list blocks SeeMore Data's IP addresses."* See [step 7](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#allowlist-ips) of the setup page.
* *"Attach this workspace to a Unity Catalog metastore."* SeeMore Data reads Unity Catalog system tables, and a workspace without a metastore has none.

Fix the cause, then select **Test again**.

#### Check the connected region <a href="#permission-checks" id="permission-checks"></a>

After the sign-in, the region's card appears, titled with the region's name and *Connected region*. Choose a **SQL warehouse** dedicated to SeeMore Data, such as `seemore_warehouse`, and select **Check**.

The check reads the tables from [step 5](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#grant-privileges) of the setup page through that SQL warehouse: the account-wide tables, such as billing and the workspace list, and the tables that only the region's own metastore holds, such as query history. A region's system tables can only be read through a SQL warehouse in that region, so each region is checked, and later fetched, through a SQL warehouse you choose for it.

A stopped SQL warehouse is started for the check, so the first check can take a minute. If it's still starting when the check stops waiting, the card says *"The SQL warehouse is still starting. Check again in a minute."*

{% hint style="info" %}
The list shows only the SQL warehouses that the service principal has a permission on. If there are none, the card says *No SQL warehouse the service principal can use*, with a **Give SQL warehouse access** link. Give the service principal **Can use** on one ([step 3](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#grant-warehouse-access) of the setup page), then test the connection again.
{% endhint %}

#### Reading the results

The card shows an outcome:

* **Ready** — every check passed.
* **Ready with gaps** — the required tables can be read, and something optional is missing. You can finish setup. The views that depend on what's missing stay empty until you grant it.
* **Not ready** — a required table can't be read, or the service principal can't use the SQL warehouse. **Finish setup** stays off until you fix it.

**Available** lists what the region gives SeeMore Data: **Cost**, **Queries**, **SQL warehouses**, **Compute and jobs**, **Lineage** and **AI**. Hover over the ⓘ beside each one to see what it covers. **Cost** and **Queries** are required. [Tables read](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/permissions-and-data-handling.md#optional-tables) lists every table behind them.

**Missing** has one line for each thing to fix: the permission, who can grant it, and what is lost without it. A red line is required, and an amber line is optional. Each permission links to the part of the setup page that fixes it:

| Missing line                  | Who can fix it  | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SELECT on system.<schema>`   | Metastore admin | [Step 5](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#grant-privileges): grant the schema                                                                                                                                                                                                                                                                                                                                                                               |
| `system.<schema> not found`   | Metastore admin | For an optional schema, [step 4](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#enable-system-schemas): enable it, if Databricks offers it in this region. A required schema is always enabled, so the cause is a missing `USE CATALOG` on `system` or `USE SCHEMA` on the schema: [step 5](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#grant-privileges) |
| `USE CATALOG on system`       | Metastore admin | [Step 5](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#grant-privileges). Shown alone when none of the required tables can be found                                                                                                                                                                                                                                                                                                                                      |
| `Can use on <SQL warehouse>`  | Workspace admin | [Step 3](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#grant-warehouse-access), or choose another SQL warehouse                                                                                                                                                                                                                                                                                                                                                          |
| `databricks_pii_access group` | Account admin   | [Step 2](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#query-text-access). Without it, SeeMore Data imports queries without their text                                                                                                                                                                                                                                                                                                                                   |

Grants are made per region, so run them in a workspace of the region that the card names, then select **Check again**.

**Workspaces** lists the region's workspaces that the service principal can sign in to.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2Fgit-blob-e880bb0716afe124e04bbfb7adfa8298f55caaa9%2Fdatabricks-connected-region.png?alt=media" alt="The Connected region step after the check: us-west-2 is Ready with gaps, with Cost, Queries, SQL warehouses, Compute and jobs and Lineage available, two optional Missing lines, and Set up other regions beside Finish setup"><figcaption><p>The connected region checked, with one more region in the account</p></figcaption></figure>

Once the connected region passes, and the account has workspaces in other regions, the line beside the buttons says, for example, *1 more region in this account.*, and **Set up other regions** appears beside **Finish setup**. While SeeMore Data is still looking, it says *Finding other regions…*

### Other regions <a href="#other-regions" id="other-regions"></a>

SeeMore Data reads the account's workspace list, signs in to each running workspace, and groups the workspaces by region. Each other region gets its own card, with the same SQL warehouse check as the connected region. The list holds the SQL warehouses of that region's workspaces that the service principal has a permission on.

A region's own tables are fetched only through its own SQL warehouse. For each region, either:

* **Choose a SQL warehouse in that region and select Check.** The card shows its results the same way as the connected region, except **Cost**: cost is read once for the whole account, so only the connected region lists it.
* **Leave it unchecked.** The region gets cost only, and its card says **Cost only**. The line beside **Finish setup** names those regions, for example *Cost only for eu-west-1 and us-east-1.*

When one region is left to decide, **Skip this region** (or **Skip \<region>** when the account has several other regions) appears beside **Finish setup**. A skipped card says *"Cost only. Seemore won't import this region's queries, SQL warehouses, clusters, jobs, lineage or AI detail, so automations won't run here."* Select **Set up this region** to undo it.

If a region has no SQL warehouse to choose, create one there ([step 3](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#create-warehouse) of the setup page), then test the connection again. You can also set up a region later by editing the integration.

#### Workspaces that refuse the sign-in

When a workspace refuses the sign-in, SeeMore Data can't read its region, so it can't place the workspace on a region's card:

* **The service principal isn't added to it.** The workspace isn't listed. Instead, the step says *Missing a workspace?*, with a link to **Add the service principal to it**. Add it ([step 6](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#workspace-access) of the setup page), then select **Look again**.
* **Any other cause.** The workspace is listed under *Couldn't sign in to all workspaces in the region*, under the fix it needs, such as **Give the service principal workspace and SQL access** or **Allow Seemore's IP addresses**, and who can do it. Fix it, then select **Try again**.

These workspaces still have cost data, but no live features such as automations. Both notices appear on the **Other regions** step, or on **Connected region** when the account has no other region.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2Fgit-blob-5e5335e96e8e52c6b8a34f435fad061e0018d224%2Fdatabricks-other-regions.png?alt=media" alt="The Other regions step before any check: eu-west-1 and us-east-1 are Cost only, eu-west-1 has no SQL warehouse the service principal can use, two workspaces couldn&#x27;t be signed in to, and the Missing a workspace hint is shown"><figcaption><p>Two regions not yet checked, one with no SQL warehouse to choose, and workspaces that refused the sign-in</p></figcaption></figure>

### Finish setup

**Finish setup** is enabled once the connected region is **Ready** or **Ready with gaps**. Other regions don't block it. While a check is running, the line beside the button says *"You can continue when the check finishes."* or *"You can finish when the checks finish."*

SeeMore Data saves only the regions it will fetch: the connected region, and every other region that passed its check. The other regions get cost only.

### What SeeMore Data reads, and through which SQL warehouse <a href="#sql-warehouse-per-region" id="sql-warehouse-per-region"></a>

| Data                                                                                                                                                                   | Read through                                        | For which workspaces                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ |
| **Account data**: the workspace list, billing usage, prices, machine types and governed tags                                                                           | The connected region's SQL warehouse                | Every workspace in the account                   |
| **Workspace data**: query history, SQL warehouses and clusters, jobs and pipelines, lineage and audit, AI activity, and the asset catalog                              | The SQL warehouse chosen for the workspace's region | Workspaces in a region that SeeMore Data fetches |
| **Users**, and **live SQL warehouse activity** for [Real Time Monitoring](https://docs.seemoredata.io/external-docs/fundamentals/our-features/real-time-monitoring.md) | Each workspace directly                             | Workspaces in a region that SeeMore Data fetches |

A skipped or unchecked region is not read, except for its account-level cost: your total spend is complete either way. Users, live queries, warehouse automation and AI Services endpoint details also need the service principal added to each workspace, as described in [step 6](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/create-databricks-service-principal-and-privileges.md#workspace-access) of the setup page. Query history and the other workspace data don't.

{% hint style="warning" %}
If a chosen SQL warehouse can't be opened during an import — for example, because it was deleted or lost its **Can use** grant — that region's workspace data is skipped, and the integration card shows the latest query fetch as **Failed**. Edit the integration to choose another SQL warehouse.
{% endhint %}

### Cloud cost

After you enable the integration, you can add an AWS integration to see the AWS infrastructure cost of your Databricks workloads. AWS is the only supported cloud provider. An AWS integration uses its own read-only AWS role, not your Databricks credentials, and an AWS administrator deploys it.

To start, select **Connect cloud provider billing** on your Databricks integration card, or select **AWS** in the **Cloud** section of **Marketplace**. Then follow the [AWS billing guide](https://docs.seemoredata.io/external-docs/fundamentals/getting-set-up/setting-integrations/databricks/cloud-cost/aws.md).

### Finishing later, and editing

A new setup is saved as a draft once the connection test passes. Its card in the marketplace shows **Setup not finished**, with *"Check a SQL warehouse in the connected region to finish setup."* Admins see a **Continue setup** button that reopens it.

<figure><img src="https://3620459840-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnSbIoBjUxWTGNWa9gGw7%2Fuploads%2Fgit-blob-f24c291064f80f715469d13ca98a2009a1200c29%2Fdatabricks-draft-card.png?alt=media" alt="A Databricks integration card in the marketplace marked Setup not finished, with a Continue setup button"><figcaption><p>An unfinished setup waits on its card</p></figcaption></figure>

The draft keeps your credentials, the SQL warehouse you chose for each region, and the regions you skipped. Check results are not kept. When you continue, **Setup integration** shows only the name. Select **Test connection** — reopening doesn't test by itself — then check the regions again. Skipped regions stay skipped.

Editing a finished integration works the same way, with two differences: nothing is saved until you select **Save**, and other regions keep the SQL warehouse they were saved with, as long as it's still listed. The connected region is always checked again before **Save**.
