> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Snowflake Metrics
> Query Snowflake tables as live external metrics in Costory. Reuse the billing integration, grant one database, then pick tables in Advanced Explorer.
Active users, sessions, or warehouse activity often already live in Snowflake, while cloud spend lives in Costory. Grant the existing billing role a metrics database, then query those tables live in [Advanced Explorer](/setup/usage-metrics#query-after-you-connect).
Reuse the Costory Snowflake user and warehouse. Pick a table, date field, and value column. Costory queries through the Snowflake SQL API and does not copy table data.
Use this when the signal already lives in Snowflake:
* Business metrics such as active users, sessions, or devices
* Technical metrics for [shared cost allocation](/features/tagging/shared-cost-allocation), such as query counts or bytes scanned by team
The [Snowflake billing](/setup/billing/snowflake) connection stays on the `SNOWFLAKE` database. Metrics are a second grant on databases you choose.
You need an existing Snowflake integration (user, role, and warehouse). If none exists, follow [Snowflake billing setup](/setup/billing/snowflake), then come back here. Costory does not create a second user or warehouse for metrics.
Go to [Integrations](https://app.costory.io/integration), click **+ Add integration**, choose **Snowflake**, then **Metrics**. The connect URL is `/integration/new/snowflake/metrics`.
Under **Existing integration**, pick the Snowflake connection already used for billing. **Already visible** lists databases you granted earlier.
Enter the **Database** name Costory should catalog (for example `ANALYTICS`). Run the grant SQL Costory shows as **ACCOUNTADMIN**. The default role is **COSTORY** unless your integration uses another role.
```sql theme={null}
GRANT USAGE ON DATABASE ANALYTICS TO ROLE COSTORY;
GRANT USAGE ON ALL SCHEMAS IN DATABASE ANALYTICS TO ROLE COSTORY;
GRANT SELECT ON ALL TABLES IN DATABASE ANALYTICS TO ROLE COSTORY;
GRANT SELECT ON ALL VIEWS IN DATABASE ANALYTICS TO ROLE COSTORY;
GRANT SELECT ON FUTURE TABLES IN DATABASE ANALYTICS TO ROLE COSTORY;
GRANT SELECT ON FUTURE VIEWS IN DATABASE ANALYTICS TO ROLE COSTORY;
```
Replace `ANALYTICS` and `COSTORY` with the identifiers on the connect screen if they differ.
Click **Validate**. Costory checks that it can list tables in that database. **Save** stays disabled until validation succeeds. Tables in the database then appear as external metrics.
**Save** stays disabled until validation succeeds. You can add more databases later on the same integration. Each grant is additive.
## Example table schema
Your table needs a date or timestamp column and at least one numeric metric column. Optional string columns work as group-by dimensions.
```sql theme={null}
CREATE TABLE MY_BUSINESS_DB.ANALYTICS.MONTHLY_BUSINESS_METRICS (
METRIC_DATE DATE,
ACTIVE_CUSTOMERS NUMBER,
NEW_CUSTOMERS NUMBER,
ARR_EUR NUMBER
);
```
Common metrics to query:
* Product analytics: daily or monthly active users, sessions, sign-ups
* Business KPIs: orders, customers, revenue snapshots already in Snowflake
* Warehouse activity: query counts or bytes scanned by warehouse, team, or query tag
## Table requirements
| Requirement | Details |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Catalog** | Tables must live in a database listed under **Already visible** on the Snowflake metrics connection. |
| **Numeric column** | At least one numeric type, such as `NUMBER`, `DECIMAL`, `FLOAT`, or `INTEGER`. |
| **Date column** | At least one date or timestamp type: `DATE`, `DATETIME`, or `TIMESTAMP` (including `TIMESTAMP_NTZ`). |
| **Identifier** | Metric ids in Explorer are `DATABASE.SCHEMA.TABLE`. |
## Query after you connect
Queries run live through the Snowflake SQL API.
Click **Explore your data**, then switch **Classic** to **Advanced**. Classic greys out non-cost metrics.
Click **+ Add Metric**. Use the **integrations** chip, then pick the Snowflake source. Helper text describes it as a live external usage metric.
Pick a **table**, then set **Date field**, **Value column**, **Aggregate** (`SUM`, `AVG`, `MAX`, or `MIN`), **Gap fill** (**FORWARD FILL**, **ZERO**, or **LINEAR**), and optional **Group by**.
In this example, `MY_BUSINESS_DB.ANALYTICS.MONTHLY_BUSINESS_METRICS` uses date `METRIC_DATE`, value `ACTIVE_CUSTOMERS`, **SUM**, **FORWARD FILL**, and **Last 3 months**. The metric column picker lists every numeric column on the table (`ARR_EUR`, `NEW_CUSTOMERS`, and so on).
Optionally click **+ Add Metric** for **Cost**, then **+ Add Formula** such as `b / a`. See [Unit Economics](/features/unit-economics).
Use the series in a [virtual dimension](/features/tagging/dimensions#virtual-dimensions) or [shared cost allocation](/features/tagging/shared-cost-allocation) rule after you can query it in Explorer.
## Metric configuration
| Field | Description |
| ---------------- | ------------------------------------------------------------------------------------- |
| **Table** | Fully qualified Snowflake table (`DATABASE.SCHEMA.TABLE`). |
| **Date field** | Column used for the time series. |
| **Value column** | Column with the metric value. |
| **Aggregate** | How values are rolled up: **SUM**, **AVG**, **MAX**, or **MIN**. |
| **Gap fill** | How missing dates are filled: **FORWARD FILL**, **ZERO**, or **LINEAR**. |
| **Group by** | Optional string column to split the metric (for example product, team, or warehouse). |
## Troubleshooting
| Issue | What to check |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **No existing integration** | Connect Snowflake for billing first, then open **Metrics** on the same tile. |
| **Validate fails** | Run the grant SQL as **ACCOUNTADMIN**. Confirm the database name matches Snowflake (quoted names are case-sensitive). |
| **Table does not appear** | Confirm the table is in a visible database, has both a date and a numeric column, and is not in `INFORMATION_SCHEMA`. |
| **Chart is empty** | Pick a different table and change **Period**. Confirm the date column has rows in that range. |
Not supported.
## Related pages
Create the key-pair integration this connector reuses.
Combine Snowflake metrics with cloud cost in Explorer formulas.
Split shared infrastructure using a Snowflake usage metric.
Browse all supported external metric sources.