> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delphina.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Snowflake Connection Guide

> Connect Delphina to Snowflake with a dedicated user, role, and warehouse

Delphina connects to Snowflake using a dedicated user and role. The role needs **SELECT** access to the data you want the agent to query, and — optionally — access to query history and Cortex Analyst objects so Delphina can learn from existing usage and semantics.

<Note>
  We recommend the warehouse provided be sized **Small or larger** so Delphina can execute queries with acceptable performance.
</Note>

## Connecting Snowflake

### Step 1: Gather connection details

You'll need the following from your Snowflake account:

| Field                  | Where to find it                                          | Example             |
| ---------------------- | --------------------------------------------------------- | ------------------- |
| **Account identifier** | Snowflake account URL (without `.snowflakecomputing.com`) | `xy12345.us-east-1` |
| **Warehouse**          | Name of the warehouse Delphina should use                 | `DELPHINA_WH`       |
| **Database**           | Default database for the connection                       | `ANALYTICS`         |
| **Role**               | Role granted to the Delphina user                         | `DELPHINA_ROLE`     |

### 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.

```sql theme={null}
CREATE USER delphina_user <any additional user properties>;
CREATE ROLE delphina_role;
GRANT ROLE delphina_role TO USER delphina_user;

GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE delphina_role;
GRANT USAGE ON DATABASE <database_name> TO ROLE delphina_role;

GRANT USAGE ON ALL SCHEMAS IN DATABASE <database_name> TO ROLE delphina_role;
GRANT USAGE ON FUTURE SCHEMAS IN DATABASE <database_name> TO ROLE delphina_role;

GRANT SELECT ON ALL TABLES IN DATABASE <database_name> TO ROLE delphina_role;
GRANT SELECT ON FUTURE TABLES IN DATABASE <database_name> TO ROLE delphina_role;

GRANT SELECT ON ALL VIEWS IN DATABASE <database_name> TO ROLE delphina_role;
GRANT SELECT ON FUTURE VIEWS IN DATABASE <database_name> TO ROLE delphina_role;

-- Repeat for any other relevant databases.
```

### 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.

<Tabs>
  <Tab title="Option A — IMPORTED PRIVILEGES (simplest)">
    Give the role read access to the shared `SNOWFLAKE` database, which exposes `ACCOUNT_USAGE.QUERY_HISTORY`.

    ```sql theme={null}
    -- Read access to the SNOWFLAKE shared DB objects
    GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE delphina_role;

    -- Allow the role to read account usage views
    GRANT MONITOR USAGE ON ACCOUNT TO ROLE delphina_role;
    ```
  </Tab>

  <Tab title="Option B — Scoped secure view">
    If you'd rather not grant broad access to `ACCOUNT_USAGE`, create a secure view that exposes only the columns and lookback window Delphina needs.

    ```sql theme={null}
    CREATE OR REPLACE SECURE VIEW <database_name>.<schema_name>.QUERY_HISTORY_SCOPED AS
    WITH q AS (
      SELECT
        QUERY_ID, USER_NAME, ROLE_NAME, WAREHOUSE_NAME,
        DATABASE_NAME, SCHEMA_NAME, QUERY_TEXT, START_TIME, END_TIME,
        EXECUTION_STATUS, TOTAL_ELAPSED_TIME
      FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY
      WHERE START_TIME >= DATEADD(day, -365, CURRENT_TIMESTAMP())  -- pick your lookback
    )
    SELECT
      QUERY_ID, USER_NAME, ROLE_NAME, WAREHOUSE_NAME,
      DATABASE_NAME, SCHEMA_NAME, QUERY_TEXT, START_TIME, END_TIME,
      EXECUTION_STATUS, TOTAL_ELAPSED_TIME
    FROM q;

    GRANT SELECT ON VIEW <database_name>.<schema_name>.QUERY_HISTORY_SCOPED TO ROLE delphina_role;
    ```
  </Tab>
</Tabs>

### 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:

```sql theme={null}
-- For an internal stage that holds semantic models
GRANT READ ON STAGE <db>.<schema>.<models_stage_name> TO ROLE delphina_role;

-- For semantic views
GRANT SELECT, REFERENCES
  ON SEMANTIC VIEW <db>.<schema>.<semantic_view_name>
  TO ROLE delphina_role;
```

### Step 5: Create the connection in Delphina

1. Navigate to [analytics.delphina.ai](https://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.

## Troubleshooting

| Problem                                    | Fix                                                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Test Connection fails**                  | Verify the account identifier, warehouse, and role exist and that `delphina_user` can log in with the supplied credentials.                      |
| **"Browse Tables" empty**                  | Confirm `USAGE` is granted on the database and schema, and `SELECT` on the tables. Future grants only apply to objects created after the grant.  |
| **"Show Top Users" empty**                 | Either `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` is missing or the scoped `QUERY_HISTORY_SCOPED` view hasn't been shared with `delphina_role`. |
| **Queries time out or feel slow**          | Size and scale the warehouse for Delphina's workload — see [Snowflake Performance & Tuning](/administration/snowflake-performance).              |
| **Cortex Analyst semantics not picked up** | Check that `READ` is granted on the models stage and `SELECT, REFERENCES` on the semantic view.                                                  |