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

# Data Warehouse Connections and Syncs

> Connect Snowflake, BigQuery, or ClickHouse and configure scheduled syncs that import contacts, custom objects, and events into Conversion.

The **Connections** and **Syncs** tabs of the CRM and syncing page let you import data from a data warehouse into Conversion on a schedule. A **connection** stores the credentials for a warehouse; a **sync** is a SQL query that runs against a connection and writes its rows into Conversion.

<Note>
  Data warehouse syncing is not enabled for every workspace. If you don't see the **Connections** and **Syncs** tabs, contact Conversion. For query requirements and warehouse-specific guidance, see the [Data Warehouse Sync](/product-docs/sync/data-warehouse/overview) guides.
</Note>

Only administrators can add connections and syncs or change their settings. Every member can view them and their logs.

## Connections

The Connections tab has a section for each supported warehouse: **Snowflake**, **BigQuery**, and **ClickHouse**. Click **Add Snowflake connection**, **Add BigQuery connection**, or **Add ClickHouse connection** to create one.

### Creating a connection

Give the connection a **Name** (for example, *Production warehouse*) and confirm the **Warehouse type**, then enter the credentials:

| Warehouse      | Credentials                                                                                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **BigQuery**   | **Project ID** and the **Service account credentials** JSON key downloaded from Google Cloud.                                                                                |
| **Snowflake**  | **Account name**, **Database name**, **Warehouse**, **Role**, **Username**, and the PEM-encoded **Private key** (`.pem`, `.p8`, or `.key`) used for key-pair authentication. |
| **ClickHouse** | **Host**, **Port**, **Database name**, **Username**, and **Password**.                                                                                                       |

For BigQuery and Snowflake, drag the key file onto the upload box or click **Upload**. The issues indicator at the top lists anything still missing. Click **Create connection**; Conversion tests the credentials before saving, and tells you if it couldn't connect.

See [BigQuery](/product-docs/sync/data-warehouse/big-query), [Snowflake](/product-docs/sync/data-warehouse/snowflake), and [ClickHouse](/product-docs/sync/data-warehouse/clickhouse) for how to set up access with the right permissions.

### Managing a connection

Click **View** on a connection to open it. The **Overview** tab shows the saved credentials, where you can replace the key file, change the password, or update other details; changes save automatically. The **Syncs** tab lists the syncs using this connection.

From the options menu you can **Rename** or **Delete** the connection. A connection can't be deleted while any sync still uses it; delete those syncs first.

## Syncs

The Syncs tab lists every sync as a card showing its name, the type of data it imports, an **Active** or **Paused** badge, its description, and a timeline of recent runs. Click a card to open the sync, or **Add sync** to create one.

### Creating a sync

<Steps>
  <Step title="Describe the sync">
    Enter a **Name** and **Description**, pick the **Connection** to query, and choose the **Data type**:

    | Data type          | What it imports                                                                                                                                                                                                 |
    | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Contacts**       | Keeps customer profiles up to date from your warehouse.                                                                                                                                                         |
    | **Custom objects** | Syncs structured records like accounts, products, or deals into a [custom object](/product-docs/workspace-settings/objects/overview#custom-objects) you choose. Only in workspaces with custom objects enabled. |
    | **Events**         | Streams user activity and behavioral data as custom events.                                                                                                                                                     |
  </Step>

  <Step title="Choose the mode and frequency">
    **Mode** controls how rows are written on each run:

    | Mode             | Behavior                                                                                                  |
    | ---------------- | --------------------------------------------------------------------------------------------------------- |
    | **Upsert**       | Add new records and update existing ones. Best for keeping data in sync with your warehouse.              |
    | **Insert only**  | Add new records. Existing records are skipped. Best for append-only data like event logs.                 |
    | **Update only**  | Update existing records. New records are skipped. Best for enriching data already in Conversion.          |
    | **Force insert** | Add every record as new, even if duplicates exist. Best for one-time backfills or replays. Contacts only. |

    Events always use **Upsert**. **Frequency** sets how often the sync runs, from every minute to every few months.
  </Step>

  <Step title="Set contact options">
    For contact and event syncs, choose whether to **Subscribe new contacts** this sync creates to email. Existing contacts keep their subscription status. Event syncs can also **Create contacts for unmatched emails** when an event's email doesn't match an existing contact; this requires an email column and must be on before new contacts can be subscribed.
  </Step>

  <Step title="Write the SQL query">
    Click **Edit query** to open the SQL editor. The query must be a `SELECT` statement that returns an identity column: `user_id` or `email` for contacts and events, and `object_id` (or `id`) for custom objects. Alias other columns to the Conversion field keys they should fill; use **Insert contact field** (or **Insert \<object> field**) to pick them, and the **Schema** sidebar to browse your warehouse's tables and columns. Click **Preview** to run the query and inspect the first 100 rows.
  </Step>

  <Step title="Create and activate">
    Click **Create sync**. New syncs start **Paused**. Open the sync and click **Activate**; Conversion validates the query first and shows the schedule it will run on.
  </Step>
</Steps>

<Tip>
  Filter your query with `{{last_sync_time}}` so each run only fetches rows that changed since the last one. The editor warns you when the query doesn't use it.
</Tip>

### Managing a sync

Opening a sync shows its status, which object and connection it uses, and two tabs:

* **Overview**: the sync's settings and SQL query. Pause the sync to edit its mode, frequency, contact options, or query; the description can be edited at any time.
* **Logs**: every run of this sync, with the same detail as [Sync activity](/product-docs/workspace-settings/crm-and-syncing/sync-activity). Filter by date range, activity type, or status.

Use **Pause** to stop scheduled runs (previously synced data stays in Conversion) and **Activate** to resume. The options menu offers **Rename**, **Delete**, and **Go to connection**. Deleting a sync is permanent and stops future runs.

<Note>
  **Activate** stays disabled while the issues indicator lists problems, such as a missing description or a query that doesn't return an identity column.
</Note>