Skip to main content
Who is this guide for? This guide is for administrators setting up the BigQuery integration. You’ll need admin access to your Google Cloud Platform project to create service accounts.

​
What Data Syncs from BigQuery?

Data TypeMaps to QuivlyWhat Syncs
Usage EventsProduct UsageFeature usage, page views, API calls, user actions
Aggregated MetricsUsage MetricsDaily active users, session counts, feature adoption
Time-series DataTrend AnalysisHistorical usage patterns for health scoring
Sync frequency: Every 6 hours

​
Prerequisites

  • Active Google Cloud Platform project
  • Admin or Owner role in GCP
  • Permission to create service accounts
  • BigQuery dataset with usage data ready

​
Step-by-Step Setup

1

Open Google Cloud Console

  1. Go to console.cloud.google.com
  2. Select your GCP project (or create one)
2

Create a Service Account

  1. Navigate to IAM & Admin → Service Accounts
  2. Click Create Service Account
  3. Enter a name: quivly-bigquery-reader
  4. Enter a description: “Service account for Quivly to read BigQuery usage data”
  5. Click Create and Continue
3

Grant BigQuery Permissions

Add the following roles to the service account:
RolePurpose
BigQuery Data ViewerRead access to tables and data
BigQuery Job UserAbility to run queries
Quivly only requires read permissions. We never write data to your BigQuery tables.
Click Continue, then Done.
4

Generate JSON Key

  1. In the service accounts list, find your quivly-bigquery-reader account
  2. Click the three-dot menu → Manage keys
  3. Click Add Key → Create new key
  4. Select JSON as the key type
  5. Click Create
  6. The JSON key file will download to your computer
Store this JSON file securely. It contains credentials to access your BigQuery data. Never commit it to version control.
5

Connect BigQuery in Quivly

  1. Log in to Quivly
  2. Go to Settings → Integrations
  3. Find BigQuery and click Set Up Integration
  4. Upload your JSON key file
  5. Select your dataset and table
  6. Map the required fields (customer ID, timestamp, event name)
  7. Click Install
6

Verify Sync

  1. Check the Logs tab to monitor sync progress
  2. Once complete, navigate to Customers and open a customer profile
  3. Go to the Usage tab to verify BigQuery data appears
Estimated sync time:
  • Small datasets (< 1M rows): 5-15 minutes
  • Medium datasets (1M-10M rows): 15-60 minutes
  • Large datasets (10M+ rows): 1-4 hours

​
BigQuery Hierarchy

Understanding the BigQuery structure helps with configuration:
  • Project: Your GCP project (auto-detected from JSON key)
  • Dataset: A collection of tables (you’ll select this in Quivly)
  • Table: Your usage data table (you’ll map fields from here)

​
Customer Matching

Quivly uses the customer ID field in your BigQuery table to link usage data with CRM customers. Example:
  • BigQuery row with customer_id: "cust_123"
  • Salesforce account with external ID cust_123
  • Result: Matched as the same customer
Ensure your BigQuery table has a reliable customer identifier that matches IDs in your CRM. Rows without valid customer IDs won’t appear in customer profiles.