Google BigQuery × HubSpot
How a company that models its customer data in BigQuery (health scores, product usage, revenue and lifetime value) can put those numbers on the HubSpot records that reps, marketers and workflows act on, and keep HubSpot data in BigQuery for analysis. HubSpot's own BigQuery integration is the starting point; a custom build on Google Cloud's APIs covers the rest.
Does BigQuery integrate with HubSpot?
BigQuery is where many companies calculate the numbers sales and marketing need: product usage, account health, lifetime value, churn risk. Those numbers only change outcomes when they reach the HubSpot record a rep opens or a workflow reads, and when HubSpot activity flows back into BigQuery for analysis.
Public documentation. The client's own admin issues credentials, with no vendor approval needed.
Open API. The BigQuery APIs are documented publicly. The client's Google Cloud admin creates the service account and grants roles.
Based on the vendor's public documentation. Access terms are confirmed with the vendor and the client in discovery.
BigQuery exposes its data through documented REST and gRPC APIs, and Google Cloud can push events as they happen, so modeled warehouse data can drive HubSpot records, lists and workflows.
Campaign Creators assessment
HubSpot's own integration is the starting point. With Data Hub Enterprise, HubSpot's BigQuery integration syncs HubSpot objects, associations and events out to BigQuery, and syncs BigQuery data into HubSpot records on a schedule from every 15 minutes to monthly. The custom case is narrower. It covers what that integration doesn't: portals without Data Hub Enterprise, per-field write rules (fill blanks only, never overwrite a rep's edit, write only on change), custom events on the HubSpot timeline, pushes triggered the moment a model finishes, labeled associations and custom objects with their own rules, several Google Cloud projects or datasets feeding one portal, and governance over which columns and rows leave the warehouse. Query cost is a planning item: on-demand BigQuery bills by bytes scanned.
Ratings are CC judgments from Google Cloud's public documentation and HubSpot's knowledge base. Pricing model, schedule and budget are set with the client's Google Cloud admin during discovery.
Event-driven by design
A scheduled query can publish a Pub/Sub message when its run finishes. A Cloud Run service subscribed to that topic pushes the new results to HubSpot right away, so nothing polls.
Who owns each field
A warehouse value written every hour will overwrite a rep's manual edit unless rules say otherwise. Each synced property gets one owner and one write rule, written into the SOW.
Tier and security decisions first
Decide which flows HubSpot's integration covers under Data Hub Enterprise and which need the custom build, and have the client's Google Cloud admin approve the service account, IAM roles and datasets.
Which BigQuery APIs does the integration use?
Seven parts of BigQuery, Google Cloud and HubSpot matter here. HubSpot's integration covers standard flows; the custom build uses Google Cloud's APIs for the rest.
HubSpot's BigQuery integration
Built by HubSpot · Data Hub EnterpriseSyncs in both directions, each set up separately. HubSpot to BigQuery stages Parquet files in a Cloud Storage bucket behind external tables; BigQuery to HubSpot syncs into CRM records.
- HubSpot → BigQuery: objects, associations, events
- BigQuery → HubSpot: every 15 minutes up to monthly
- Sensitive data properties are not synced to BigQuery
BigQuery API
REST · jobs and queriesRuns queries and reads results. The integration layer uses it to read approved views and to record HubSpot IDs and sync status in BigQuery.
- Query jobs against approved views
- Dry runs report bytes before a query runs
- Parameterized queries for change-only reads
Storage Read API
High-throughput reads · gRPCReads table data in parallel streams with column selection and row filters, for backfills and large result sets.
- Select only approved columns
- Row restriction filters at read time
- Billed by bytes read, separate from query pricing
Scheduled queries & Pub/Sub
BigQuery Data Transfer ServiceScheduled queries build the outbound table of changed rows. When a run finishes, a Pub/Sub message reports SUCCEEDED, FAILED or CANCELLED.
- Change table built in SQL, on a schedule
- Run-finished message triggers the push
- Failed runs alert the support team
Cloud Run push worker
Subscriber to the run-finished topicA small service in the client's Google Cloud project that reads the change table and writes to HubSpot in batches, with retries and a dead-letter queue.
- Runs only when there is work
- Idempotent upserts by unique property
- Replays failed batches without duplicates
Storage Write API
Write HubSpot results back · gRPCWrites HubSpot record IDs, sync status and errors back to BigQuery, so the warehouse knows which rows reached HubSpot.
- Committed streams support exactly-once writes
- Records readable as soon as written
- Needs the bigquery.tables.updateData permission
Query cost & IAM
Bytes scanned and least privilegeOn-demand queries bill per TiB processed, with a 10 MB minimum per table referenced. Selected columns are billed even with LIMIT. The pricing model and schedule are agreed before build.
- Partitioned, clustered change tables
- Dedicated service account, read-only on approved views
- Capacity (slot) pricing as an alternative
How does the BigQuery HubSpot integration work?
Models stay in BigQuery. A scheduled query builds a small table of changed rows; when it finishes, Pub/Sub wakes a CC-built Cloud Run worker that applies governance and write rules, matches each row to the right HubSpot record, and writes in batches. HubSpot data returns to BigQuery through HubSpot's integration.
Compute in BigQuery, act in HubSpot
Scores and rollups are calculated once in the warehouse. HubSpot stores the result on the record where people and workflows use it.
Send changes, not tables
A small change table keeps bytes scanned and HubSpot API calls low, and makes every run small enough to replay.
Govern at the source
The service account reads only views the client approves. Restricted columns and rows never leave BigQuery.
What does BigQuery HubSpot integration setup involve?
Each phase ends on a gate the client signs off before the next begins. The first data set goes live while the next is being built.
Use-case inventory
List the decisions sales, marketing and service should make from warehouse data, and the BigQuery datasets or models that hold each number.
Native-or-custom decision
For each data set, decide whether HubSpot's BigQuery integration covers it under Data Hub Enterprise, or whether it needs write rules, events, associations or timing that call for the custom build.
Access & governance
The client's Google Cloud admin creates a dedicated service account with read access to approved views and job rights in one project. Compliance signs off the column list.
HubSpot data model
Create the properties, custom objects, association labels and custom event definitions in a HubSpot sandbox.
Build
Build the change-table query, Pub/Sub topic, Cloud Run worker and write-back for the first data set, with identity matching, write rules, idempotent upserts and a dead-letter queue.
Backfill
Load current values for all matched records once, through the Storage Read API, in batches sized to HubSpot's API limits.
Workflows, parallel run & launch
Build lists and workflows with sends paused, run in parallel for two weeks, review bytes scanned, then switch on.
What does the BigQuery HubSpot integration sync?
Warehouse column names are defined by each client's models, so the source column describes the data plainly. Exact dataset, table and column names are confirmed during discovery.
| BigQuery field | HubSpot property | Object | Direction | Notes |
|---|---|---|---|---|
| Identity & keys | ||||
| HubSpot record ID (stored in BigQuery) | hs_object_id | Contact / Company | ↔ Both | Best match key once known. Written back to BigQuery after first match. |
| Email address | Contact | BQ → HS | Match key for contacts without a stored HubSpot ID. | |
| Company domain | domain | Company | BQ → HS | Match key for companies without a stored HubSpot ID. |
| Customer account ID | bq_account_id | Company | BQ → HS | Client's own account key. Unique property; used for batch upserts. |
| User ID | bq_user_id | Contact | BQ → HS | Product user key. Unique property. |
| Sync status and errors | Status table in BigQuery | — | HS → BQ | Written by the worker through the Storage Write API. |
| Account metrics · companies | ||||
| Annual recurring revenue | bq_arr | Company | BQ → HS | From the revenue model. BigQuery owns this field. |
| Plan or tier | bq_plan_tier | Company | BQ → HS | Dropdown values agreed in discovery. |
| Lifetime value | bq_ltv | Company | BQ → HS | Model output. BigQuery owns this field. |
| Health score | bq_health_score | Company | BQ → HS | Model output, 0 to 100. |
| Churn risk band | bq_churn_risk | Company | BQ → HS | Low, medium, high. Can trigger a CSM workflow. |
| Seats purchased vs used | bq_seats_used | Company | BQ → HS | Rollup from product data. |
| Product usage · contacts | ||||
| Last active date | bq_last_active | Contact | BQ → HS | Write only when changed. |
| Active days, last 30 | bq_active_days_30 | Contact | BQ → HS | Rollup from product events. |
| Key feature adopted | bq_features_adopted | Contact | BQ → HS | Multiple checkboxes. |
| Product-qualified flag | bq_pql | Contact | BQ → HS | Can move lifecycle stage by workflow, not by direct write. |
| Milestone reached | Custom event: Product milestone | Contact | BQ → HS | Timeline entry that workflows can trigger on. |
| Phone, job title | phone, jobtitle | Contact | BQ → HS | Fill blanks only. HubSpot edits win. |
| Custom objects & associations | ||||
| Subscription or license | Subscription (custom object) | Custom object | BQ → HS | Plan, term, renewal date. Object design confirmed in discovery. |
| Workspace or product account | Workspace (custom object) | Custom object | BQ → HS | For multi-workspace customers. |
| Account-to-user link | Association (labeled) | Company ↔ Contact | BQ → HS | Labels such as Admin or Billing contact. |
| Subscription-to-company link | Association | Custom object ↔ Company | BQ → HS | Set from the customer account ID. |
| Renewal opportunity | Deal in renewal pipeline | Deal | BQ → HS | Created when renewal date enters the agreed window. |
| HubSpot → BigQuery | ||||
| Contacts, companies, deals | HubSpot integration export | All objects | HS → BQ | Parquet in Cloud Storage behind external tables. |
| Associations | HubSpot integration export | Associations | HS → BQ | One sync configuration per association pair. |
| Email and web events | HubSpot integration export | Events | HS → BQ | Joins marketing activity to product usage. |
How are authentication and API limits handled?
BigQuery access is self-serve for the client's Google Cloud admin. Values Google does not publish are marked for confirmation.
| Topic | BigQuery | HubSpot |
|---|---|---|
| Access model | A dedicated service account in the client's project, granted roles by the client's Google Cloud admin on approved datasets only. | Private app token for the custom build. Data Hub Enterprise for HubSpot's BigQuery integration. |
| Interfaces | BigQuery API (REST) for query jobs; Storage Read and Storage Write APIs (gRPC); scheduled queries with Pub/Sub run notifications; Cloud Run for the push worker. | REST APIs: CRM objects, batch upserts, associations, custom events, imports. |
| Authentication | Service account identity through Google Cloud IAM; the worker runs as that account, so no key file is needed on Cloud Run. HubSpot token kept in Secret Manager. | Private app access token or OAuth 2.0, scoped per object. |
| Permissions | Data read on approved views and job rights in one project. Write-back needs bigquery.tables.updateData on the status table only. | Scopes for the objects, associations and events in scope. |
| Freshness | Scheduled query frequency set per data set; Pub/Sub delivers the run-finished message as each run ends. | Writes are immediate; batch endpoints handle volume. |
| Cost & limits | On-demand: billed per TiB processed, 10 MB minimum per table referenced; capacity pricing by slot-hour. Storage Read API billed by bytes read. | Per-10-second burst and daily limits by subscription tier. |
| Network & sensitive data | VPC Service Controls or organization policies may restrict access; confirm in discovery. | Sensitive data properties available on Enterprise; HubSpot's integration does not sync them to BigQuery. |
What should you plan for, and what does the integration unlock?
Severity reflects impact on the SOW, not technical difficulty alone.
Challenges to plan for
A query that reads a full wide table every 15 minutes adds up. Partitioned and clustered change tables, selected columns only, and dry-run checks keep cost predictable.
If both systems write the same property, the last write wins. Every synced field gets an owner and a rule (overwrite, fill blanks, or never) before the build starts.
HubSpot's integration needs Data Hub Enterprise and runs on a schedule. Agreeing which flows it handles avoids building twice and keeps the custom scope narrow.
A full table pushed every hour can exhaust daily limits. The worker sends changed rows only and uses batch endpoints.
Only approved columns and rows leave BigQuery. The views and the service account's roles enforce this, and compliance signs off the column list.
HubSpot's integration allows each object type, event type or association pair in only one export configuration. Plan datasets around that before setup.
Opportunities in HubSpot
Health, fit and churn risk sit on the company record, so reps and CSMs see them in views, sequences and tasks.
A usage milestone becomes a HubSpot custom event that enrolls the contact in the right workflow as soon as the model run finishes.
Subscriptions as custom objects create renewal deals on time, with seat and usage data attached.
HubSpot's integration puts marketing and sales activity next to revenue in BigQuery, so attribution models use real outcomes.
Revenue and health are calculated once in BigQuery, so HubSpot reports and warehouse dashboards agree.
Scheduled CSV imports of warehouse exports are replaced by an audited, replayable sync.
Use HubSpot's integration where it fits. Build where it doesn't.
HubSpot's BigQuery integration handles standard, scheduled flows in both directions under Data Hub Enterprise. The custom build is scoped only to what it doesn't cover, so the client pays for the gap, not for a rebuild.
- HubSpot data into BigQuery for analysis: HubSpot's integration.
- Scheduled table-to-record syncs into contacts, companies and deals: HubSpot's integration.
- Per-field write rules, custom events, custom objects with their own rules, or push on model completion: custom build.
- Portals without Data Hub Enterprise, or several projects or datasets into one portal: custom build.
Which HubSpot properties does the integration create?
All custom properties use the bq_ prefix in a BigQuery property group. Values are calculated in BigQuery so every report agrees.
| Internal name | Label | Object | Type | Source / logic |
|---|---|---|---|---|
| bq_account_id | BigQuery Account ID | Company | Single-line text | Client's customer account key; unique |
| bq_user_id | Product User ID | Contact | Single-line text | Product user key; unique |
| bq_arr | ARR | Company | Number (currency) | Revenue model output |
| bq_plan_tier | Plan Tier | Company | Dropdown | Current plan from billing model |
| bq_ltv | Lifetime Value | Company | Number (currency) | LTV model output |
| bq_health_score | Health Score | Company | Number | Model output, 0 to 100 |
| bq_churn_risk | Churn Risk | Company | Dropdown | Low, medium, high |
| bq_seats_used | Seats Used | Company | Number | Active seats from product data |
| bq_last_active | Last Active Date | Contact | Date picker | Latest product activity |
| bq_active_days_30 | Active Days (30) | Contact | Number | Distinct active days, last 30 |
| bq_features_adopted | Features Adopted | Contact | Multiple checkboxes | Key features used at least once |
| bq_pql | Product Qualified | Contact | Single checkbox | PQL rule in BigQuery model |
Interactive scope builder
Choose the data sets and fields for this engagement and the direction each one syncs. Required fields are the keys the integration cannot match without. Copy the summary into the SOW or a reply to the client.
Scope summary
Sources & verification
Based on public documentation from Google Cloud and HubSpot. Pricing model, IAM roles and dataset names are confirmed with the client's Google Cloud admin during discovery.
BigQuery HubSpot integration FAQ
Does BigQuery integrate with HubSpot?
Yes. HubSpot’s own BigQuery integration, available with Data Hub Enterprise, syncs HubSpot objects, associations and events to BigQuery and syncs BigQuery data into HubSpot records on a schedule from every 15 minutes to monthly. Campaign Creators adds a custom build on Google Cloud’s publicly documented APIs for what that integration doesn’t cover, such as per-field write rules, custom events and pushes triggered the moment a model finishes.
What data syncs between BigQuery and HubSpot?
Modeled warehouse data such as ARR, plan tier, lifetime value, health score and churn risk syncs to HubSpot companies; product usage such as last active date, active days and product-qualified flags syncs to contacts; and subscriptions and workspaces sync to custom objects. HubSpot contacts, companies, deals, associations and email and web events flow back to BigQuery through HubSpot’s integration.
Which system owns which data?
Scores and rollups are calculated once in BigQuery, and HubSpot stores the result on the record where people and workflows use it. Each synced property gets one owner and one write rule (overwrite, fill blanks or never), agreed before the build starts, so a warehouse value does not overwrite a rep’s manual edit.
What does setting up the BigQuery HubSpot integration involve?
Seven phases, each closed by a client sign-off: a use-case inventory, the native-or-custom decision, access and governance (a dedicated service account approved by the client’s Google Cloud admin), the HubSpot data model, the build, backfill, and workflows with a two-week parallel run before launch.
How long does the integration take and what does it cost?
Timeline and cost depend on the data sets, fields and flows in scope (for example how much HubSpot’s own BigQuery integration covers, the write rules and custom objects needed, and BigQuery query cost). Campaign Creators confirms these in discovery and provides a fixed scope before the build starts.
Ready to Get More From HubSpot?
Whether you’re implementing HubSpot, optimizing what you already have, connecting systems, or scaling your customer experience, we’ll help you figure out the right next step.
.png?width=1920&height=553&name=cc-logo-color%20(2024).png)