Skip to main content
Delphina supports either a dedicated Snowflake service user or per-user Snowflake OAuth. A service user needs SELECT access to the data you want the agent to query; with per-user OAuth, each person’s Snowflake role determines their access. Query history and Cortex Analyst access are optional.
We recommend the warehouse provided be sized Small or larger so Delphina can execute queries with acceptable performance.

Connecting Snowflake

Step 1: Gather connection details

You’ll need the following from your Snowflake account:

Step 2: Create the user, role, and grant data access

Run the following DDL in Snowflake. It creates a dedicated user and role and grants SELECT access to every object in a database. Prune the grants down to a smaller set of schemas/tables if you’d rather scope Delphina narrowly.
If a tool like dbt creates or rebuilds tables and views in a schema, also add schema-level future grants for that schema. Snowflake ignores database-level future grants in a schema that has its own.

Step 3: Grant access to query history

Delphina uses query histories from trusted users to prioritize tables and learn how your data is used. Choose one of the two patterns below.
Give the role read access to the shared SNOWFLAKE database, which exposes ACCOUNT_USAGE.QUERY_HISTORY.

Step 4: (Optional) Grant access to Cortex Analyst objects

If you use Snowflake Cortex Analyst and want Delphina to reuse your existing semantic definitions, grant the following additional permissions:

Step 5: Create the connection in Delphina

  1. Navigate to analytics.delphina.ai.
  2. Click your name in the bottom-left, then Org Admin > Warehouse Connections.
  3. Click Add Connection on the target workspace.
  4. Set the Warehouse Type to Snowflake.
  5. Fill in the account identifier, warehouse, database, role, and user credentials from the steps above.
  6. Click Create Connection, then Test Connection to verify Delphina can reach your warehouse, list tables, and access query history.

Per-user Snowflake OAuth

Use this option when queries should run with each person’s Snowflake permissions rather than a shared service user’s permissions. A Snowflake administrator must create a custom OAuth security integration for a confidential client in the same Snowflake account as the connection. Register the exact redirect URI shown in Delphina’s Snowflake connection form: append /oauth/snowflake/callback to the configured Delphina API URL. For example, an API URL of https://app.delphina.ai/api uses https://app.delphina.ai/api/oauth/snowflake/callback; a local API URL of https://localhost:3543 uses https://localhost:3543/oauth/snowflake/callback. Do not use the analytics frontend URL. Configure the integration to issue refresh tokens. Set its refresh-token validity and single-use policy to match your security requirements; Delphina persists a rotated refresh token before allowing the next exchange. Keep the client ID and both the client secret and Snowflake account identifier available for the Delphina connection settings. Snowflake’s custom OAuth documentation describes creating the integration and retrieving its client credentials. In Org Admin > Warehouse Connections, configure the Snowflake account, warehouse, database, OAuth client ID, and client secret. Choose User default role to request refresh_token and use each person’s Snowflake default role, or Fixed role to request refresh_token session:role:<ROLE>; for roles needing URL encoding Delphina uses session:role-encoded:<ROLE>. The fixed role must be granted to each consenting Snowflake user: choosing it does not grant access by itself. Grant USAGE on the warehouse, database, and schemas and SELECT on the intended objects to that role. A person’s default role also needs those grants when using the default-role option. Each person connects their own Snowflake account from User Settings > Data Sources and consents in Snowflake. Reconnect when the integration, OAuth client, role, or account changes or if a refresh exchange fails ambiguously. Delphina retains the service user’s credentials for system jobs; human queries using an OAuth-enabled connection do not fall back to that user when consent is missing or invalid. Existing shared or published results retain their current visibility; per-user OAuth governs new queries, not historical result authorization.

Troubleshooting