Connect Databricks¶

Connect a customer-authored Databricks view containing aggregated traffic counts. Squoosh reads the view through your workspace's SQL Statement Execution API. You decide which source tables, session definition, conversion event, and reporting window the view represents.

What the connection does¶

The connector reads dimension, bucket, and sessions from one view or table. It can produce device, country, and channel distributions, plus a conversion signal when the view supplies a conversion count and a positive session denominator. Every count is marked as customer-reported.

The view must aggregate the same last full UTC days for all dimensions and conversions. Enter that number as Days covered by the view (windowDays), which defaults to 28. Squoosh reports this declaration and the warning window_declared_by_customer. Changing a requested refresh window does not rewrite your view or change its date bounds.

Prepare the calibration view¶

Use the three-column CSV template contract:

dimension,bucket,sessions
device,mobile,600
device,desktop,350
device,tablet,50
geo,US,700
geo,DE,200
geo,other,100
channel,Direct,400
channel,Organic Search,400
channel,Email,200
conversion,total,30

At least 80% of device-session mass must map to the three device labels. Missing dimensions stay absent with warnings. Small samples do not become reliable calibration. Repeated dimension/bucket rows are summed, so do not include overlapping totals or repeated exports. Unlike the CSV template upload, warehouse duplicate rows are allowed because dated aggregates can be additive.

The conversion denominator is the device rows' total, else geography's if device is absent, else channel's if both are absent. A missing conversion row or a zero denominator produces no conversion rate. An explicitly reported zero conversion count with positive sessions remains a real zero. Keep conversions and sessions on the same population and window.

The following is an illustrative view definition to adapt, not a schema Squoosh discovers or creates. Here your_catalog.your_schema.normalized_sessions must be your own normalized relation with one row per session, canonical device/country/channel labels, a UTC TIMESTAMP_NTZ session start, and a Boolean converted flag. Replace these source names and expressions with your real schema. Remove any dimension you cannot measure.

CREATE OR REPLACE VIEW `main`.`analytics`.`SQUOOSH_CALIBRATION` AS
WITH bounds AS (
  SELECT date_trunc('DAY', convert_timezone('UTC', current_timestamp())) AS until_utc
), windowed AS (
  SELECT s.*
  FROM `your_catalog`.`your_schema`.`normalized_sessions` AS s
  CROSS JOIN bounds AS b
  WHERE s.session_started_at_utc >= b.until_utc - INTERVAL 28 DAYS
    AND s.session_started_at_utc < b.until_utc
)
SELECT 'device' AS dimension, device_category AS bucket, COUNT(*) AS sessions
FROM windowed GROUP BY device_category
UNION ALL
SELECT 'geo', country_iso2, COUNT(*) FROM windowed GROUP BY country_iso2
UNION ALL
SELECT 'channel', channel_group, COUNT(*) FROM windowed GROUP BY channel_group
UNION ALL
SELECT 'conversion', 'total', COUNT(CASE WHEN converted THEN 1 END) FROM windowed;

The single windowed relation keeps every branch on the same half-open UTC interval, excluding today. Set windowDays to 28 for this example. If you edit the interval, update the declared setting too. Databricks documents the time-zone conversion in convert_timezone.

The connector selects only the three template columns:

SELECT dimension, bucket, sessions
FROM `main`.`analytics`.`SQUOOSH_CALIBRATION`
LIMIT 10001

Catalog, schema, and view are entered separately. Each component must match ^[A-Za-z_][A-Za-z0-9_$]{0,127}$; do not paste a dotted reference, quotes, spaces, or SQL fragments into any field. Squoosh quotes components with Databricks backtick identifier syntax.

Connect Databricks¶

1. Create or select a service principal assigned to your workspace. In Databricks, open Settings > Identity and access > Service principals > Manage, select the principal, then Secrets > Generate secret. Prefer the sql scope. Copy the application/client ID and the secret; the secret is shown once. See OAuth M2M setup.
2. In SQL Warehouses, open your warehouse. Use Permissions to grant the principal CAN USE. Copy its warehouse ID from Connection details. Choose serverless where available to reduce cold-start delays.
3. In Catalog, grant the principal USE CATALOG on the catalog, USE SCHEMA on the schema, and SELECT on the calibration view. The querying principal does not need SELECT on the underlying source tables; the view owner must have the permissions required by your Unity Catalog configuration. See Unity Catalog privileges.
4. In Squoosh, open Integrations, select Databricks, and choose Connect. Enter the workspace HTTPS URL, SQL warehouse ID, catalog, schema, calibration view name, and days covered by the view. The default view name is SQUOOSH_CALIBRATION.
5. Enter the Service principal client ID and Service principal OAuth secret. Leave the personal access token field empty, then connect.

The connector exchanges the secret for a workspace token once per check or snapshot request. It uses the documented all-apis token request scope; a scoped OAuth secret limits the resulting token's permissions. The scoped-secret exchange still needs live validation with this connector.

If OAuth is unavailable, Databricks' legacy personal access token is an alternative. In Settings > Developer > Access tokens > Manage, generate a token and paste it into Personal access token. Leave both OAuth fields empty. Administrators may disable PATs. Squoosh rejects combined or incomplete credential methods.

Squoosh checks the warehouse, then runs a LIMIT 1 query against the configured view to prove the required read access. This query can start a stopped warehouse. Both checks share the same overall deadline.

What Squoosh reads and never reads¶

Only put aggregated labels and counts in the view. Squoosh uses your warehouse compute, and your view may scan underlying data to calculate those aggregates. The output limit does not bound scanned bytes or cost.

Limits and caveats¶

• 10,000 result rows maximum, before duplicate aggregation. The query requests one extra row to detect overflow. A 10,001st row or an observed provider truncation rejects the snapshot with window_unsupported. Squoosh never silently clips counts.
• One 30-second budget covers authentication, submission, polling, result reads, and best-effort cancellation. The final second is reserved for cancel. Cancel acknowledges a request; it does not prove the warehouse has stopped executing. If submission never returns a statement ID, Squoosh cannot send a targeted cancel.
• Cold starts can time out. Databricks describes serverless starts as typically seconds and pro/classic starts as typically minutes. Retry after the warehouse becomes ready. See warehouse types.
• INLINE JSON results only. No external storage links are downloaded. Databricks' inline size limit or another provider cap can prevent a complete result. See Statement Execution.
• Workspace hosts only. Supported suffixes are .cloud.databricks.com, .azuredatabricks.net, and .gcp.databricks.com. Custom aliases, custom ports, private hosts, and cross-origin redirects are rejected.
• 15-minute minimum refresh policy, not a vendor quota guarantee. Endpoint-specific rate limits are unverified; 429 responses remain retryable. This auth-stage beta does not enter unattended snapshot refresh.
• Live validation is outstanding. Free Edition support for PATs/service-principal secrets is unverified. Promotion requires a real snapshot, validation of the counts and fields, and cold-start testing before grounded use.

Troubleshooting¶

Related¶

• CSV / Excel import, for customer-reported counts without a warehouse connection.
• Connect Google Analytics and Connect Shopify.
• Databricks Statement Execution API.
• Databricks OAuth M2M.