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

# Snowflake Connector

> Connect Snowflake data warehouse to Roe

Connect your Snowflake data warehouse to Roe to query transaction data, customer information, and other structured data during agent investigations.

## Use Cases

* **AML/Fraud Investigation**: Query transaction history and customer data during investigations
* **Data Analysis**: Enable agents to explore and analyze data using natural language queries
* **Context Enrichment**: Provide agents with access to your data warehouse for comprehensive analysis

## Prerequisites

Before connecting Snowflake to Roe, ensure you have:

1. A Snowflake account with appropriate permissions
2. A Programmatic Access Token (PAT) **OR** an RSA Key Pair for authentication
3. Access to a warehouse, database, and schema

## Authentication Methods

Roe supports two authentication methods for Snowflake: Programmatic Access Tokens (PAT) and RSA Key Pair authentication. Both methods bypass MFA and are recommended for programmatic access.

### Option 1: Programmatic Access Token (PAT)

<Steps>
  <Step title="Open Snowsight">
    Log in to your Snowflake account using [Snowsight](https://app.snowflake.com)
  </Step>

  <Step title="Navigate to Profile">
    Click on your user menu (top-right) → **My Profile**
  </Step>

  <Step title="Go to Authentication">
    Select the **Authentication** tab
  </Step>

  <Step title="Generate Token">
    Under **Programmatic access tokens**, click **Generate new token**
  </Step>

  <Step title="Save Token">
    Copy the token immediately—it's only shown once!
  </Step>
</Steps>

### Option 2: RSA Key Pair Authentication

You can generate an RSA key pair locally and register the public key with your Snowflake user.

<Steps>
  <Step title="Generate Key Pair Locally">
    Run the following OpenSSL commands in your terminal to generate an encrypted private key and a public key:

    ```bash theme={null}
    # Generate an encrypted private key (you will be prompted to create a passphrase)
    openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out snowflake_private_key.p8

    # Generate the public key
    openssl rsa -in snowflake_private_key.p8 -pubout -out snowflake_public_key.pub
    ```

    *Note: If you prefer an unencrypted private key, append `-nocrypt` to the first command.*
  </Step>

  <Step title="Format the Public Key">
    Snowflake requires the public key body without the header, footer, or newlines. Extract it using:

    ```bash theme={null}
    awk 'NR > 1 && !/-----END PUBLIC KEY-----/ { printf "%s", $0 }' snowflake_public_key.pub
    ```

    Copy the output.
  </Step>

  <Step title="Register Public Key in Snowflake">
    Log into Snowflake as an admin (e.g., `USERADMIN` or `ACCOUNTADMIN`) and run the following SQL:

    ```sql theme={null}
    ALTER USER your_snowflake_username
    SET RSA_PUBLIC_KEY = '<paste-public-key-body-here>';
    ```

    Verify it was set correctly by running `DESC USER your_snowflake_username;`.
  </Step>
</Steps>

<Warning>
  Store your PAT or Private Key securely. Roe encrypts and stores credentials in AWS Secrets Manager.
</Warning>

## Configure the Connection

Provide the following information to connect Snowflake:

### Authentication (Sensitive)

Choose your authentication method from the dropdown and provide the corresponding fields:

| Field                      | Required    | Description                                                                                           |
| -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
| **Account**                | Yes         | Snowflake account identifier (e.g., `xy12345.us-east-1`)                                              |
| **Username**               | Yes         | Your Snowflake username                                                                               |
| **Authentication Method**  | Yes         | Choose either **Programmatic Access Token** or **Key Pair**                                           |
| **Token**                  | Conditional | The PAT (required if using Token auth)                                                                |
| **Private Key**            | Conditional | The full PEM-encoded RSA private key including header/footer (required if using Key Pair auth)        |
| **Private Key Passphrase** | Conditional | The passphrase for your encrypted private key (required if using Key Pair auth with an encrypted key) |

### Configuration

| Field         | Required | Description                                                          |
| ------------- | -------- | -------------------------------------------------------------------- |
| **Warehouse** | Yes      | Snowflake warehouse (compute resource) to use for queries            |
| **Database**  | Yes      | Default database to use for queries                                  |
| **Schema**    | Yes      | Schema (namespace) within the database. `PUBLIC` is a common default |
| **Role**      | No       | Snowflake role for access control                                    |

<Tip>
  The schema hierarchy in Snowflake is: **Account → Database → Schema → Table**

  For example, `PROD_DB.PUBLIC.CUSTOMERS` means:

  * Database: `PROD_DB`
  * Schema: `PUBLIC`
  * Table: `CUSTOMERS`
</Tip>

## Test the Connection

Click **Test Connection** to verify that Roe can successfully connect to your Snowflake instance. The test will:

1. Authenticate using your PAT or Key Pair
2. Verify access to the specified warehouse, database, and schema
3. Run a simple query to confirm connectivity

## Using Snowflake as a Context Source

Once connected, you can use your Snowflake connection as a **context source** in agentic workflows like AML Investigation or Fraud Investigation.

### Context Source Configuration

When configuring an agent to use Snowflake:

```json theme={null}
{
  "connection_type": "snowflake",
  "name": "Transaction History",
  "connection_id": "your-connection-uuid",
  "table": "TRANSACTIONS",
  "description": "Customer transaction data for the last 12 months"
}
```

| Field           | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `name`          | Friendly name for this data source                           |
| `connection_id` | UUID of your Snowflake connection                            |
| `table`         | Table to query (agent generates SELECT queries with filters) |
| `description`   | Helps the agent understand what data is available            |

### Agent Capabilities

When Snowflake is configured as a context source, agents can:

* **Discover schema**: Automatically understand table structure
* **Generate SQL**: Create appropriate queries based on natural language
* **Filter data**: Apply relevant filters (e.g., customer ID, date ranges)
* **Handle errors**: Recover from query issues gracefully

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Secure Auth" icon="key">
    PATs and Key Pair auth are more secure than passwords and can be revoked independently
  </Card>

  <Card title="Limit Permissions" icon="shield">
    Create a dedicated role with read-only access to only the required tables
  </Card>

  <Card title="Use Separate Warehouse" icon="warehouse">
    Use a dedicated warehouse for Roe to manage resource usage
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Review Snowflake query history to audit agent data access
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed: Invalid credentials">
    Verify your account identifier, username, and PAT or Private Key/Passphrase are correct. PATs expire and may need to be regenerated. If using a Key Pair, ensure the public key matches.
  </Accordion>

  <Accordion title="Connection failed: Warehouse not found">
    Ensure the warehouse name is correct and your user has USAGE permission on the warehouse.
  </Accordion>

  <Accordion title="Connection failed: Database/Schema not found">
    Verify the database and schema exist and your user has appropriate permissions to access them.
  </Accordion>

  <Accordion title="Query timeout">
    Queries have a 30-second timeout. If your queries are timing out, consider optimizing table indexes or filtering to smaller datasets.
  </Accordion>
</AccordionGroup>