> ## 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. # Overview > Connect your data warehouse to sync product usage metrics **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. There are two ways to send product usage to Quivly: connect a **data warehouse** (this guide) so Quivly queries it on a schedule, or push events directly with the [Push API](/integrations/product-usage/api-overview). Use whichever fits your stack — or both. *** ## 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: **Google Cloud Platform** * Serverless, highly scalable * Great for large datasets * Authentication via service account [Setup Guide →](/integrations/warehouses/bigquery) **Snowflake Data Cloud** * Enterprise-grade data warehouse * Multi-cloud support * Authentication via username/password [Setup Guide →](/integrations/warehouses/snowflake) Other warehouses (Redshift, PostgreSQL, MySQL, and more) aren't connectable in the app yet — email [support@quivly.ai](mailto:support@quivly.ai) if you need one, or push metrics from your own pipeline via the [Usage Push API](/integrations/product-usage/api-overview). *** ## 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:** ```sql theme={null} 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:** ```sql theme={null} 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](/integrations/warehouses/bigquery#understanding-data-formats-long-vs-wide). *** ## Prerequisites for All Warehouses Before connecting any data warehouse: 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. For security, create a dedicated user/service account with **read-only** permissions: **BigQuery:** Service account with "BigQuery Data Viewer" role **Snowflake:** Database user with SELECT permission on usage tables Never give Quivly write permissions. Read-only access ensures we can't accidentally modify your data. 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. Sync schedule is set later, in the usage mapping config under **Settings → Objects → Product Usage**: | Frequency | Best For | Query Costs | | ---------- | ----------------------------------- | ----------- | | **Hourly** | Near real-time tracking | Higher | | **Daily** | Cost-effective, sufficient for most | Lower | | **Weekly** | Slow-moving metrics | Lowest | | **Manual** | Infrequent updates, testing | Lowest | 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:** ```sql theme={null} 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:** ```sql theme={null} 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? | Warehouse | Required Permissions | Why | | -------------- | ------------------------------------------------------------------------ | --------------------------------------- | | **BigQuery** | `bigquery.tables.get`, `bigquery.tables.getData`, `bigquery.jobs.create` | Read table schema, query data, run jobs | | **Snowflake** | `SELECT` on usage tables | Query usage data | | **PostgreSQL** | `SELECT` on usage tables | Query usage data | | **MySQL** | `SELECT` on usage tables | Query usage data | | **Redshift** | `SELECT` on usage tables | Query 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?** * Email support: [support@quivly.ai](mailto:support@quivly.ai) * Book a call: [Schedule onboarding](https://cal.com/chandrika) * BigQuery guide: [BigQuery Setup →](/integrations/warehouses/bigquery)