> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quivly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# BigQuery

> Connect your BigQuery data warehouse to sync product usage metrics

<Info>
  **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.
</Info>

***

## What Data Syncs from BigQuery?

| Data Type              | Maps to Quivly | What Syncs                                           |
| ---------------------- | -------------- | ---------------------------------------------------- |
| **Usage Events**       | Product Usage  | Feature usage, page views, API calls, user actions   |
| **Aggregated Metrics** | Usage Metrics  | Daily active users, session counts, feature adoption |
| **Time-series Data**   | Trend Analysis | Historical 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

<Steps>
  <Step title="Open Google Cloud Console">
    1. Go to [console.cloud.google.com](https://console.cloud.google.com)
    2. Select your GCP project (or create one)
  </Step>

  <Step title="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**
  </Step>

  <Step title="Grant BigQuery Permissions">
    Add the following roles to the service account:

    | Role                 | Purpose                        |
    | -------------------- | ------------------------------ |
    | BigQuery Data Viewer | Read access to tables and data |
    | BigQuery Job User    | Ability to run queries         |

    <Check>
      Quivly only requires **read permissions**. We never write data to your BigQuery tables.
    </Check>

    Click **Continue**, then **Done**.
  </Step>

  <Step title="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

    <Warning>
      Store this JSON file securely. It contains credentials to access your BigQuery data. Never commit it to version control.
    </Warning>
  </Step>

  <Step title="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**
  </Step>

  <Step title="Add usage tables">
    In the **Data Tables** section, click **Add Table** and pick the tables and columns that hold usage data.
  </Step>

  <Step title="Map metrics">
    Metric mapping (which columns become which metrics, customer identifier, sync schedule) is configured under **Settings → Objects → Product Usage**.
  </Step>

  <Step title="Verify">
    Open a customer profile and check the **Usage** tab once the first sync has run.
  </Step>
</Steps>

***

## 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

<Warning>
  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.
</Warning>