Skip to main content
Who is this guide for? This guide is for administrators and data engineers planning to connect a data warehouse to Quivly for product usage data.

​
Why Connect a Data Warehouse?

While CRM and billing integrations provide customer and revenue data, data warehouse integrations unlock your product usage data - the most powerful signal for predicting churn and identifying growth opportunities. What you can track:
  • Daily/weekly active users per customer
  • Feature adoption and usage frequency
  • API calls and volume metrics
  • Product engagement trends
  • Custom usage metrics specific to your product
Impact on customer success:
  • Identify customers not using key features
  • Detect usage declines before customers churn
  • Find expansion opportunities (high usage = ready to upgrade)
  • Understand which features drive retention

​
Supported Data Warehouses

Quivly supports connections to the following data warehouses:

BigQuery

Google Cloud Platform
  • Serverless, highly scalable
  • Great for large datasets
  • Authentication via service account
Setup Guide →

Snowflake

Snowflake Data Cloud
  • Enterprise-grade data warehouse
  • Multi-cloud support
  • Authentication via username/password or key-pair
Setup Guide →

PostgreSQL

PostgreSQL Database
  • Open-source, self-hosted or managed
  • Great for smaller datasets
  • Authentication via connection string
Contact support for setup

MySQL

MySQL Database
  • Popular open-source database
  • Widely supported
  • Authentication via connection string
Contact support for setup

Redshift

Amazon Redshift
  • AWS-native data warehouse
  • Integrates with AWS ecosystem
  • Authentication via IAM or credentials
Contact support for setup

Databricks

Databricks Lakehouse
  • Unified data and AI platform
  • Delta Lake integration
  • Authentication via personal access token
Contact support for setup

​
Data Format: Long vs Wide

Before connecting your warehouse, understand the two common data formats for usage data:

​
Long Format (Event-Based)

Structure: One row per event Use when: You track individual user actions (clicks, page views, API calls) Example: 
timestamp           | customer_id | user_id  | event_name    | properties
--------------------+-------------+----------+---------------+------------
2024-01-15 10:23:45 | cust_123    | user_456 | page_viewed   | {"page": "dashboard"}
2024-01-15 10:24:12 | cust_123    | user_456 | button_clicked| {"button": "export"}
2024-01-15 10:25:03 | cust_123    | user_789 | api_called    | {"endpoint": "/customers"}
Pros:
  • Flexible (can aggregate any way you want)
  • Granular insights
  • Easy to add new event types
Cons:
  • Large table sizes
  • Requires aggregation on every query
  • Higher query costs

​
Wide Format (Aggregated Metrics)

Structure: One row per time period with metrics as columns Use when: You pre-aggregate usage data (daily/weekly rollups) Example: 
date       | customer_id | daily_active_users | api_calls | reports_generated
-----------+-------------+-------------------+-----------+------------------
2024-01-15 | cust_123    | 12                | 450       | 8
2024-01-15 | cust_456    | 5                 | 120       | 2
2024-01-16 | cust_123    | 15                | 523       | 12
Pros:
  • Faster queries (no aggregation needed)
  • Smaller table sizes
  • Lower query costs
Cons:
  • Less flexible (metrics fixed)
  • Must decide aggregations upfront
  • Harder to add new metrics
Recommendation: Use wide format if you already aggregate usage in your ETL pipeline. Use long format if you want maximum flexibility and have raw event data.
See detailed examples in the BigQuery Integration Guide.

​
Prerequisites for All Warehouses

Before connecting any data warehouse:
1

Prepare Your Usage Data

Ensure you have usage data in a table with:
  • Customer identifier (customer ID, account ID, or domain)
  • Timestamp or date field
  • Event names or metric columns
  • Optional: User identifier, event properties
Run a test query to verify data exists and is structured correctly.
2

Create Read-Only Access

For security, create a dedicated user/service account with read-only permissions:BigQuery: Service account with “BigQuery Data Viewer” roleSnowflake: Database user with SELECT permission on usage tablesPostgreSQL/MySQL: User with SELECT permission
Never give Quivly write permissions. Read-only access ensures we can’t accidentally modify your data.
3

Test Connectivity

Verify Quivly can reach your data warehouse:
  • If cloud-hosted: Usually no firewall changes needed
  • If self-hosted: Whitelist Quivly’s IP addresses
  • If VPN/private network: Set up secure tunnel or VPN connection
Contact support for Quivly’s IP addresses to whitelist.
4

Plan Sync Frequency

Decide how often Quivly should sync usage data:
FrequencyBest ForAPI/Query Costs
Every 6 hoursReal-time usage trackingHigher
Every 12 hoursNear real-time trackingMedium
DailyCost-effective, sufficient for mostLower
ManualInfrequent updates, testingLowest
Start with daily syncs. You can always increase frequency later.

​
Sync Behavior Across Warehouses

​
How Syncs Work

All warehouse integrations follow the same pattern: Initial Sync:
  1. Quivly queries your usage table for the last 90 days (configurable)
  2. Data is ingested and processed
  3. Usage metrics are calculated per customer
  4. Health scores are updated
Incremental Syncs:
  1. Quivly queries only new data since last sync (using timestamp/date field)
  2. New data is appended
  3. Metrics are recalculated
  4. Health scores are updated
Deduplication:
  • Long format: Deduplicates based on (timestamp, customer_id, user_id, event_name)
  • Wide format: Deduplicates based on (date, customer_id) - newer values overwrite

​
Query Examples

Long format incremental query: 
SELECT timestamp, customer_id, user_id, event_name, properties
FROM your_table
WHERE timestamp > '2024-01-15 14:30:00 UTC'
ORDER BY timestamp ASC
LIMIT 10000;
Wide format incremental query: 
SELECT date, customer_id, daily_active_users, api_calls, reports_generated
FROM your_table
WHERE date > '2024-01-15'
ORDER BY date ASC;

​
Security and Permissions

​
What Permissions Does Quivly Need?

WarehouseRequired PermissionsWhy
BigQuerybigquery.tables.get, bigquery.tables.getData, bigquery.jobs.createRead table schema, query data, run jobs
SnowflakeSELECT on usage tablesQuery usage data
PostgreSQLSELECT on usage tablesQuery usage data
MySQLSELECT on usage tablesQuery usage data
RedshiftSELECT on usage tablesQuery usage data

​
Data Security

How Quivly protects your data:
  • Read-only access (no write permissions)
  • Encrypted connections (TLS/SSL)
  • Credentials stored encrypted at rest
  • Row-level security (organization isolation)
  • No data shared across customers
What data is synced:
  • Only usage data from tables you configure
  • No PII unless explicitly mapped
  • Data is aggregated (not raw event-level details)
What data is NOT synced:
  • Other tables or schemas
  • User passwords or sensitive fields
  • Financial transaction details (unless explicitly configured)
Need help choosing a warehouse or setting up your data?