Data Warehouse Sync - Conversion Docs

Data warehouse sync lets you bring data from your data warehouse into Conversion. Sync contacts, custom objects, relationships, and events directly from tables and views in your warehouse—keeping Conversion in sync with your source of truth.

Why Sync from Your Data Warehouse?

Your data warehouse is often the most complete and accurate source of customer data:

Use your existing data models — Query the tables you already have instead of restructuring data for Conversion
Keep data fresh automatically — Schedule syncs to run on an interval, ensuring Conversion always has current data
Sync any data type — Bring in contacts, companies, custom objects, relationships, and events from a single integration

Supported Warehouses

Conversion supports the following data warehouses:

BigQuery

Google BigQuery

Snowflake

Snowflake Data Cloud

Redshift

Amazon Redshift

Key Concepts

Before setting up your integration, it helps to understand a few key concepts.

Syncs

A sync defines what data to pull from your warehouse and how to map it to Conversion. Each sync includes:

A destination type — What kind of data you’re syncing (contacts, custom objects, or events)
A SQL query — The query that returns the data you want to sync
A schedule — How often the sync runs

You’ll typically create multiple syncs for a single warehouse connection—one for contacts, one for each custom object type, etc.

Incremental Syncing

To avoid re-syncing your entire dataset on every run, syncs support incremental syncing using a timestamp column. Conversion exposes a last_sync_time variable you can use in your query to only select rows that have changed since the last sync.

SELECT id, email, first_name, last_name, updated_at
FROM users
WHERE updated_at > '{{last_sync_time}}'

On the first sync, last_sync_time is set to the Unix epoch (0), so all rows are synced. On subsequent syncs, only rows updated since the last run are included.

We strongly recommend including a WHERE clause using last_sync_time in all syncs. Without it, you’ll re-sync your entire dataset on every interval, which is slower and less efficient.

Unique Keys

Each sync requires a unique key that identifies records. This key determines how Conversion matches incoming rows to existing records:

Destination Type	Unique Key
Contacts	Email address
Custom Objects	Object ID
Events	Message ID (for deduplication)

What You Can Sync

Contacts

Sync contacts from your warehouse to create or update contact records in Conversion. Contacts are matched by email address. Required columns:

email — The contact’s email address (unique identifier)

Optional columns:

Any contact field (e.g., first_name, last_name, job_title, phone)
Custom field keys you’ve defined in Conversion

SELECT 
  email,
  first_name,
  last_name,
  title AS job_title,
  phone,
  city,
  updated_at
FROM users
WHERE updated_at > '{{last_sync_time}}'

Custom Objects

Sync custom objects to create or update records of a specific custom object type. Objects are matched by their ID. Required columns:

id — Your unique identifier for this object

Optional columns:

Any field defined on the custom object type

SELECT 
  id,
  name,
  status,
  plan_tier,
  renewal_date,
  updated_at
FROM subscriptions
WHERE updated_at > '{{last_sync_time}}'

You must create the custom object type in Conversion before setting up a sync. The sync will create and update individual objects of that type.

Custom Objects with Relationships

To connect a custom object to a contact, include the contact’s email and any relationship-specific fields in your query. This creates both the object and its relationship to the contact in a single sync. Required columns:

id — Your unique identifier for this object
email — The contact to relate this object to

Optional columns:

Any field defined on the custom object type
relationshipFields — A JSON object containing relationship-specific fields

SELECT 
  p.id,
  p.name,
  p.sku,
  p.category,
  u.email,
  JSON_OBJECT(
    'role', up.role,
    'quantity', up.quantity,
    'purchased_at', up.purchased_at
  ) AS relationshipFields,
  up.updated_at
FROM user_products up
JOIN products p ON up.product_id = p.id
JOIN users u ON up.user_id = u.id
WHERE up.updated_at > '{{last_sync_time}}'

In this example:

Object fields (id, name, sku, category) create or update the Product object
email identifies which contact to relate the object to
relationshipFields contains fields specific to this contact’s relationship with the object (their role, quantity purchased, etc.)

If multiple rows have the same object id but different email values, Conversion creates one object with multiple relationships—one for each contact.

Events

Sync events to record activity on contacts. Events appear on the contact’s timeline and can trigger workflows. Required columns:

email — Identifies the contact
event_name — The name of the event
timestamp — When the event occurred

Optional columns:

Any event property
message_id — A unique identifier for deduplication

SELECT 
  u.email,
  'purchase_completed' AS event_name,
  o.created_at AS timestamp,
  o.id AS message_id,
  o.total_amount,
  o.product_name,
  o.currency
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.created_at > '{{last_sync_time}}'

We use message_id to deduplicate events. If you send the same event twice with the same message_id, we’ll ignore the duplicate. This is especially useful when using time-buffered queries.

Setting Up a Sync

1. Connect Your Warehouse

Navigate to Settings → Integrations → Data Warehouse and select your warehouse type. You’ll need to provide connection credentials—the specific requirements vary by warehouse.

We recommend creating a dedicated read-only user for Conversion. This limits access to only the tables you need and makes it easy to revoke access if needed.

2. Create a Sync

After connecting your warehouse, create a sync:

Click Add Sync
Select the destination type (Contacts, Custom Objects, or Events)
For Custom Objects, select the specific object type
Enter your SQL query
Set the sync schedule
Enable the sync

3. Set the Schedule

Choose how often your sync runs:

Frequency	Best For
Every 15 minutes	High-frequency data like events or rapidly changing attributes
Every hour	Most contact syncs
Every 6 hours	Large datasets or slowly changing data
Daily	Historical data or very large syncs

If a sync is still running when the next scheduled run begins, we’ll skip that run. Choose a frequency that gives your query enough time to complete.

Incremental Sync Strategies

Using last_sync_time

The simplest approach is to filter on an updated_at column:

SELECT *
FROM contacts
WHERE updated_at > '{{last_sync_time}}'

Time-Buffered Queries

If your updated_at timestamps aren’t perfectly reliable, you can add a buffer to catch rows that might have been missed:

SELECT *
FROM contacts
WHERE updated_at > TIMESTAMP_SUB('{{last_sync_time}}', INTERVAL 5 MINUTE)

When using time-buffered queries, include a message_id column (for events) or rely on the unique key to handle duplicates. Conversion will update existing records rather than creating duplicates.

Full Syncs

For small tables or when you need to ensure complete accuracy, you can omit the WHERE clause to sync all rows on every run. This is less efficient but guarantees no rows are missed.

Monitoring and Troubleshooting

Sync History

View the history of each sync in the Syncs tab. Each run shows:

Start and end time
Number of rows processed
Number of successful and failed operations
Error details (if any)

Common Errors

Error	Cause	Solution
Missing required field	A row is missing a required column (e.g., `email` for contacts)	Update your query to ensure required columns are never null
Invalid field value	A value doesn’t match the expected type (e.g., text in a number field)	Cast values to the correct type in your query
Object type not found	Syncing to a custom object type that doesn’t exist	Create the custom object type in Conversion first
Connection failed	Conversion can’t reach your warehouse	Check your network settings and credentials

Frequently Asked Questions

What happens if a sync fails?

If a sync fails, we’ll retry on the next scheduled interval. Partial failures (where some rows succeed and others fail) are logged, and you can download error details from the sync history. Failed rows won’t affect successful rows.

Can I sync the same data to multiple destinations?

Yes. You can create multiple syncs from the same warehouse, each with its own query and destination. This is common when you need to sync contacts and their related custom objects from different tables.

Can I transform data in my query?

Yes. Use SQL functions to transform data before it reaches Conversion. For example, you can concatenate fields, convert types, or apply conditional logic.

What timezone are timestamps in?

last_sync_time is a Unix timestamp (UTC). Your query should compare against UTC timestamps. If your data uses a different timezone, convert it in your query.

Can I sync objects without relating them to contacts?

Yes. If your query doesn’t include an email column, the objects are created without any relationships. You can add relationships later through a separate sync or via the API.

What if a contact doesn't exist yet?

If you sync a custom object with an email that doesn’t exist in Conversion, we’ll create the contact automatically with just that email address. You can enrich the contact’s profile through a separate contacts sync.

Objects

Fields

Integrations

​Why Sync from Your Data Warehouse?

​Supported Warehouses

BigQuery

Snowflake

Redshift

​Key Concepts

​Syncs

​Incremental Syncing

​Unique Keys

​What You Can Sync

​Contacts

​Custom Objects

​Custom Objects with Relationships

​Events

​Setting Up a Sync

​1. Connect Your Warehouse

​2. Create a Sync

​3. Set the Schedule

​Incremental Sync Strategies

​Using last_sync_time

​Time-Buffered Queries

​Full Syncs

​Monitoring and Troubleshooting

​Sync History

​Common Errors

​Frequently Asked Questions

Why Sync from Your Data Warehouse?

Supported Warehouses

Key Concepts

Syncs

Incremental Syncing

Unique Keys

What You Can Sync

Contacts

Custom Objects

Custom Objects with Relationships

Events

Setting Up a Sync

1. Connect Your Warehouse

2. Create a Sync

3. Set the Schedule

Incremental Sync Strategies

Using last_sync_time

Time-Buffered Queries

Full Syncs

Monitoring and Troubleshooting

Sync History

Common Errors

Frequently Asked Questions