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

# Snowflake

# Snowflake Integration Setup

Honeydew requires access to Snowflake in order to operate.
You have two options to set up Snowflake access - either using a central org-level connection parameters
or map your individual Snowflake user credentials to Honeydew.

If you would like to use a central org-level connection, it is advised to create a new dedicated Snowflake user for Honeydew integration.
The following Snowflake connection parameters are required for Honeydew setup:

1. Account name
2. Username
3. Role
4. Warehouse

## Authentication Methods

Honeydew supports the following authentication methods for Snowflake:

### [**Key-pair authentication**](https://docs.snowflake.com/en/user-guide/key-pair-auth)

This is the recommended method for org-level service accounts.
For this method, you will need to provide a **Private Key** and possibly a **Private Key Passphrase** (if used).

<Steps>
  <Step title="Generate a key pair">
    <Tabs>
      <Tab title="MacOS">
        Generating an unencrypted private key can be done using the following command:

        ```bash theme={null}
        openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
        ```

        Generating an encrypted private key can be done using the following command:

        ```bash theme={null}
        openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
        ```

        Generating the public key:

        ```
        openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
        ```
      </Tab>

      <Tab title="Windows">
        <Note>
          Make sure the OpenSSH feature is enabled on your Windows machine.
          For the output folder we use Windows command line %userprofile% to direct to your user home folder.
          You can replace it with your preferred (existing) folder.
        </Note>

        ```cmd theme={null}
        ssh-keygen -t rsa -b 2048 -m pkcs8 -f %userprofile%\rsa_key.p8
        ```

        Convert the generated .pub file to a compatible format:

        ```cmd theme={null}
        ssh-keygen -e -f %userprofile%\rsa_key.p8.pub -m pkcs8 > %userprofile%\rsa_key.pub
        ```
      </Tab>
    </Tabs>

    Store the generated keys in a secure location.
  </Step>

  <Step title="Assign the public key to a Snowflake user">
    To assign the public key to a Snowflake user, execute the following SQL command in Snowflake:

    ```sql theme={null}
     -- Replace <HONEYDEW_USER> with the Snowflake user name and <PUBLIC_KEY> with the content of the rsa_key.pub file
    ALTER USER <HONEYDEW_USER> SET RSA_PUBLIC_KEY='<PUBLIC_KEY>';
    ```

    <Tip>
      Exclude the public key delimiters in the SQL statement.
    </Tip>
  </Step>

  <Step title="Configure the Snowflake connection in Honeydew">
    In [Honeydew App settings page](https://app.honeydew.cloud/settings),
    configure the Snowflake connection using the **Private Key** and **Private Key Passphrase** (if used) from the previous step.
  </Step>
</Steps>

### [**OAuth authentication**](https://docs.snowflake.com/en/user-guide/oauth-custom)

This is the recommended method for individual users credentials. Each user will need to connect to Honeydew using their own Snowflake OAuth credentials.
For this method, you will need to create a new Snowflake OAuth integration and then provide a **Client ID** and **Client Secret**.

When Snowflake OAuth is used, users can authorize their Honeydew credentials using SSO via Snowflake.
If Snowflake is set up with SSO through a third-party identity provider, Honeydew users can use this method to log into Snowflake and authorize Honeydew credentials without any additional setup.

#### OAuth integration configuration

<Steps>
  <Step title="Locate the Honeydew redirect URI">
    You will need to provide the Honeydew redirect URI when creating the OAuth integration in Snowflake.
    The redirect URI can be found in the Honeydew App [settings page](https://app.honeydew.cloud/settings) under the Snowflake connection section.
    It should look like this (exact URI may vary based on your Honeydew deployment):

    ```
    https://api.honeydew.cloud/oauth2callback
    ```

    Save it for later use.
  </Step>

  <Step title="Create a Snowflake OAuth integration">
    To create a new OAuth integration in Snowflake, execute the following SQL command.
    You can find the complete documentation on creating an oauth integration [here](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration#syntax).

    In the following query, replace `<REDIRECT_URI>` with the Honeydew redirect URI you saved in the previous step.
    Replace `<VALIDITY_IN_SECONDS>` with the desired validity period for the refresh token - for example, `2592000` for 30 days.
    If not provided, the default is `7776000` (90 days).

    If you are using secondary roles, please include `OAUTH_USE_SECONDARY_ROLES = 'IMPLICIT'` in the statement.
    If you would like to pre-authorize specific roles for OAuth authentication,
    provide the `PRE_AUTHORIZED_ROLES_LIST` parameter with a list of the actual role names you want to pre-authorize.

    For improved security, we recommend setting `OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE`.
    This rotates the refresh token on every use, so a leaked token cannot be reused. See the Snowflake
    [single-use refresh tokens](https://docs.snowflake.com/en/user-guide/single-use-refresh-tokens)
    documentation for details.

    ```sql theme={null}
    CREATE OR REPLACE SECURITY INTEGRATION HONEYDEW_OAUTH_INTEGRATION   -- Replace HONEYDEW_OAUTH_INTEGRATION with your desired integration name
      TYPE = OAUTH
      ENABLED = TRUE
      OAUTH_CLIENT = CUSTOM
      OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
      OAUTH_REDIRECT_URI = '<REDIRECT_URI>'                 -- Replace with the Honeydew redirect URI
      OAUTH_ISSUE_REFRESH_TOKENS = TRUE
      OAUTH_REFRESH_TOKEN_VALIDITY = <VALIDITY_IN_SECONDS>  -- Replace with desired validity period in seconds
      OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE       -- (Optional, recommended) Rotate the refresh token on each use for improved security
      NETWORK_POLICY = '<NETWORK_POLICY>'                   -- (Optional) Replace with the name of the network policy to use, if any
      PRE_AUTHORIZED_ROLES_LIST = ( '<role_name1>', ...)    -- (Optional) Replace with the list of roles that will be used for OAuth authentication
      OAUTH_USE_SECONDARY_ROLES = IMPLICIT;                 -- (Optional) Required for secondary roles
    ```

    Additional configuration options may be specified for the security integration as needed.

    <Tip>
      When defining a network policy for the OAuth integration, ensure that it allows access from the Honeydew IP addresses,
      in combination with any IP addresses that are used to access Snowflake from your SSO provider (e.g. Okta, etc..).
    </Tip>

    <Note>
      Only Snowflake users with the `ACCOUNTADMIN` role or a role with the global `CREATE INTEGRATION` privilege can execute this SQL command
    </Note>
  </Step>

  <Step title="Retrieve OAuth Client ID and Client Secret">
    Once the OAuth integration is created, you can configure the Snowflake connection in Honeydew.
    First, retrieve the **Client ID** and **Client Secret** for the OAuth integration you just created.
    You can do this by executing the following SQL command in Snowflake:

    ```sql theme={null}
    WITH
    OAUTH_SECRETS as (
      select PARSE_JSON(
        system$SHOW_OAUTH_CLIENT_SECRETS('HONEYDEW_OAUTH_INTEGRATION')) as SECRETS_JSON     -- Replace HONEYDEW_OAUTH_INTEGRATION with your integration name
    )
    SELECT
      SECRETS_JSON:"OAUTH_CLIENT_ID"::string as CLIENT_ID,
      SECRETS_JSON:"OAUTH_CLIENT_SECRET"::string as CLIENT_SECRET
    from
      OAUTH_SECRETS;
    ```
  </Step>

  <Step title="Configure the Snowflake connection in Honeydew">
    In [Honeydew App settings page](https://app.honeydew.cloud/settings),
    configure the Snowflake connection using the **Client ID** and **Client Secret** from previous step.
  </Step>
</Steps>

#### User setup

Once Snowflake OAuth integration is configured, Honeydew users will be able to provide their credentials via OAuth.
By clicking "Connect to Snowflake" in the Snowflake settings, users will be redirected to Snowflake to authorize with the configured SSO provider.

### [**PAT (programmatic access tokens) authentication**](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens)

For this method, you will need to provide a generated access token.

<Steps>
  <Step title="Generate a PAT in Snowflake">
    Follow the steps in the [Snowflake documentation](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens#generating-a-programmatic-access-token) to create a PAT.
    Note the prerequisites required for PAT generation, such as:

    * [Network policy requirements](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens#generating-a-programmatic-access-token)
    * [Authentication policy requirements](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens#authentication-policy-requirements)
  </Step>

  <Step title="Configure the PAT in Honeydew">
    In [Honeydew App settings page](https://app.honeydew.cloud/settings),
    configure the Snowflake connection using the **Access Token** generated in Snowflake.
  </Step>
</Steps>

### [**Password authentication**](https://docs.snowflake.com/en/user-guide/password-authentication)

For this method, you will need to provide a password, and will likely be required to approve access via MFA.

<Warning>
  Password authentication is not recommended for production use.
</Warning>

<Note>
  It is advised to use [Key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth) for Snowflake integration, when using an org-level service account,
  and to use [OAuth authentication](https://docs.snowflake.com/en/user-guide/oauth-custom)
  or [PAT (programmatic access tokens) authentication](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) for individual users credentials.

  It is strongly recommended to keep MFA enabled for any Snowflake users that are integrated with Honeydew.
</Note>

The following Snowflake connection parameters are required to be able to deploy dynamic datasets to Snowflake:

1. Database - the database where Honeydew will deploy any dynamic datasets as views or tables
2. Schema - the schema where Honeydew will deploy any dynamic datasets as views or tables
3. Dev Database - the database where Honeydew will deploy any dynamic datasets as views or tables when working on a dev branch
4. Dev Schema - the schema where Honeydew will deploy any dynamic datasets as views or tables when working on a dev branch

## Allowing Honeydew client IP addresses

If you have IP-based access restrictions in Snowflake,
add the IP addresses displayed in the Snowflake connection screen
in [Honeydew App settings page](https://app.honeydew.cloud/settings) to the "Allowed IP Addresses" list.

<Info>
  For the Honeydew Cloud deployment, the following IP addresses are used:

  * `34.86.209.90`
  * `34.145.147.92`

  If you are using a private Honeydew deployment, the IP addresses will be different.
  You can find them in the Snowflake connection screen in [Honeydew App settings page](https://app.honeydew.cloud/settings).
</Info>

## Snowflake Private Link

Honeydew supports
[Snowflake Private Link](https://docs.snowflake.com/en/user-guide/admin-security-privatelink)
connectivity for customers who require private,
secure connections that do not traverse the public internet.

To configure Snowflake Private Link for your Honeydew deployment,
contact [support@honeydew.ai](mailto:support@honeydew.ai).

## Permissions

Honeydew does not extract or store your data.
It only reads schema metadata and executes SQL queries inside your Snowflake environment.

You can find more security-related information [here](/docs/security/security).

If using an integration user deployment, the Honeydew integration user/role require the following permissions to operate:

1. **USAGE** on any databases and schemas which will be used as part of the semantic layer
2. **SELECT** on any tables/views which will be used as part of the semantic layer
3. **CREATE TABLE**, **CREATE DYNAMIC TABLE**, **CREATE INTERACTIVE TABLE** and **CREATE VIEW**
   on the database/schema where dynamic datasets will be deployed

## Snowflake Cortex Requirements

Honeydew has a growing number of AI-powered features, that can leverage Snowflake Cortex as the LLM models runner, if chosen.
This includes the Honeydew Analyst Bot, which provides AI-assisted data exploration and analysis capabilities.

To use Snowflake Cortex with Honeydew, you need to ensure the following requirements are met.

### Snowflake User Access Requirements

The Snowflake user used by Honeydew to connect to Snowflake, needs to have the **SNOWFLAKE.CORTEX\_USER** role.
This role is required for accessing Snowflake's AI/ML capabilities that power the bot's functionality.

```sql theme={null}
-- Grant the SNOWFLAKE.CORTEX_USER role to the user role created for Honeydew integration
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE HONEYDEW_USER_ROLE;
```

For more information about the `SNOWFLAKE.CORTEX_USER` role
and how to grant it, refer to the
[Snowflake Cortex documentation](https://docs.snowflake.com/user-guide/snowflake-cortex/aisql#required-privileges).

To use Cortex Code, grant the following additional permission to users:

```sql theme={null}
-- Required for all Cortex Code users
GRANT DATABASE ROLE SNOWFLAKE.COPILOT_USER TO ROLE <user_role>;
```

### Claude Sonnet Model Availability

The default model `claude-sonnet-4-6` is required to be available in your Snowflake Cortex
environment. If this model is not available in the region where your Snowflake account is
running, you can enable cross-region inference.

This also applies if your Snowflake account is running in a different cloud provider (**Azure**, **GCP**),
and the model you would like to use is only available in AWS.

To check the current cross-region inference configuration, you can use the following command:

```sql theme={null}
-- Check current cross-region inference configuration
SHOW PARAMETERS LIKE 'CORTEX_ENABLED_CROSS_REGION' IN ACCOUNT;
```

To enable cross-region inference, you can use one of the following commands:

**Enable across all regions:**

```sql theme={null}
-- Enable cross-region inference across all regions
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';
```

**Enable across specific regions (e.g., AWS\_US, AWS\_EU, etc.):**

```sql theme={null}
-- Enable cross-region inference to AWS_US
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_US';

-- Enable cross-region inference to AWS_EU
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_EU';
```

For more details about cross-region inference configuration,
see the [Snowflake Cortex Cross-Region Inference documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cross-region-inference).

### Cortex Models Allowlist

If your organization is using an allowlist of Cortex models,
you need to ensure the following models are included:

* `claude-sonnet-4-6` - The main model used for AI-powered features
* `llama3.1-8b` - Used for simple and fast tasks

Add any other model you select in the Honeydew LLM Provider settings, or in an
[agent](/docs/integration/context-layer/agents)'s `model` field, to the allowlist as well.

To configure the allowlist, execute the following SQL command in Snowflake:

```sql theme={null}
-- Add required Cortex models to the allowlist
ALTER ACCOUNT SET CORTEX_MODELS_ALLOWLIST = 'claude-sonnet-4-6,llama3.1-8b';
```

For more details about the account-level allowlist parameter and model access control,
see the [Snowflake Cortex AISQL documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/aisql#account-level-allowlist-parameter).

<Note>
  The list of the models used by Honeydew may change over time as new models are introduced
  or existing models are deprecated.
  Refer to the Honeydew release notes for any updates regarding Cortex model requirements.

  If you would like to be notified about such changes in advance, please contact [support@honeydew.ai](mailto:support@honeydew.ai).
</Note>

## Tracking Honeydew Queries in Snowflake

You can track and monitor queries executed by Honeydew in Snowflake using several methods.
All queries from Honeydew include a standardized query tag that provides detailed information
about the query context.

### Query Tag Format

All Honeydew queries include a query tag with the following JSON format:

```json theme={null}
{
  "application": "Honeydew",
  "workspace": "some_workspace",
  "branch": "branch_name",
  "user": "username@example.com",
  "client": "Honeydew Server"
}
```

The query tag contains:

* **application**: Always set to "Honeydew"
* **workspace**: The Honeydew workspace name
* **branch**: The Honeydew workspace branch being used (e.g., "dev", "prod")
* **user**: The Honeydew user identifier (usually email address)
* **client**: The client name, usually "Honeydew Server" for server-side operations

### Tracking Methods

You can track Honeydew queries using any of the following approaches:

#### 1. By User or Role

If you're using dedicated Snowflake users or roles for Honeydew integration,
you can filter queries by these identifiers in the `SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY` view.

#### 2. By Warehouse

If you're using dedicated warehouses for Honeydew operations,
you can filter by warehouse name in the `SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY` view.

#### 3. By Query Tag (Recommended)

The most comprehensive method is to filter by the Honeydew query tag.
This approach works regardless of your Snowflake setup and allows you to track queries
by workspace, branch, or user using the standardized query tag format.