# Initial Snowflake Setup

Before we jump into making our snowflake agent, lets go through the initial setup.

### Auth Setup

- To connect to snowflake you'll need to generate a role on snowflake, attach a user to that role, and use private key-pair auth to add that role to snowflake.
- You can have multiple snowflake credentials in credal each tied to their own snowflake user/role to ensure secure access.

##### 1. Create a role in snowflake which will control read access to tables/views (e.g CREDAL\_READ)

```sql
-- 1. Create the new Role
CREATE ROLE CREDAL_READ;
GRANT ROLE CREDAL_READ TO ROLE ACCOUNTADMIN;

-- 2. Grant the appropriate access to read database/schema/tables
GRANT USAGE ON DATABASE <database_name> TO ROLE CREDAL_READ;
GRANT USAGE ON ALL SCHEMAS IN DATABASE <database_name> TO ROLE CREDAL_READ;
GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE CREDAL_READ;

GRANT SELECT ON ALL TABLES IN DATABASE <database_name> TO ROLE CREDAL_READ;
GRANT SELECT ON ALL VIEWS IN DATABASE <database_name> TO ROLE CREDAL_READ;

-- 3. Test that the role has the correct access (Optional).
USE ROLE CREDAL_READ;
SHOW SCHEMAS IN DATABASE <database_name>;
SHOW TABLES;
SELECT * FROM <database_name>.INFORMATION_SCHEMAS.TABLES;
```

##### 2. Create a new User that is granted the **CREDAL\_READ** role

```sql
-- 1. Create the new User
CREATE USER CREDAL_USER; -- can be any username
...
GRANT ROLE CREDAL_READ TO USER CREDAL_USER;
```

##### 3. Setup Snowflake key pair authentication

- Follow this guide to setup key-pair auth: [Snowflake Key Pair Auth](https://docs.snowflake.com/en/user-guide/key-pair-auth)

##### 4. Add your snowflake credential on the \[action provider page]

- They will need the `Subdomain`, `Account Identifier`, `Username`, `Private Key` and `SHA-256 Fingerprint` to add the snowflake connection.

:::frame
![Form for adding a Snowflake credential with fields for subdomain, account identifier, username, private key, and SHA-256 fingerprint](/media/t/75c5dc71-055f-4496-bcaf-6966eeb0b645/p/6557597f-ed9e-4a60-b7d4-61f66fcfad15/b829d823e92edee3e5255fadd35ce4495db6c780ee143f2e94556d0811d2f779.png/raw)
:::

## Implementation Steps

### Step 1: Create Your Agent

1. Navigate to the [Agents](https://app.credal.ai/agents) page and click "Create New Agent"
2. Name your agent "Snowflake Data Extractor"
3. Add this description:
   > This assistant helps employees query data from snowflake getting metrics, analysis and human-readable responses on the data.
4. Enable [Code Interpreter](https://docs.credal.ai/user-guide/platform/agent-builder/configuration/choosing-a-model) (required for image generation)
   > Output from the runSnowflakeQuery Action is passed into Open AI Code Interpreter for image generation and analysis (depending on your parameter setup)

:::frame
![Agent configuration panel with the Code Interpreter option enabled](/media/t/75c5dc71-055f-4496-bcaf-6966eeb0b645/p/6557597f-ed9e-4a60-b7d4-61f66fcfad15/0873dc2bae41a6362ed80d5a016d39a9d67fca0294e4628fb2231987067fbc12.png/raw)
:::

**Tip:** A detailed description helps users understand the purpose of your Agent.

### Step 2: Create the runSnowflake Action

1. **Database**: the default database to use when querying
2. **Warehouse**: the compute warehouse to run your queries (will likely be hardcoded)
3. **Query**: Depends on whether you take the Query Templates Approach or the Snowflake Views approach (explained more in next steps)
4. **Account Name**: Your snowflake account name (will likely be hardcoded)
5. **Format**: The format of your output `csv` or `json` (prefer `csv`)
6. **Role**: The role you would like to use with the credentials (optional)
7. **Limit** (Optional): The limit on number of rows to return, anything over this limit will mention "data queried was too large"
8. **Code Interpreter Limit** (Optional): The minimum number of rows required to pass to code interpreter for analysis (thinking models handle small sets of results (e.g < 100) better than code interpreter)
9. **Code Interpreter Image Gen Limit** (Optional): The minimum number of rows required for image generation (in case you want thinking models for analysis and image generation for more than X results)

### Step 3: Configure Access Control for Snowflake Credentials

Access to Snowflake data is controlled at two levels:

1. **Credential Access**:
   - Only the creator of a Snowflake credential can attach it to an Action.
2. **Action Access**:
   - You can specify exactly which users or groups can use this Action through the [End User Access settings](https://docs.credal.ai/user-guide/platform/governed-actions/credentials-and-security)
   - This ensures that only authorized personnel can execute queries using the attached Snowflake credentials

**Important Security Note**: Any user with end-user access to an Action will be able to use the attached Snowflake credentials through that Action. Ensure you carefully manage the End User Access list to maintain proper data security.

:::frame
![Action settings showing a Snowflake credential attached to the action](/media/t/75c5dc71-055f-4496-bcaf-6966eeb0b645/p/6557597f-ed9e-4a60-b7d4-61f66fcfad15/943e31fd19c31c5aa5832f21112bdf5c20e54b96870ea1eca21e6429971eae3b.png/raw)
:::

:::frame
![End User Access settings specifying which users and groups can use the action](/media/t/75c5dc71-055f-4496-bcaf-6966eeb0b645/p/6557597f-ed9e-4a60-b7d4-61f66fcfad15/3e2aaeda476e1014d14f4ac26cebd51c717e6b52cb4984778c69b3eff76b7bd9.png/raw)
:::

### Step 4: Model Choice

The base model you select will affect queries generated and analysis of results.
It's recommended to use a [thinking model](https://docs.credal.ai/user-guide/platform/agent-builder/configuration/choosing-a-model) with reasoning enabled for complex queries, however the model you select also depends on the query approach. You may want to use a smaller non-reasoning model for query templates which are more well defined compared to snowflake views.

### Step 5: Choose your query approach

Right now there are 2 approaches to querying snowflake for data

- ##### 1. Query Templates
- ##### 2. Snowflake Views

Each one has their own pros and cons and will likely be use-case dependant.
Read about each approach and implementation steps in [Query Approaches](https://docs.credal.ai/user-guide/getting-started/tutorials-common-first-agents/snowflake-query-assistant/query-approaches).

## Next Step

Continue to [Query Approaches](https://docs.credal.ai/user-guide/getting-started/tutorials-common-first-agents/snowflake-query-assistant/query-approaches) to compare query templates versus Snowflake views and choose the implementation pattern that fits your use case.

## Related pages

- [Creating a Snowflake Query Assistant](./getting-started-tutorials-snowflake-query-overview.md)
- [Query Approaches](./getting-started-tutorials-snowflake-query-query-approaches.md)
- [Testing your solution](./getting-started-tutorials-snowflake-query-testing-solution.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.