Snowflake¶

Connect Adverity Atlas to your Snowflake account to query your data warehouse directly.

Prerequisites¶

A user or role that can read the data you want to query. Adverity Atlas only issues read queries against your tables, it does not create, modify, or drop them, so read access is all it needs.

Create a read-only role:

CREATE ROLE atlas_reader;
GRANT USAGE ON WAREHOUSE your_wh TO ROLE atlas_reader;
GRANT USAGE ON DATABASE your_db TO ROLE atlas_reader;
GRANT USAGE ON ALL SCHEMAS IN DATABASE your_db TO ROLE atlas_reader;
GRANT SELECT ON ALL TABLES IN DATABASE your_db TO ROLE atlas_reader;

CREATE USER atlas_svc
  PASSWORD = '...'
  DEFAULT_ROLE = atlas_reader
  DEFAULT_WAREHOUSE = your_wh;

What Adverity Atlas reads¶

A sync lists the objects in each schema you bind and records what kind each one is. Profiling then runs aggregate queries over the types it can profile, and those field statistics are what Chat and the glossary work from. An object that is discovered but not profiled is still queryable, it just carries no statistics.

Object type	Discovered and queryable	Profiled
Tables, including temporary and external tables	Yes	Yes
Views	Yes	No
Materialized views	Yes	Yes

Querying and profiling need the same access: SELECT on the objects you want available. Profiling adds no privilege of its own, it reads the same objects with aggregate queries. The Connection test on the wizard’s Test step proves exactly that access, in the order a sync needs it: connect, list the schemas, list the tables in the target schema, and read a row.

When a check fails on a privilege rather than a credential, Adverity Atlas names the GRANT that is missing: the role granted to the connecting user, USAGE on the warehouse, USAGE on the schema, or SELECT on the table.

Note

To show a dollar cost for Snowflake queries in Cost monitoring, the role also needs to read SNOWFLAKE.ACCOUNT_USAGE, where Snowflake records the compute credits each query used. Without that access, querying and profiling work as normal and the queries stay unpriced. Adverity Atlas checks this access again 24 hours after it finds it missing, so a grant you add later is picked up without reconnecting.

Authentication methods¶

Snowflake supports 3 authentication methods. Choose the one that matches your security posture.

Username & Password¶

Best for: Most setups and initial onboarding.

Credentials:

Field	Description
Username	e.g. `my_user`	Required
Password	Stored encrypted.	Required

Key Pair¶

Authenticate with an RSA private key registered on a Snowflake user.

Best for: Production, and organizations with key-only auth policies.

Credentials:

Field	Description
Username	e.g. `my_user`	Required
Private Key (PEM)	e.g. `-----BEGIN PRIVATE KEY-----` Stored encrypted.	Required
Passphrase	Stored encrypted.	Optional

Snowflake OAuth¶

Sign in to Snowflake itself and let it issue the token. You are redirected to a Snowflake consent screen once; Adverity Atlas stores the resulting tokens and renews them on its own from then on. No password is stored.

Best for: Organizations that would rather grant access through a sign-in than hand over a credential.

The token is issued for one Snowflake role, the one you set on the data source. It is not a general grant: it can only ever open sessions as that role, whatever else the signing-in user is entitled to.

It also carries the identity of whoever signed in, so queries run as that person. For unattended sync against a dedicated service user, Key Pair is usually the better fit: no consent, no expiry, and no borrowed identity.

Nothing is entered on the Authenticate step beyond the connection fields. You pick an OAuth client instead, a service config an admin creates once under Settings > Integrations > Service Configs and every Snowflake source can share.

Note

The Host field disappears for this method. The account is already named on the OAuth client’s authorization URL, so Adverity Atlas takes it from there rather than asking twice.

What an admin sets up first¶

One CREATE SECURITY INTEGRATION on the Snowflake side, run by someone with ACCOUNTADMIN:

CREATE SECURITY INTEGRATION atlas_oauth
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = 'https://<your-atlas-host>/oauth2/callback/'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE;

SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('ATLAS_OAUTH');

The redirect URI must match exactly, trailing slash included. If your Adverity Atlas installation routes sign-ins through an OAuth redirect proxy, register the proxy callback URL your Adverity Atlas operator gives you instead of https://<your-atlas-host>/oauth2/callback/.

SYSTEM$SHOW_OAUTH_CLIENT_SECRETS returns a JSON object containing the client id and two secrets. Copy the individual values out of it. Pasting the whole object into the Client Secret field is the most common way this goes wrong, and Snowflake answers with an unhelpful “invalid client”. Either secret works; two exist so you can rotate without downtime.

Then create the service config under Settings > Integrations > Service Configs:

Field	Value
Authorization URL	`https://<account>.snowflakecomputing.com/oauth/authorize`	Required
Token URL	`https://<account>.snowflakecomputing.com/oauth/token-request`	Required
Client ID	From `SYSTEM$SHOW_OAUTH_CLIENT_SECRETS`.	Required
Client Secret	From the same output. Stored encrypted.	Required

Saving the config checks it against Snowflake straight away, no sign-in needed: the Status column reads Verified once Snowflake has accepted the client, or Verification failed with Snowflake’s reason. A pasted JSON blob or a typo in the Token URL shows up here, before anyone reaches a consent screen. See Service configs.

Keeping it working¶

Adverity Atlas renews the access token by itself, so a connection keeps working without anyone returning to it. Two things do need a person:

The authorization eventually lapses.: Snowflake caps a refresh token at 90 days. When it expires, open the source and choose Re-authorize.
Changing the Role invalidates the authorization, because the role is inside the token. Adverity Atlas clears it and marks the source unverified rather than leaving it quietly running as the old role. Re-authorize to pick the new one up. Changing Database, Warehouse or Schema costs nothing.

Setup¶

Go to Settings > Data Governance > Data Sources. Under Add Connection, choose Snowflake. The Add a data source wizard opens and runs in five steps.
Source, confirm Snowflake is selected and click Continue.
Auth method, pick one of the methods above and click Continue.
Authenticate. For Username & Password or Key Pair, fill in the Configuration and Credentials fields and click Save credentials, then Continue. For Snowflake OAuth, fill in the Configuration fields, pick an OAuth client, and click Authenticate. You are sent to Snowflake’s consent screen and returned to Test once you approve.
Test, Adverity Atlas tests the connection as soon as you arrive and shows the result under Connection test. Continue unlocks once the test passes. After fixing a failure, click Test again. Back discards the saved credentials and returns you to Authenticate, with the configuration still filled in.
Review & create, enter a Name, choose a Sync schedule, and pick a Mode: Active (sync runs on schedule and agents can query this source), Development (sync runs, but agents cannot query it yet), or Disabled (no automated operations). Then click Create data source.

The Connection test runs the full connection diagnostic: it authenticates, lists the visible schemas, lists the tables in the target schema, and reads a row. You cannot continue to Review & create until every check passes, so a wrong credential or a missing grant is resolved here rather than becoming an unhealthy source afterwards. A failed check reports the warehouse’s own error, and the grant that is missing where Adverity Atlas can work it out, see Connection diagnostics. A test that could not run at all says “The connection test could not run. Try again in a moment.”

Adverity Atlas verifies the connection as soon as the source is created, and starts the first sync when verification succeeds and the mode allows it. Schema discovery and field profiling run from that sync.

Tip

If someone else holds the credentials, use Share a one-time link under Or ask someone else on the Authenticate step. They submit the credentials through that link and see the connection test run on their page too. If it fails, Provide credentials again lets them correct what they entered. Your wizard moves on to Test once they submit, so the secret never passes through you. This is offered for the credential-based methods only: Snowflake OAuth also needs a role, which the person holding the link has no way to choose.

Connection fields¶

These appear under Configuration on the wizard’s Authenticate step.

Field	Description
Host	e.g. `xy12345.us-east-1.snowflakecomputing.com`	Required, except for Snowflake OAuth, where it is taken from the OAuth client and not shown
Database	e.g. `MY_DB`	Required
Warehouse	e.g. `COMPUTE_WH`	Optional
Schema	e.g. `PUBLIC`	Optional
Role	e.g. `SYSADMIN`	Optional, but required for Snowflake OAuth, it is what the authorization is granted for

Troubleshooting¶

Symptom	Likely cause
“Snowflake status unhealthy”	Credentials expired or rotated. Re-enter and test.
No tables in a child workspace	The role may have database access but not the child schemas. Grant USAGE and SELECT per schema.
Warehouse suspended	Snowflake auto-suspends idle warehouses. Enable auto-resume.
“This Snowflake connection has not been authorized yet, or its authorization has expired”	The refresh token lapsed, was revoked, or the Role changed. Open the source and choose Re-authorize.
Service config shows “Verification failed”	The reason under the badge is Snowflake’s own. “Invalid client credentials” means the Client ID or Client Secret; “Could not reach the authorization server” means the Token URL. Fix and save to check again.
Sign-in succeeds, then “Invalid client credentials (error code: invalid_client)”	The Client Secret or Client ID on the service config does not match the security integration. `SYSTEM$SHOW_OAUTH_CLIENT_SECRETS` returns a JSON object, and only the secret inside it belongs in that field.
Sign-in succeeds, then “Could not reach the authorization server: …”	Adverity Atlas never got an answer from Snowflake. Check the Token URL on the service config for typos, a TLS error naming a host it did not expect usually means one.
“Set role on this data source before authorizing”	Snowflake OAuth grants access for one role, so it has to be chosen before the consent screen, not after.

What’s next?¶

Configure the glossary, align the language across your platforms so answers use your definitions
Ask questions about your data, start a conversation against the data you just connected
Data sources, schema discovery, profiling, and managing connections