How Conversion works with Databricks
Conversion connects to Databricks through a SQL warehouse, signing in as an OAuth service principal, and runs the queries you write on a schedule you choose. Lakehouse tables in the schemas you grant can land as contacts, as custom objects tied to contacts, or as events that start workflows. Syncs are scheduled rather than real time, and Conversion never writes to your workspace.
What you can do
Runs on your SQL warehouse
Sync queries run on the Databricks SQL warehouse you connect. Giving Conversion its own warehouse keeps syncs from competing with other workloads.
Lakehouse models as objects
Bring products, subscriptions, or usage in as custom objects related to contacts, with details such as role or quantity stored on the relationship itself.
Signals that start workflows
Rows with an event name and timestamp become events on contacts, ready to trigger workflows and filter audiences.
Scheduled, incremental runs
Run each sync every 15 minutes, hourly, every 6 hours, or daily. Compare your timestamp column with from_unixtime() on last_sync_time so a run reads only changed rows.
What syncs
| Data | Direction | Details |
|---|---|---|
| Contacts | Into Conversion | Upserted by userId, or by email when the query returns no userId. Column aliases decide which fields each value fills. |
| Custom objects | Into Conversion | Any custom object type you define in Conversion, related to contacts through relationshipFields built with named_struct. |
| Events | Into Conversion | Each row becomes an event on a contact's timeline. Include an eventId so a row synced twice is recorded once. |
How to connect Databricks
- 1 Create a service principal for Conversion in your Databricks workspace settings and generate an OAuth secret. Save the client ID and secret, since the secret is shown only once.
- 2 Grant the service principal USE CATALOG, USE SCHEMA, and SELECT on the data you want to sync, plus Can use on the SQL warehouse.
- 3 If your workspace uses IP access lists, allow Conversion's IP addresses.
- 4 Add a Databricks connection in Conversion settings with the warehouse's server hostname, port, and HTTP path, your catalog and schema, and the OAuth credentials. Then create your syncs.
