Connecting Snowflake

Read the concepts first for push vs pull and snapshots. This page covers what is specific to Snowflake.

Where the data comes from

Snowflake keeps usage history in the shared, read-only SNOWFLAKE database, mostly the ACCOUNT_USAGE schema: warehouse metering, query history, query attribution (cost per query), and Cortex AI usage. We read only these views. Access to them is a distinct privilege from access to your own databases.

ACCOUNT_USAGE is not real-time. Views can lag by a few hours, so the newest activity may be missing from the latest snapshot.

Option A — Push (recommended)

You run one script in a Snowflake worksheet. It creates a stored procedure and a daily task inside your account; the task sends the usage metadata to us.

You (ACCOUNTADMIN)                    Your Snowflake account                Teksoptima
──────────────────                    ──────────────────────                ──────────
Run the setup script ───────────────► creates:
                                       • NETWORK RULE  (egress to ONE host)
                                       • SECRET        (the upload token)
                                       • EXTERNAL ACCESS INTEGRATION
                                       • PROCEDURE     (reads ACCOUNT_USAGE)
                                       • TASK          (runs daily, UTC)
                                                │
                                   daily task runs the procedure
                                                │ gzip'd JSON over HTTPS ─► validated, stored

What each object is for

Object	Concept
Network rule	Snowflake blocks outbound traffic by default. This rule allows exactly one destination: ours.
Secret	Holds the upload token inside Snowflake, so it is not written in the procedure's code.
External access integration	The gate that ties the rule and the secret to the procedure. Without it the procedure can't call out.
Procedure	Plain Python/SQL you can read. Runs the queries, builds the payload, posts it.
Task	The schedule. Suspend or drop it and uploads stop.

Why `ACCOUNTADMIN`

The setup creates account-level objects (integrations, network rules), which only ACCOUNTADMIN can do. The procedure runs as its owner, who can already read ACCOUNT_USAGE, so you do not create a custom role or grant IMPORTED PRIVILEGES for push. You can review the whole script before running it.

Run it

In Teksoptima choose Connect Snowflake → Push.
Copy the generated script (it contains your upload token — treat it like a password).
In Snowflake, open a worksheet, select Run All (the single-line play button runs only the line under your cursor), as ACCOUNTADMIN.
Back in Teksoptima, the first snapshot appears once the task has run. You can also trigger the task manually from Snowflake.

Don't want outbound access?

If your security policy forbids external access, use the payload query: the same datasets as a single SELECT returning one JSON value. You run it yourself and submit the result. It is manual, so the data is only as fresh as your last run.

Stopping it

Drop the task and objects, or regenerate the upload token in Teksoptima — the old one stops working immediately. Disconnecting the workspace deletes our copy.

Option B — Pull with OAuth

In this mode Teksoptima signs in to your account on your behalf. This uses Snowflake OAuth, and it has one concept that surprises people.

The key idea: the OAuth client lives in your account

A Snowflake OAuth client is an object created inside one account (CREATE SECURITY INTEGRATION). The client ID and secret it generates only work for that account. That means:

We can't register one Teksoptima client with Snowflake and use it for everyone.
Each customer creates their own and gives us the ID and secret, which we store encrypted against your connection only.
Snowflake does not offer a way to skip this step, even for large partners.

Moving parts

Piece	What it is
Security integration	The OAuth client you create. Holds the redirect URL, token lifetime and `ENABLED = TRUE`.
Client ID & secret	Printed by `DESCRIBE SECURITY INTEGRATION` and `SYSTEM$SHOW_OAUTH_CLIENT_SECRETS`. You paste them into the wizard.
Redirect URL	Where Snowflake sends you back after you approve. It must match character for character; a mismatch is the most common failure.
Read-only role	`COST_OPT_APP_ROLE`, with `IMPORTED PRIVILEGES` on the `SNOWFLAKE` database and `MONITOR USAGE`.
Small warehouse	`COST_OPT_APP_WH` (X-Small), so our queries are separately visible in your own cost reporting.
Refresh token	After you approve, Snowflake issues a token valid up to 90 days that we use to get new access tokens. Stored encrypted.

The wizard, step by step

Account identifier. Your account, in the form orgname-accountname (or the legacy locator). Find it in Snowsight under your account menu.
Run the setup SQL. The wizard shows it with your redirect URL filled in. Run it once as ACCOUNTADMIN, with Run All. Paste the client ID and secret back.
Approve access. You're sent to Snowflake's consent screen, then back to us.
Grants check. We verify the role can read ACCOUNT_USAGE and has MONITOR USAGE, and tell you which grant is missing if not.
First sync. We run the queries and store the first snapshot.

Things that commonly go wrong

Symptom	Cause
"OAuth client integration with the given client id is not found"	The ID/secret came from a different account than the identifier you entered.
Redirect error after consent	The redirect URL in the integration differs from the one in the wizard.
Consent works, grants check fails	Your user's default role isn't `COST_OPT_APP_ROLE`, or only one statement of the script ran.
Connection stops after ~90 days	The refresh token expired; reconnect to re-approve.

Undoing it

The setup SQL has a matching teardown: drop the integration, role and warehouse. Doing so cuts our access immediately.

Which should I pick?

Push if you can run a script once and are comfortable with a daily task. No credential of yours is held by us, and nothing needs matching or rotating.
Pull if you'd rather not run a job in your account and accept that we hold an encrypted refresh token, renewed every ≤90 days.