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

# Snowflake

> Connect your Snowflake data warehouse to sync product usage metrics

<Info>
  **Who is this guide for?** This guide is for **administrators and data engineers** setting up Snowflake. You'll need admin access to your Snowflake account (ACCOUNTADMIN or SECURITYADMIN role).
</Info>

***

## What You'll Need

Before you begin, ensure you have:

* **Admin access** to your Snowflake account (ACCOUNTADMIN or SECURITYADMIN role)
* **Permissions** to create users, roles, and grant warehouse access
* **Knowledge** of which databases and schemas contain your customer usage data

***

## Configuration Requirements

Quivly requires the following information to connect:

| Configuration           | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| **Connection Name**     | A label for this connection in Quivly                         |
| **Account**             | Your Snowflake account identifier (e.g., `xy12345.us-east-1`) |
| **Warehouse**           | The compute warehouse for queries                             |
| **Database**            | The database containing usage data                            |
| **Schema**              | Schema to use (default `PUBLIC`)                              |
| **Role**                | Snowflake role to use (default `PUBLIC`)                      |
| **Username / Password** | The dedicated Quivly service user's credentials               |

***

## Setup Instructions

<Steps>
  <Step title="Create a Dedicated Role for Quivly">
    Run the following SQL in your Snowflake worksheet:

    ```sql theme={null}
    -- Create a dedicated role for Quivly
    CREATE ROLE IF NOT EXISTS QUIVLY_READER_ROLE;

    -- Grant usage on the warehouse Quivly will use
    GRANT USAGE ON WAREHOUSE <your_warehouse> TO ROLE QUIVLY_READER_ROLE;
    ```
  </Step>

  <Step title="Grant Database and Schema Access">
    Grant read-only access to the databases and schemas containing your customer data:

    ```sql theme={null}
    -- Grant access to a specific database
    GRANT USAGE ON DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;

    -- Grant access to schemas within the database
    GRANT USAGE ON ALL SCHEMAS IN DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;
    GRANT USAGE ON FUTURE SCHEMAS IN DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;

    -- Grant SELECT on tables and views
    GRANT SELECT ON ALL TABLES IN DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;
    GRANT SELECT ON FUTURE TABLES IN DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;
    GRANT SELECT ON ALL VIEWS IN DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;
    GRANT SELECT ON FUTURE VIEWS IN DATABASE <your_database> TO ROLE QUIVLY_READER_ROLE;
    ```

    <Tip>
      For tighter security, scope these grants to specific schemas rather than the entire database.
    </Tip>
  </Step>

  <Step title="Create a Service User">
    ```sql theme={null}
    -- Create a dedicated user for Quivly
    CREATE USER IF NOT EXISTS QUIVLY_SERVICE_USER
      PASSWORD = '<strong_password>'
      DEFAULT_ROLE = QUIVLY_READER_ROLE
      DEFAULT_WAREHOUSE = <your_warehouse>
      MUST_CHANGE_PASSWORD = FALSE;

    -- Assign the role to the user
    GRANT ROLE QUIVLY_READER_ROLE TO USER QUIVLY_SERVICE_USER;
    ```

    <Warning>
      Use a strong, unique password. The connection form authenticates with username and password.
    </Warning>
  </Step>

  <Step title="Find Your Account Identifier">
    Your account identifier is in your Snowflake URL:

    **Format:** `https://<account_identifier>.snowflakecomputing.com`

    **Examples:**

    * URL: `https://xy12345.us-east-1.snowflakecomputing.com` → Account: `xy12345.us-east-1`
    * URL: `https://mycompany.snowflakecomputing.com` → Account: `mycompany`

    <Info>
      Include the region if present (e.g., `xy12345.us-east-1`).
    </Info>
  </Step>

  <Step title="Connect in Quivly">
    1. Go to **Settings → Integrations**, click the **Snowflake** card, and open the **Configure** tab
    2. Fill in the connection name, account, warehouse, database, schema, role, username, and password
    3. Click **Test Connection** — it must succeed before you can connect
    4. Click **Connect Database**
  </Step>
</Steps>

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

***

## Snowflake Structure

Snowflake organizes data in a three-level hierarchy:

* **Database** — Top-level container for your data
  * **Schema** — Logical grouping of tables, views, and objects
    * **Table/View** — Your actual data with rows and columns

Example: `ANALYTICS_DB` → `PRODUCT` → `EVENTS`

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Insufficient privileges errors">
    Verify that `QUIVLY_READER_ROLE` has proper grants:

    ```sql theme={null}
    SHOW GRANTS TO ROLE QUIVLY_READER_ROLE;
    ```

    Ensure USAGE grants on warehouse, database, and schema, plus SELECT on tables.
  </Accordion>

  <Accordion title="Connection timeout">
    Ensure your Snowflake account allows connections from Quivly's IP addresses. Check **Admin → Security → Network Policies** if you have IP allowlisting enabled.

    Contact support for Quivly's IP addresses.
  </Accordion>

  <Accordion title="Tables not appearing">
    Confirm tables exist in the granted schemas and that FUTURE grants are in place for newly created tables.
  </Accordion>

  <Accordion title="Warehouse suspended errors">
    The warehouse may be set to auto-suspend. Either increase the auto-suspend timeout or ensure the warehouse is running when Quivly syncs. Quivly will attempt to resume suspended warehouses automatically if the user has OPERATE privileges:

    ```sql theme={null}
    GRANT OPERATE ON WAREHOUSE <your_warehouse> TO ROLE QUIVLY_READER_ROLE;
    ```
  </Accordion>
</AccordionGroup>

***

## Cost Optimization

Snowflake charges for compute (warehouse usage). To manage costs:

* Use an **X-Small warehouse** — sufficient for most sync operations
* Set **auto-suspend** to 1 minute to minimize idle time
* Consider a dedicated warehouse for Quivly to track usage separately

```sql theme={null}
CREATE WAREHOUSE IF NOT EXISTS QUIVLY_WH
  WAREHOUSE_SIZE = 'X-SMALL'
  AUTO_SUSPEND = 60
  AUTO_RESUME = TRUE;

GRANT USAGE, OPERATE ON WAREHOUSE QUIVLY_WH TO ROLE QUIVLY_READER_ROLE;
```

***

## Security Notes

* Quivly only requests read-only (SELECT) access
* Credentials are encrypted at rest and in transit
* Revoke access anytime by dropping the user or revoking the role

***

<Info>
  **Need help?**

  * Email support: [support@quivly.ai](mailto:support@quivly.ai)
  * Book a call: [Schedule onboarding](https://cal.com/chandrika)
</Info>