> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/productize/connect-engine/snowflake.md).

# Snowflake

Configure Snowflake as the engine for your Data Product.

Snowflake is a cloud data warehouse for governed, SQL-first enterprise analytics. Use the `snowflake` adapter when your data already lives in Snowflake. This page covers the connection. For materialization internals, tuning, and the full reference, see the [Snowflake engine manual](https://v2.dataos.info/references/engine-guide/snowflake) in References.

## Before you start

* A Snowflake account with valid credentials.
* A warehouse available for running computations.
* DataOS access: a `roles:id:data-dev`-equivalent role tag, `depot:rw:<snowflake-depot-name>` (or `depot:r` for read-only), **Can Use** on Compute/Depots/Secrets, and a git-sync Secret. Verify with `dataos-ctl user get` and `dataos-ctl resource -t depot get -a`.

## Permissions

Snowflake access splits into two grants: read-only on the schemas Vulcan reads, and managed access on the schema where Vulcan writes output.

* **Source schemas (read-only)** - grant `USAGE` on the warehouse, database, and schema, and `SELECT` on all and future tables and views.
* **Target schema (Vulcan-managed)** - grant `CREATE SCHEMA` on the database, then `USAGE`, `CREATE TABLE`, and `CREATE VIEW` on the schema, `SELECT, INSERT, UPDATE, DELETE, TRUNCATE` on all and future tables, and `SELECT` on all and future views.

Vulcan needs `DELETE` because it deletes a slice's rows before reinserting refreshed rows during incremental rebuilds, and `TRUNCATE` for full refreshes. Grant `OWNERSHIP` only if DataOS must manage the schema lifecycle (`ALTER`, `REPLACE`, `DROP`). The exact grants also depend on whether source and target share one database or span two: see the [minimum-permissions reference](https://v2.dataos.info/references/resources/vulcan/roles-and-permissions/snowflake-minimum-permissions) for the single-database, cross-database, and semantic-read-only tiers.

{% hint style="warning" %}
When connecting through a Depot, Vulcan reads the Snowflake `role` from the `role` key in the DataOS secret projection, not from the depot spec. If this project uses a custom role, make sure that key is set in the secret. Otherwise, Vulcan silently falls back to the connection's default role.
{% endhint %}

## Connection options

| Option                                       |   Required  | Description                                                                                   |
| -------------------------------------------- | :---------: | --------------------------------------------------------------------------------------------- |
| `type`                                       |     Yes     | Must be `snowflake`                                                                           |
| `account`                                    |     Yes     | Account identifier, format `<org-name>-<account-name>`                                        |
| `user`                                       |     Yes     | Authentication username                                                                       |
| `password`                                   | Conditional | Required only for username/password auth — not needed for JWT, OAuth, or external-browser SSO |
| `warehouse`                                  |     Yes     | Warehouse for computations                                                                    |
| `database`                                   |     Yes     | Database to connect to                                                                        |
| `role`                                       |      No     | Role for authentication                                                                       |
| `authenticator`                              |      No     | Method, for example `externalbrowser` or `oauth`                                              |
| `token`                                      |      No     | OAuth 2.0 access token                                                                        |
| `private_key_path`, `private_key_passphrase` |      No     | Private key authentication                                                                    |

### Authentication methods

* **Key-pair JWT** (recommended for production): set `authenticator: snowflake_jwt`, `private_key_path`, and `private_key_passphrase`. Generate the key pair once per developer machine (`openssl genrsa` then `openssl pkcs8`), keep the `.p8` file out of version control, and register the public key with `ALTER USER <your_user> SET RSA_PUBLIC_KEY = '<contents_of_key.pem>';`.
* **Username and password**: set `user` and `password`.
* **OAuth 2.0 token**: set `authenticator: oauth` and `token`.
* **External browser SSO**: set `authenticator: externalbrowser`.
* **Role-based**: set `role`.

{% hint style="danger" %}
OAuth and external-browser SSO are not recommended for production gateway connections. Use key-pair JWT for service accounts.
{% endhint %}

## Example

```yaml
gateways:
  snowflake:
    connection:
      type: snowflake
      account: <org-name-account-name>
      user: <username>
      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
      warehouse: <warehouse-name>
      database: <database-name>
      role: <role-name>
```

Find the account identifier in your Snowflake URL.

### Using a Depot

Snowflake has no local Docker setup, so production connects through a Depot instead of raw credentials:

```yaml
gateways:
  default:
    connection:
      type: depot
      address: dataos://snowflakedepot?purpose=rw
```

A depot is registered with one or more purposes (`rw`, `scan`, `query`): bind the purpose to the credential's actual use; a `query` credential can't create tables, and handing an `rw` credential to a consumer over-permissions them.

## Supported model kinds

`FULL`, `SEED`, `VIEW`, `INCREMENTAL_BY_TIME_RANGE`, `INCREMENTAL_BY_UNIQUE_KEY`, `INCREMENTAL_BY_PARTITION`, `MANAGED` (Dynamic Tables, Enterprise and above), `SCD_TYPE_2`, `SCD_TYPE_2_BY_TIME`, and `SCD_TYPE_2_BY_COLUMN`. `FULL` compiles to `CREATE OR REPLACE TABLE`, `VIEW` to `CREATE OR REPLACE VIEW`, `INCREMENTAL_BY_UNIQUE_KEY` to `MERGE` on the unique key, `MANAGED` to `CREATE OR REPLACE DYNAMIC TABLE`, and the `SCD_TYPE_2` kinds to a `MERGE` implementing SCD Type 2. For the full mapping, see the [Snowflake engine manual](https://v2.dataos.info/references/engine-guide/snowflake).

> Snowflake stores unquoted identifiers in UPPERCASE. Column names in dimensions, measures, filters, and joins must be uppercase, or the warehouse won't resolve them. See the engine manual for the full casing rules.

Guard raw DDL/DML in `pre_statements` / `post_statements` / `before_all` / `after_all` with `@IF(@runtime_stage = 'evaluating', ...)`, or `vulcan plan` executes it. For Snowpark Python models, import Snowpark functions inside `execute()`, not at module scope — a module-level `from snowflake.snowpark.functions import col` raises `NameError: 'col' is not defined`. `vulcan create_external_models` only inspects the gateway database; declare cross-database sources manually in `inputs.yaml` with triple-quoted identifiers (for example `'"SNOWFLAKE_SAMPLE_DATA"."TPCH_SF1"."ORDERS"'`), or the linter reports `Table not found`.

## Limits and performance

Match warehouse size to the workload rather than one size for everything: X-SMALL/SMALL for dev iteration, LARGE/X-LARGE for a first backfill, MEDIUM for daily incrementals, and LARGE with a raised `MAX_CONCURRENCY_LEVEL` for the semantic API or concurrent BI. Set `AUTO_SUSPEND = 60` and `AUTO_RESUME = TRUE` for bursty workloads. Keep `concurrent_tasks` at or below `MAX_CONCURRENCY_LEVEL / 3`, and keep `api.resources.limits.memory` at 3 GiB.

Cap spend with a resource monitor, set query and queued timeouts, and tag queries for attribution:

```sql
CREATE RESOURCE MONITOR vulcan_monthly_cap
  WITH CREDIT_QUOTA = 500 FREQUENCY = MONTHLY START_TIMESTAMP = IMMEDIATELY
  TRIGGERS ON 75 PERCENT DO NOTIFY ON 90 PERCENT DO SUSPEND ON 100 PERCENT DO SUSPEND_IMMEDIATE;
```

On TPC-H SF1000 baselines (Medium warehouse), cross-join-heavy queries ran up to 30x slower than standard queries. Fix SQL shape first, then add API replicas, raise `MAX_CONCURRENCY_LEVEL`, and size up the warehouse last.

## Troubleshooting

| Symptom                                     | Likely cause                                   | Fix                                                             |
| ------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------- |
| JWT token invalid on first run              | Public key missing, or PEM/passphrase mismatch | Run `ALTER USER ... SET RSA_PUBLIC_KEY`; verify the passphrase. |
| `Object 'COL' does not exist`               | Semantic model uses lowercase identifiers      | Use UPPERCASE identifiers.                                      |
| `Table not found: SNOWFLAKE_SAMPLE_DATA...` | Cross-database source not declared             | Add a triple-quoted identifier to `inputs.yaml`.                |
| `vulcan plan` runs DDL                      | Lifecycle DDL not guarded                      | Wrap it in `@IF(@runtime_stage = 'evaluating', ...)`.           |
| `NameError: 'col' is not defined`           | Snowpark functions imported at module scope    | Import them inside `execute()`.                                 |
| Endpoint OOM                                | API memory below 1.5 GiB                       | Raise it to 3 GiB.                                              |

For the full failure-mode table, health-check queries, and recovery procedures, see [Troubleshooting](https://v2.dataos.info/references/engine-guide/snowflake/troubleshooting) in the Snowflake engine manual.

Once `vulcan info` succeeds, continue to [Assets](https://v2.dataos.info/build/productize/assets.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/build/productize/connect-engine/snowflake.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
