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?

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:
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. Go to Settings → Integrations, click the BigQuery card, and open the Configure tab
  2. Click New Connection — BigQuery supports multiple named connections
  3. Fill in: Connection Name, Project ID, Dataset Name (optional, needed for table browsing), and paste your Service Account Key JSON
  4. Click Test Connection — it must succeed before you can connect
  5. Click Connect Database
6

Add usage tables

In the Data Tables section, click Add Table and pick the tables and columns that hold usage data.
7

Map metrics

Metric mapping (which columns become which metrics, customer identifier, sync schedule) is configured under Settings → Objects → Product Usage.
8

Verify

Open a customer profile and check the Usage tab once the first sync has run.

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