> 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/references/dataos-resources/vulcan/incremental-by-time/import-snowflake-semantic-views.md).

# Import Snowflake semantic views

If you have a semantic view defined natively in Snowflake, you can import it into a Vulcan project instead of writing `kind: semantic` YAML by hand. Vulcan reads the view definition directly from Snowflake, translates it to the Vulcan semantic format, and writes one YAML file per table under `models/snowflake_semantic/`. The result is a standard Vulcan semantic layer with dimensions, measures, segments, joins, and REST, GraphQL, and SQL endpoints.

This guide covers the full workflow from a blank directory to a running REST API.

## Prerequisites

1. Vulcan installed with the Snowflake engine extra (`vulcan-<version>-py3-none-any.whl[snowflake]`).
2. A Snowflake connection configured in your `config.yaml`.
3. A Snowflake Semantic View created in Snowflake (requires Snowflake Enterprise edition or higher).

## Initialize your project

If you are starting from scratch:

```bash
mkdir my-project && cd my-project
vulcan init
```

Edit `config.yaml` to add your Snowflake gateway. The key-pair JWT method is recommended for production:

```yaml
gateways:
  default:
    connection:
      type: snowflake
      account: "{{ env_var('SNOWFLAKE_ACCOUNT') }}"
      user: "{{ env_var('SNOWFLAKE_USER') }}"
      authenticator: snowflake_jwt
      private_key_path: ./snowflake_key.p8
      private_key_passphrase: "{{ env_var('SNOWFLAKE_KEY_PASSPHRASE') }}"
      warehouse: "{{ env_var('SNOWFLAKE_WAREHOUSE') }}"
      database: "{{ env_var('SNOWFLAKE_DATABASE') }}"
    state_connection:
      type: duckdb
      database: ./.state/vulcan.db

model_defaults:
  dialect: snowflake
```

For the full connection fields and authentication options, see the [Engine guide](/references/engine-guide/engine-guide.md).

## Import the semantic view

Run `import_semantic_view` with the view name:

```bash
vulcan import_semantic_view MY_SEMANTIC_VIEW --connection default
```

To target a specific database and schema, use a fully qualified name (`MYDB.GOLD.MY_SEMANTIC_VIEW`). Vulcan calls `SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW()` on Snowflake and translates the result into `kind: semantic` files under `models/snowflake_semantic/MY_SEMANTIC_VIEW/`, one per table. Each file is a standard semantic model you can edit: add measures, adjust joins, or add `ai_context`.

## Generate external model stubs

Vulcan needs the column schema of the underlying Snowflake tables the view references:

```bash
vulcan create_external_models
```

This writes `inputs.yaml` to the project root, listing each source table with its columns and types, which Vulcan uses for join inference and query transpilation.

## Fix inputs.yaml

The generated `inputs.yaml` has two issues to correct before `vulcan plan` succeeds. For every entry:

```yaml
# Before
- name: "'MYDB'.'SCHEMA'.'ORDERS'"
  columns:
    O_ORDERKEY: DECIMAL(38, 0)

# After
- name: MYDB.SCHEMA.ORDERS
  dialect: snowflake
  grain:
    - O_ORDERKEY
  columns:
    O_ORDERKEY: DECIMAL(38, 0)
```

| Fix                                     | Why                                                                |
| --------------------------------------- | ------------------------------------------------------------------ |
| Remove the quotes around the table name | Quoted identifiers break table resolution during planning.         |
| Add `dialect: snowflake`                | Ensures the correct transpilation dialect for each external table. |
| Add `grain: [<primary_key>]`            | Required for join inference; use each table's primary key.         |

{% hint style="warning" %}
The extra quotes around table names in the generated `inputs.yaml` are a known issue tracked for a future release. Until then, unquote each table name manually before running `vulcan plan`.
{% endhint %}

## Plan

```bash
vulcan plan
```

Review the output and confirm. Vulcan registers all imported semantic models and makes them queryable.

## Query via the REST API

Start the API server with `vulcan api`, then query a measure:

```bash
curl -X POST http://localhost:8000/api/v1/query/semantic/rest \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "measures": ["ORDERS.ORDER_COUNT"],
      "dimensions": ["ORDERS.O_ORDERSTATUS"],
      "segments": ["ORDERS.HIGH_VALUE"]
    }
  }'
```

{% hint style="info" %}
Snowflake stores unquoted identifiers in uppercase. Measure, dimension, and segment names in API queries must match the uppercase identifiers in the imported YAML exactly.
{% endhint %}

## Re-import after a view change

If the Snowflake Semantic View definition changes, remove the translated files and `inputs.yaml`, re-import, regenerate the stubs, reapply the `inputs.yaml` fixes, and run `vulcan plan`:

```bash
rm -rf models/snowflake_semantic/MY_SEMANTIC_VIEW/
rm inputs.yaml
vulcan import_semantic_view MY_SEMANTIC_VIEW --connection default
vulcan create_external_models
```

## Related docs

* [Semantic model and components](/references/dataos-resources/vulcan/core-concepts/semantic-model-and-components.md): edit and extend the generated YAML.
* [Semantic query lifecycle guide](/references/dataos-resources/vulcan/incremental-by-time/semantic-query-lifecycle.md): how a query against the imported view resolves.
* [Engine guide](/references/engine-guide/engine-guide.md): Snowflake connection, identifier casing, and permissions.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/dataos-resources/vulcan/incremental-by-time/import-snowflake-semantic-views.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.