Skip to main content

Snowflake connector

For Studio users who administer a Snowflake account and can create a service user, a network policy and either a programmatic access token or an RSA key pair for it.

Before you start: note the account identifier as Snowsight shows it (orgname-account_name or a legacy locator; the host is always <identifier>.snowflakecomputing.com) and grant the service user's role exactly what agents should read. There is no discovery step: "You write the guide; agents get the SQL API and your role's grants, nothing more."

Steps​

  1. Open Data Connectors, click Create Connector, choose Snowflake and fill Connector Name, Description and Connector Guide.

  2. In Connection Configuration: Account identifier (letters, digits, _, . and -; 1 to 63 characters; the helper shows the host); Warehouse (case-sensitive; placeholder COMPUTE_WH); Database (required; placeholder ANALYTICS); Schema (Optional) (placeholder PUBLIC); Role (Optional) ("Leave blank for the token user's default role"); Query timeout (seconds), 1 to 60, default 60.

  3. Read the setup facts under the fields ("Loading setup facts..." while they arrive), each with Copy: Deployment egress IP (add to the token user's network policy); Token type, the header sent on every SQL API call (X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN, or KEYPAIR_JWT for key pair); SQL API URL and Test statements once identifier, warehouse and database are filled; and Network policy SQL (allows the egress IP above for the token user), shown only when the deployment reports its egress IP. Run it in Snowflake as ACCOUNTADMIN (or a role with CREATE NETWORK POLICY), replacing <token_user>; the form fills in the real address:

    CREATE NETWORK RULE IF NOT EXISTS alphaagent_studio_egress
      TYPE = IPV4 MODE = INGRESS VALUE_LIST = ('<deployment-egress-ip>/32');
    CREATE NETWORK POLICY IF NOT EXISTS alphaagent_studio
      ALLOWED_NETWORK_RULE_LIST = ('alphaagent_studio_egress');
    ALTER USER <token_user> SET NETWORK_POLICY = alphaagent_studio;

  4. In Snowflake, mint a programmatic access token for the service user, or generate an RSA key pair and register the public key on the user (private key in Privacy-Enhanced Mail (PEM) format; an encrypted key needs its passphrase).

  5. Under Authentication, enter the Username (the service user's login name; agents connect as this user) with either the Programmatic access token (recommended) or, for Key pair (RSA private key), the whole Private key (PEM) from -----BEGIN PRIVATE KEY----- and Private key passphrase (Optional) ("Only if the key is encrypted"). The note: "Stored in AWS Secrets Manager and never shown again. Agents connect from their sandbox as this user".

  1. Click Test Connection, enabled once the identifier is valid, warehouse and database are filled, the timeout is in range and the username plus token or private key are entered. For a key pair Studio signs a short-lived JSON Web Token (JWT) with your key. It runs three statements that need no warehouse, so the test never resumes yours:

    SELECT CURRENT_VERSION(), CURRENT_USER(), CURRENT_ROLE()
    SHOW WAREHOUSES LIKE '<warehouse>'
    SHOW DATABASES LIKE '<database>'

    A pass reads "Connected to <host> as <user> (<role>). Warehouse <warehouse>: <state>. Database <database>: found."

  1. Click Create Connector (v1), enabled only after a passing test.
  2. Open the agent, choose Configure, and add the connector (Agents: configure and activate).

What you should see​

The list shows Snowflake "(v1)", Active. Configuration shows account, host, warehouse, database, schema, role, authentication method and query timeout. Credentials shows only the Username with "Stored in AWS Secrets Manager as a programmatic access token" (or "as a key pair"). "The secret is never shown here; use Update to rotate it."; tokens, keys and passphrases never appear on any screen.

Rotate the token or key​

Mint the new token or register the new public key in Snowflake, open the connector, click Update and under Credentials enter the Username with the new token or Private key (PEM) and passphrase ("Re-enter a token or key pair to rotate the stored credential; leave blank to keep it."). Optionally Test Connection, then Update Connector (v2) ("Saving creates v2", one higher than the version you opened). Blank keeps the stored credential; username and secret go together, both or neither; switching method needs the new method's complete credentials; credentials are stored per connector, not per version, so every version uses the new one.

In chat​

The agent's code connects with the Snowflake Python connector as the service user, using the token or the private key Studio delivers to that run at invocation (never written into the environment's configuration), and reads results into a data frame or saves them as Parquet in the workspace. Every statement carries a query tag naming the connector, visible in Snowflake's query history. The role's grants decide what it can read; the guide decides what it looks for.

Notes​

  • Limits: identifier 1 to 63 characters; query timeout 1 to 60 seconds; 1,000 rows per statement from Studio's own calls; key-pair JWTs for Studio's own calls last 59 minutes (Snowflake caps them at one hour) and are re-minted within 5 minutes of expiry.
  • "Failed to load Snowflake setup": reload; your fields are kept. Egress IP "Not available on this deployment yet - ask your administrator for the deployment's NAT gateway address.": the network policy SQL stays hidden until the deployment records its address (your administrator reads it from the installation's network outputs).
  • "Connected to ..., but warehouse <name> was not found (or the role cannot see it)." (or the database): sign-in worked; fix the case-sensitive name or the grant. A failure before "Connected" is Snowflake's message: check the network policy is on the user, the token is unexpired or the public key matches, and the identifier is exactly as Snowsight shows it.
  • Test Connection disabled: a field is missing or out of range, or username and secret are not both entered (a passphrase alone is not a credential). Update Connector disabled after pasting a key: enter the username too, or clear both. "No username stored. Add one via Update": enter the Username alone and save; the stored token is kept.