# Connecting Heap Data

> Source: https://docs.trailspark.ai/bigquery-connector/connecting-heap-data

## Overview

If you use Heap for product analytics and have **Heap Connect** writing to BigQuery, you can bring that product activity into Trailspark without writing any SQL. Connect the BigQuery project Heap writes to, and Trailspark recognizes the Heap dataset and offers ready-made queries for it.

There's nothing to set up on the Heap side beyond Heap Connect itself. Trailspark reads the tables Heap has already written into your warehouse — it never writes to them, and it doesn't connect to Heap.

## Prerequisites

- Heap Connect is set up and syncing to a BigQuery project (this is a paid Heap add-on).
- You've connected that BigQuery project to Trailspark — see [Connecting BigQuery](https://docs.trailspark.ai/bigquery-connector/connecting-bigquery).
- You're an admin or owner in Trailspark.

## Step 1: Let Trailspark find your Heap data

Open **Integrations → BigQuery**. Under **Syncs**, if Trailspark recognizes a Heap export in your project you'll see a note reading **"We found Heap data in this project"**, naming the dataset and how many events are available.

Click **Create the Heap product events sync** to open the sync form with the Heap events template already chosen and the dataset filled in.

> [!NOTE]
> No note? Your Heap dataset may live in a project or region other than the one this connection points at, or the account Trailspark connects with may not be able to list it. You can still use the templates — open **New sync**, pick a Heap template under **Start from a template**, and type the dataset name yourself.

## Step 2: Bring in your product events

With **Heap — product events** selected:

1. Check **Heap dataset** is the right one.
2. Under **Events to bring in**, tick the events you want. This list is the events Heap is syncing to your warehouse.
3. Give the sync a **Name** and a **Schedule**, then click **Run preview** and save.

Which events to pick? The ones that say someone is getting value or getting close to buying — a pricing page view, an invite sent, a team member added, a paid feature tried, a usage limit hit. Everyday navigation events add volume without adding signal.

Leaving the event list empty brings in **every** event Heap syncs. That works, but it's usually far more data than you need.

> [!TIP]
> Events arrive with the person's email attached when Heap has one. Events Heap only knows by its own user ID still come through — the Users sync in the next step is what connects them to a real person later.

## Step 3: Bring in your users

Create a second sync and pick **Heap — users**. This is what matches product activity to actual people, so it's worth doing even if you only care about events.

Under **User columns to bring across**, list any extra columns on Heap's users table you want stored against the person — `company` and `job_title` are the usual ones. Anything you list is kept as an attribute of that person.

One thing to know: Heap's users table has no dependable "last changed" column, so this sync reads every user with an email on each run rather than only what changed. That's fine at most sizes, and **Run preview** shows you how much data each run will read. If your Heap export *does* include a modified timestamp, you can edit the query to compare that column to `@watermark` and each run will read far less.

## Step 4 (optional): Bring in your accounts

If Heap stores an account or company ID against each user, add a third sync with **Heap — accounts**. Tell it which column holds the account ID (and, if you have one, the account name column), and Trailspark builds one record per account from it.

Skip this if your account information already reaches Trailspark from your CRM — you don't need it from two places.

## What good looks like

Once all three are running you should see, within a sync cycle:

- Product activity on people's timelines, attributed to their account.
- New people appearing from Heap that your CRM hadn't seen.
- Accounts scoring on real product usage, not just firmographics.

Check **Run history** on each sync if something looks off — see [Schedules and Run History](https://docs.trailspark.ai/bigquery-connector/schedules-and-run-history).

## Next Steps

- [Designing Sync Queries](https://docs.trailspark.ai/bigquery-connector/designing-sync-queries) — the column requirements behind each feed, if you want to tailor a template
- [Schedules and Run History](https://docs.trailspark.ai/bigquery-connector/schedules-and-run-history) — set a schedule, read run results, and fix a failing sync