How to connect Snowflake to Whatagraph

Whatagraph connects to Snowflake using key-pair authentication, no passwords involved. Once connected, each schema in your Snowflake account becomes a selectable integration account, and each table inside it becomes a source you can build reports from.

What you'll need before you start

A Snowflake account on AWS, Azure, or GCP
A Snowflake user with ACCOUNTADMIN privileges (or any role that can CREATE USER, CREATE ROLE, and grant warehouse and database access)
A terminal with openssl installed

Step 1: Create a dedicated Snowflake user, role, and warehouse

We recommend setting up a dedicated user, role, and warehouse for Whatagraph so the connector has tightly scoped permissions and can be revoked cleanly if needed.

Open a Snowflake worksheet and run the following:

USE ROLE ACCOUNTADMIN;

-- Warehouse Whatagraph will use to run SELECTs

CREATE WAREHOUSE IF NOT EXISTS WHATAGRAPH_WH
  WITH WAREHOUSE_SIZE = 'XSMALL'
       AUTO_SUSPEND = 60
       AUTO_RESUME = TRUE
       INITIALLY_SUSPENDED = TRUE;

-- Role Whatagraph will operate under

CREATE ROLE IF NOT EXISTS WHATAGRAPH_ROLE;

-- Grant the role access to the warehouse and your database
-- The role needs USAGE on the warehouse to run queries, 
-- plus read access to the databases and schemas you want Whatagraph to report on.

GRANT USAGE ON WAREHOUSE WHATAGRAPH_WH TO ROLE WHATAGRAPH_ROLE;

-- Grant database access. 
-- Repeat the following 7 lines for each additional database, replacing <YOUR_DB>. 

GRANT USAGE ON DATABASE <YOUR_DB>                       TO ROLE WHATAGRAPH_ROLE; 
GRANT USAGE ON ALL SCHEMAS IN DATABASE <YOUR_DB>        TO ROLE WHATAGRAPH_ROLE;
GRANT SELECT ON ALL TABLES IN DATABASE <YOUR_DB>        TO ROLE WHATAGRAPH_ROLE;
GRANT SELECT ON ALL VIEWS  IN DATABASE <YOUR_DB>        TO ROLE WHATAGRAPH_ROLE;
GRANT USAGE ON FUTURE SCHEMAS IN DATABASE <YOUR_DB>     TO ROLE WHATAGRAPH_ROLE;
GRANT SELECT ON FUTURE TABLES IN DATABASE <YOUR_DB>     TO ROLE WHATAGRAPH_ROLE;
GRANT SELECT ON FUTURE VIEWS  IN DATABASE <YOUR_DB>     TO ROLE WHATAGRAPH_ROLE;

-- Service user (no password — key-pair auth only)

CREATE USER IF NOT EXISTS WHATAGRAPH_USER
  DEFAULT_ROLE      = WHATAGRAPH_ROLE
  DEFAULT_WAREHOUSE = WHATAGRAPH_WH
  MUST_CHANGE_PASSWORD = FALSE;

GRANT ROLE WHATAGRAPH_ROLE TO USER WHATAGRAPH_USER;

Replace <YOUR_DB> with the database you want to report on. If you need Whatagraph to access multiple databases, repeat the seven GRANT … ON DATABASE blocks for each one.

Note: Whatagraph enumerates schemas by running SHOW SCHEMAS IN ACCOUNT. It only returns schemas the role can see, so the grants above control what's visible in Whatagraph.

Step 2: Generate an RSA key pair

Whatagraph authenticates using signed JWTs (RS256). Run the following in your terminal to generate a key pair:

# Encrypted private key (recommended). You'll be asked to set a passphrase.
openssl genrsa 2048 \
  | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out whatagraph_key.p8

# Public key derived from the private key
openssl rsa -in whatagraph_key.p8 -pubout -out whatagraph_key.pub

Once generated, open whatagraph_key.pub, copy everything between the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines (no header, no footer, no line breaks), and register it on the Snowflake user:

ALTER USER WHATAGRAPH_USER SET RSA_PUBLIC_KEY = 'MIIBIj...IDAQAB';

To confirm it registered correctly, run:

DESC USER WHATAGRAPH_USER;

Look for RSA_PUBLIC_KEY_FP in the output - that's the SHA-256 fingerprint Whatagraph will use when signing JWTs.

Keep whatagraph_key.p8 (the private key file) - you'll paste its contents into Whatagraph in the next step.

Step 3: Add the connection in Whatagraph

Step 1. Go to Data -> Sources and click "Connect new source"

Step 2. Select Snowflake from the list.

Step 3. Fill in the connection fields:

Field	What to enter	Example	Required
Account identifier	Your Snowflake account locator. Find it in the Snowflake UI under Admin → Accounts → Locator, or copy it from any account URL.	`xy12345.us-east-1`	Yes (read-only after creation)
Username	The Snowflake service user from Step 1. Snowflake stores usernames in uppercase unless they were created with quoted lowercase identifiers — use the form Snowflake stores.	`WHATAGRAPH_USER`	Yes
Private key	The full contents of `whatagraph_key.p8`, including the `-----BEGIN ENCRYPTED PRIVATE KEY-----` and `-----END ENCRYPTED PRIVATE KEY-----` lines.	(paste PEM)	Yes
Passphrase	The passphrase you set when generating the key. Leave blank if your private key is unencrypted.	—	Optional
Warehouse	The warehouse Whatagraph will use to run queries.	`WHATAGRAPH_WH`	Yes
Role	The role to assume. If left blank, Snowflake will fall back to the user's default role.	`WHATAGRAPH_ROLE`	Optional

Step 4. Click "Add an account"

Whatagraph posts SELECT 1 to https://<account_identifier>.snowflakecomputing.com/api/v2/statements, signed with your private key. If the test passes, the connection is saved, and Whatagraph enumerates your schemas - each <DATABASE>.<SCHEMA> becomes a separate integration account, and each table inside becomes a source you can connect.

Step 4: Select schemas and tables to report on

Step 1. After connecting, Whatagraph presents every schema that the role can see. Select the schemas (<DATABASE>.<SCHEMA>) that you want to report on

Step 2. For each selected schema, Whatagraph surfaces every table as a source you can connect to use in the reports.

When you add a Snowflake table source to a widget, Whatagraph maps your columns to dimensions and metrics automatically:

Metrics - all numeric columns (NUMBER, DECIMAL, FLOAT, INTEGER, BIGINT, SMALLINT, TINYINT, DOUBLE, REAL). The default aggregation is SUM(<column>). Columns ending in _SK are treated as surrogate keys and excluded.
Date dimensions - columns whose type starts with DATE or TIMESTAMP*.
String dimensions - everything else.

The first DATE or TIMESTAMP* column found in a table is automatically set as the source's date column - the column Whatagraph uses to filter by date range. You can change it later in source settings.

Note: If you need to aggregate a _SK column, expose it as a renamed column in a Snowflake view.

How data is fetched

Whatagraph queries Snowflake's SQL API asynchronously. For each widget refresh:

Whatagraph submits a SELECT against your table, restricted to the widget's date range and any filters you've added.
Snowflake returns a statementHandle and a status code. Whatagraph polls /api/v2/statements/<handle> until the status flips from 333334 (still running) to 090001 (succeeded).
The result rows are mapped onto the widget's dimensions and metrics.

JWTs are minted per request with a 9-minute TTL - there's no long-lived token sitting around. The private key never leaves Whatagraph's encrypted credential store.

Troubleshooting

Snowflake error code	What you'll see in Whatagraph	Fix
`390144`	"The public key fingerprint registered on the user does not match the private key you provided."	The private key and the registered public key don't match. Run `DESC USER <username>;`, compare `RSA_PUBLIC_KEY_FP` to the fingerprint of `whatagraph_key.pub`, and re-run `ALTER USER … SET RSA_PUBLIC_KEY = …`.
`390304`	"The JWT is expired."	Clock skew between your server and Snowflake. If you're self-hosting, verify your server clock. Otherwise, contact support.
`394300`	"Snowflake user authentication failed."	Username casing mismatch. Snowflake stores usernames uppercase unless they were created with quoted lowercase identifiers - double-check the username you entered.
`390139`	"Your IP is not allowed by the Snowflake network policy on this user."	Your account has a `NETWORK_POLICY` that blocks Whatagraph's IPs. Add Whatagraph's egress IP range to `ALLOWED_IP_LIST`.
`002043`	"The role does not have USAGE on the warehouse."	Run `GRANT USAGE ON WAREHOUSE <wh> TO ROLE <role>;` in Snowflake.
`5xx`	"Snowflake is temporarily unavailable. Try again later."	Transient error - Whatagraph retries automatically.

If you see a generic 4xx not listed above, check Snowflake's query history for the exact code field - it will pinpoint the cause.

Limitations

Password authentication is not supported. The connector uses key-pair JWT only.
Snowflake compute and storage costs are billed by Snowflake, not Whatagraph. Each widget refresh runs a query through your warehouse. Use a small warehouse (XSMALL) with a short auto-suspend (AUTO_SUSPEND = 60) to keep costs low.
There is no incremental fetch. Every widget refresh runs a fresh query against your table. If you have very large fact tables, consider building a pre-aggregated view in Snowflake and pointing Whatagraph at the view instead.

How to Connect Apple Search Ads to Whatagraph