Skip to main content
TrailsparkDocs

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.
  • 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.

Info

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.

Next Steps