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

# Databricks Integration

> Connect a Databricks SQL warehouse to Statisfy to sync product usage, custom fields, and custom objects with self-serve query configuration.

### Connect Databricks with Statisfy

The Databricks integration lets you import data from your Databricks SQL warehouse into Statisfy. Author queries in the Statisfy settings UI, preview against your warehouse, and schedule them — sync product usage, account-level custom fields, person-level attributes, or custom objects.

Databricks uses the same self-serve configuration model as the other warehouse integrations. You can find the shared concepts — query types, account resolvers, transformers, schedules, configuration history — in [Integration Concepts](/integrations/self_serve_configuration). This page focuses on what's specific to Databricks.

**Prerequisites:**

* **Admin access** to Statisfy
* A Databricks workspace with a running **SQL warehouse**
* A **personal access token** for a user (or service principal) with `SELECT` access on the catalogs and schemas you want to sync
* **Unity Catalog** enabled for the data you want to browse (see [Schema browsing](#databricks-specific-notes))

### What You Can Import

| Data Type          | Description                           | Use Case                                     |
| ------------------ | ------------------------------------- | -------------------------------------------- |
| **Product Usage**  | Time-series usage metrics per account | MAU, API calls, feature usage                |
| **Custom Fields**  | Account- or person-level attributes   | Health scores, segments, industry, plan tier |
| **Custom Objects** | Domain-specific records               | Subscriptions, deployments, contracts        |

### Gather Your Connection Details

Statisfy connects to a Databricks **SQL warehouse** over its HTTP endpoint. In your Databricks workspace:

1. Open **SQL Warehouses**, pick the warehouse Statisfy should use, and open its **Connection details** tab. Copy:
   * **Server hostname** — e.g., `dbc-a1b2c3d4-e5f6.cloud.databricks.com`
   * **HTTP path** — e.g., `/sql/1.0/warehouses/abc123def456`
2. Generate a **personal access token**: **User Settings → Developer → Access tokens → Generate new token**. Copy it immediately — Databricks shows it only once.

<Tip>
  Use a dedicated user or service principal with read-only grants (`USE CATALOG`, `USE SCHEMA`, `SELECT`) on just the data Statisfy needs, and generate the token for that identity. A small serverless or `2X-Small` warehouse is plenty for sync queries.
</Tip>

### Steps to Connect

1. **Log in to Statisfy.**

2. Navigate to **Integrations → Admin Apps → Databricks → Connect**.

3. Enter your connection details:
   * **Server Hostname** — the warehouse's server hostname (no `https://` prefix)
   * **HTTP Path** — the warehouse's HTTP path
   * **Access Token** — the personal access token
   * **Catalog** *(optional)* — default catalog for queries that don't fully qualify their tables
   * **Schema** *(optional)* — default schema within that catalog

4. Click **Test Connection** to confirm Statisfy can authenticate and run a no-op query.

5. Once connected, Databricks will appear as **Connected** on the Integrations page.

### Configure Queries

Open **Integrations → Databricks → Settings** to:

* **Browse catalogs, schemas, and tables** the token can see, with column types
* **Author queries** using Databricks SQL with autocomplete and a preview pane
* **Map results** to Statisfy accounts (via Statisfy account ID, CRM ID, organization ID, email domain, account name, or any custom field) and to fields, metrics, or custom objects
* **Apply column transformers** to reshape values before they're written
* **Set the cadence** — daily, weekly, monthly, or a sub-day interval (HOURLY through TWELVE\_HOURS)
* **Run a one-off sync** on demand

Each saved query is one of three types — `product_usage`, `custom_field`, or `custom_object`. See [Query types](/integrations/self_serve_configuration#query-types) and [Account resolvers](/integrations/self_serve_configuration#account-resolvers) for the shared model.

### Databricks-Specific Notes

* **Unity Catalog for schema browsing.** The schema browser reads Unity Catalog's per-catalog `information_schema`. Tables that live only in the legacy `hive_metastore` won't appear in the browser — you can still query them directly if the token has access, but Unity Catalog is the supported surface.
* **Fully qualify objects across catalogs.** If a query references a table outside the default catalog / schema, qualify it explicitly: `catalog.schema.table`.
* **Date placeholders.** Use `{START_DATE}` / `{END_DATE_SQL}` to keep queries incremental. Databricks SQL's `DATE_TRUNC()`, `DATE_ADD()`, and `TO_DATE()` work well with these placeholders.
* **Warehouse cost.** Each query wakes the SQL warehouse and consumes DBUs. Use a small warehouse with a short auto-stop interval to minimize idle cost.

### Account Matching

| Resolver                | Description                              |
| ----------------------- | ---------------------------------------- |
| **Statisfy Account ID** | Native Statisfy account identifier       |
| **CRM Account ID**      | Salesforce or HubSpot account identifier |
| **Organization ID**     | External org identifier                  |
| **Email Domain**        | Company website domain                   |
| **Account Name**        | Company name (fuzzy matching)            |
| **Custom Field**        | Any custom field defined on accounts     |

<Warning>
  Rows that don't resolve to an existing Statisfy account are skipped. For CRM ID resolvers, make sure your CRM integration has synced the matching accounts first.
</Warning>

For `custom_field` queries that target people instead of accounts, configure a **person resolver** (email column, optionally name) — Statisfy will upsert the person record by email.

### Sync Behavior

**Scheduled Jobs:**

* Each saved query runs on its own cadence.
* The first run after connecting is a **bootstrap** covering the last 30 days; subsequent runs cover only the active window for the cadence.
* Databricks is self-serve only — there is no built-in fallback configuration, so queries run only once you've saved them in Settings.

**Error Handling:**

* Per-query errors are logged but do not block other queries from running.
* Invalid rows within a query are skipped and reported in the job audit log.

### Network Access

If your workspace uses **IP access lists** to restrict who can reach it, allow Statisfy's egress IPs:

```text theme={null}
35.203.185.27
35.197.52.231
```

### Security

* The access token is stored encrypted in Google Cloud Secret Manager.
* All connections use TLS.
* Queries authored in the Settings page are read-only — Statisfy validates each query and rejects DDL/DML before save.
* Access is scoped to whatever the token's identity can see — grant `SELECT` only on the catalogs and schemas you want Statisfy to read.

### Troubleshooting

<Accordion title="Connection test fails">
  **Check the endpoint:**

  * Confirm the **Server Hostname** has no `https://` prefix and the **HTTP Path** matches the warehouse's Connection details tab exactly
  * Confirm the SQL warehouse is not stopped by an admin policy — Statisfy can wake an auto-stopped warehouse, but the first connection may take a minute while it starts

  **Check the token:**

  * Personal access tokens expire — regenerate if the token's lifetime has lapsed
  * Confirm your workspace allows personal access tokens (**Admin Settings → Advanced → Personal Access Tokens**)
  * If the workspace uses IP access lists, confirm Statisfy's egress IPs are allowed
</Accordion>

<Accordion title="Catalogs, schemas, or tables not visible in the browser">
  * Confirm the token's identity has `USE CATALOG` on the catalog, `USE SCHEMA` on the schema, and `SELECT` on the tables
  * Only **Unity Catalog** data appears in the browser — legacy `hive_metastore`-only tables are not listed
  * `information_schema` and system schemas are intentionally hidden
</Accordion>

<Accordion title="Query validation errors at save time">
  * Statisfy validates queries against the Databricks SQL dialect — vendor-specific functions from other warehouses will be flagged
  * DDL (`CREATE`, `DROP`) and DML (`INSERT`, `UPDATE`, `DELETE`, `MERGE`) are rejected — only read-only queries are allowed
  * Check the validation error for the offending function or syntax
</Accordion>

<Accordion title="Records not matching to accounts">
  * Verify the resolver column contains values that exist in Statisfy
  * For CRM ID resolvers, confirm your CRM integration has synced the matching accounts
  * Try a different resolver (switch from account name to email domain) if matching is unreliable
  * Add a `regex_extract` or `strip_prefix` transformer if the column contains the right ID with extra characters
</Accordion>

<Accordion title="Sync is slow or running up DBUs">
  * Use a smaller SQL warehouse with a short auto-stop interval for sync queries
  * Lower the cadence to `DAILY` so each run scans a smaller window
  * Use `{START_DATE}` / `{END_DATE_SQL}` to keep queries incremental rather than scanning the full table
</Accordion>

### Need Help?

For initial setup, query design, or troubleshooting, contact [support@statisfy.com](mailto:support@statisfy.com).