omni-to-snowflake-semantic-view

The definitions behind an Omni report — the measures, the tables they draw on, the wording — rewritten as something Snowflake itself understands, so Snowflake's own AI analyst can answer from them.

WHEN TO USE

SCOPE

USE FOR

Give Snowflake Cortex Analyst access to metrics already defined in Omni.
Move a governed metric definition from Omni into Snowflake without redefining it by hand.
Recreate an Omni topic's joins, dimensions, and measures as a native Snowflake object.
Grant a specific Snowflake role access to metrics that originate in Omni.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (5)

Omni → Snowflake Semantic View

Converts an Omni topic into a Snowflake Semantic View YAML definition by first exploring the Omni model via API, then translating its definitions into the Snowflake Semantic View format.

Prerequisites

# Verify the Omni CLI is installed — if not, ask the user to install it
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Show available profiles and select the appropriate one
omni config show
# If multiple profiles exist, ask the user which to use, then switch:
omni config use <profile-name>

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

Auth: a profile authenticates with an API key or OAuth. If whoami (or any call) returns 401, hand off — ask the user to run ! omni config login <profile> (OAuth 2.1 browser flow; it blocks ~2 min on the browser). Don't run config login yourself in a headless/CI session (no browser → timeout); on a local interactive machine you may. See the omni-api-conventions rule for profile setup (omni config init --auth oauth) and discovering command and request-body shapes with --schema.

Tip: Use -o json to force structured output for programmatic parsing, or -o human for readable tables. The default is auto (human in a TTY, JSON when piped).

Runtime Environment Detection

Before starting, determine which environment you are running in — this controls how SQL is executed against Snowflake in Step 7.

How to detect

Check for the presence of the built-in Snowflake SQL execution capability:

Cortex Code (Snowflake Notebooks / Cortex Analyst): Native SQL execution is available. No extra tooling required.
Claude Code, Cursor, or any external IDE/agent: No native Snowflake connection. You must use one of the CLI options below.

Detection heuristic

If the agent can execute a SQL statement like `SELECT CURRENT_USER()` directly without any shell command → you are in Cortex Code.
Otherwise → you are in an external environment.

If unsure, ask the user: "Are you running this inside Snowflake (Cortex Code / Notebooks), or in an external tool like Claude Code or Cursor?"

External environment: Snowflake connectivity options

For Claude Code, Cursor, or any terminal-based agent, choose one of the following. Check availability in order:

Option A — Snowflake CLI (`snow`) ✅ Recommended

# Check if available
command -v snow

# Configure a connection (first time)
snow connection add

# Execute SQL
snow sql -q "SELECT CURRENT_USER();" --connection <connection_name>

Set a default connection to avoid repeating --connection on every call:

snow connection set-default <connection_name>

Option B — SnowSQL (classic CLI)

# Check if available
command -v snowsql

# Execute SQL
snowsql -a <account> -u <user> -q "SELECT CURRENT_USER();"

Option C — Python (`snowflake-connector-python`)

pip install snowflake-connector-python

import snowflake.connector
conn = snowflake.connector.connect(
    account="<account>",
    user="<user>",
    password="<password>",   # or use key-pair / SSO
    warehouse="<warehouse>",
    database="<database>",
    schema="<schema>",
)
conn.cursor().execute("<SQL here>")

✋ STOP — Confirm the Snowflake connection method with the user before proceeding to Step 7. Record which method is being used so Step 7 generates the correct execution command.

Workflow

Step 1 — Gather Requirements

Ask the user:

Which Topic do they want to convert?
What should the Semantic View be named?
Where should it be created in Snowflake (database and schema)?
Which role should be granted access to the Semantic View?

⚠️ STOP — Confirm all four answers before proceeding.

Step 2 — Explore the Omni Model

2a. Find the model ID

omni models list --model-kind SHARED

Identify the Shared Model and note its id. Always prefer the Shared Model over Schema or Workbook models.

2b. Fetch the topic file

omni models yaml-get <modelId> --file-name <topic_name>.topic

2c. Fetch the relationships file

omni models yaml-get <modelId> --file-name relationships

2d. Fetch each view file referenced in the topic

For every view in base_view and joins, fetch its YAML:

omni models yaml-get <modelId> --file-name <view_name>.view

If a view is prefixed with omni_dbt_, fetch the file that also starts with omni_dbt_ (e.g. omni_dbt_ecomm__order_items.view).

Step 3 — Identify Tables and Joins

Mapping view names to Snowflake tables

The base_view in the topic file is the primary table. Convert view names to Snowflake table references:

`base_view` / join value	Snowflake table
`ecomm__order_items`	`ECOMM.ORDER_ITEMS`
`omni_dbt_ecomm__order_items`	`ECOMM.ORDER_ITEMS` (strip `omni_dbt_`)

The __ separator maps to schema (left) and table name (right). If the schema does not exist in Snowflake, skip that table entirely.

Reading the join hierarchy

The joins parameter in the topic uses indentation to define the join chain — a table indented beneath another joins into its parent:

joins:
  user_order_facts: {}        # skip — this is a derived CTE, not a physical table
  ecomm__users: {}            # joins to base_view (ORDER_ITEMS)
  ecomm__inventory_items:     # joins to base_view (ORDER_ITEMS)
    ecomm__products:          # joins to INVENTORY_ITEMS
      demo__product_images: {}           # joins to PRODUCTS
      ecomm__distribution_centers: {}   # joins to PRODUCTS

Skip any view that is a derived table (CTE defined in SQL in Omni). These have no physical Snowflake table to reference.

Primary keys

In each view file, find the dimension with primary_key: true — this becomes the unique: true dimension in the Semantic View.

✋ STOP — Confirm the table list with the user before continuing.

Step 4 — Resolve the Field List

The topic's fields parameter controls which fields from the views are included in the Semantic View.

Field targeting rules

Syntax	Meaning
(no `fields` parameter)	Include all fields from all views
`all_views.*`	Include all fields from all views
`view.*`	Include all fields in the named view
`tag:<value>`	Include all fields tagged with this value
`view.field`	Include this specific field
`-view.field`	Exclude this specific field

How to apply exclusions correctly

Exclusions (prefixed with -) must be applied after all inclusions are resolved. The process is:

Start with an empty inclusion set
Process each entry in fields in order:
- If it is an inclusion rule (view.*, view.field, tag:x) → add matching fields to the set
- If it is an exclusion rule (-view.field) → remove that field from the set, even if it was added by a wildcard
The final set is the complete list of fields to include in the Semantic View

Example:

fields:
  - ecomm__order_items.*          # include all order_items fields
  - ecomm__users.country          # include this one users field
  - -ecomm__order_items.cost      # remove cost — excluded even though * was used above
  - -ecomm__order_items.raw_json  # remove raw_json — same reason

Result: all order_items fields except cost and raw_json, plus users.country.

⚠️ Critical: A - exclusion always wins. Never include a field that has been explicitly excluded, regardless of what wildcard included it.

Step 5 — Build Relationships

Using the join hierarchy from Step 3 and the relationships.yaml fetched in Step 2c, map each join to a Snowflake Semantic View relationship.

Each entry in relationships.yaml looks like:

- join_from_view: ecomm__order_items
  join_to_view: ecomm__inventory_items
  join_type: always_left
  on_sql: ${ecomm__order_items.inventory_item_id} = ${ecomm__inventory_items.id}
  relationship_type: assumed_many_to_one

The on_sql field tells you the join columns. Extract the column names to populate relationship_columns in the output.

Available relationship parameters:

Parameter	Description
`join_from_view`	Source view the join originates from
`join_to_view`	Target view being joined to
`join_type`	SQL join type (e.g. `always_left`)
`on_sql`	SQL condition — extract column names from this
`relationship_type`	Cardinality (e.g. `assumed_many_to_one`)
`reversible`	Whether the join is bi-directional
`where_sql`	Additional WHERE clause when join is active

Step 6 — Map Dimensions and Measures

For each view in the resolved field list, translate its Omni field definitions into Semantic View entries.

⚠️ Only translate fields that survived the Step 4 inclusion/exclusion resolution. Do not add fields that were excluded.

Dimensions → `dimensions` or `time_dimensions`

The field name becomes the dimension name unless a label is defined. Carry description and synonyms directly.

Standard dimension:

# Omni view YAML
city:
  sql: '"CITY"'
  label: City
  description: Customer's city

# Semantic View output
- name: city
  expr: CITY
  description: Customer's city
  data_type: TEXT

Date/timestamp dimension → use time_dimensions:

# Omni
created_at:
  sql: '"CREATED_AT"'
  type: time
  label: Created At

# Semantic View output
time_dimensions:
  - name: created_at
    expr: CREATED_AT
    data_type: TIMESTAMP

Group dimension → translate to a CASE WHEN expression:

# Omni
device_type_groups:
  sql: ${device_type}
  label: Device Type Groups
  groups:
    - filter:
        is: [ mobile, tablet ]
      name: Handheld
    - filter:
        is: desktop
      name: Desktop
  else: Other

-- expr value
CASE
  WHEN "DEVICE_TYPE" IN ('mobile', 'tablet') THEN 'Handheld'
  WHEN "DEVICE_TYPE" = 'desktop' THEN 'Desktop'
  ELSE 'Other'
END

Bin dimension → translate to a CASE WHEN range expression:

# Omni
age_bin:
  sql: ${age}
  bin_boundaries: [ 18, 35, 50, 65 ]

-- expr value
CASE
  WHEN "AGE" < 18 THEN 'below 18'
  WHEN "AGE" >= 18 AND "AGE" < 35 THEN '>= 18 and < 35'
  WHEN "AGE" >= 35 AND "AGE" < 50 THEN '>= 35 and < 50'
  WHEN "AGE" >= 50 AND "AGE" < 65 THEN '>= 50 and < 65'
  WHEN "AGE" >= 65 THEN '65 and above'
  ELSE NULL
END

Duration dimension → translate to a TIMESTAMPDIFF expression:

# Omni
fulfillment_days:
  duration:
    sql_start: ${created_at[date]}
    sql_end: ${delivered_at[date]}
    intervals: [ days ]

-- expr value (days)
CASE
  WHEN TIMESTAMPADD(DAY, 1 * TIMESTAMPDIFF(DAY, DATE_TRUNC('DAY', "CREATED_AT"), DATE_TRUNC('DAY', "DELIVERED_AT")), DATE_TRUNC('DAY', "CREATED_AT"))
       <= DATE_TRUNC('DAY', "DELIVERED_AT")
  THEN TIMESTAMPDIFF(DAY, DATE_TRUNC('DAY', "CREATED_AT"), DATE_TRUNC('DAY', "DELIVERED_AT"))
  ELSE TIMESTAMPDIFF(DAY, DATE_TRUNC('DAY', "CREATED_AT"), DATE_TRUNC('DAY', "DELIVERED_AT")) - 1
END

Boolean dimension → becomes a named filter (not a dimension):

# Omni
is_returned:
  sql: '"IS_RETURNED"'
  description: Whether the item was returned

completed_orders:
  sql: ${status} = 'Complete'
  label: Completed Orders

# Semantic View output — goes in filters, not dimensions
filters:
  - name: is_returned
    expr: IS_RETURNED
    description: Whether the item was returned
  - name: completed_orders
    expr: STATUS = 'Complete'
    description: Completed Orders

Measures → `metrics`

The sql field references the source column and aggregate_type defines the aggregation.

Standard measure:

# Omni
total_sale_price:
  sql: ${sale_price}
  aggregate_type: sum
  label: Total Sale Price
  description: Total revenue of orders
  synonyms: [ Total Revenue, Total Receipts ]

# Semantic View output
metrics:
  - name: total_sale_price
    expr: COALESCE(SUM("SALE_PRICE"), 0)
    description: Total revenue of orders
    synonyms: [ Total Revenue, Total Receipts ]

Derived measure (no aggregate_type) — references other measures:

# Omni
gross_margin:
  sql: ${total_sale_price} - ${total_cost}
  label: Gross Margin

# Semantic View output — top-level derived metric
metrics:
  - name: gross_margin
    expr: total_sale_price - total_cost

Filtered measure → wraps in CASE WHEN:

# Omni
california_revenue:
  sql: ${sale_price}
  aggregate_type: sum
  filters:
    users.state:
      is: California

-- expr value
COALESCE(SUM(CASE WHEN "users"."STATE" = 'California' THEN "SALE_PRICE" ELSE NULL END), 0)

Array and boolean filter variants:

# is: [New York, New Jersey]  →  "STATE" IN ('New York', 'New Jersey')
# is: true                    →  field IS TRUE

Filter-Only Fields (Templated Filters)

Filter-only fields in Omni are parameterized inputs defined in a filters: block in a view YAML. They don't map to a real column — they inject dynamic values into other fields' SQL at query time via Mustache templates. Snowflake Semantic Views have no equivalent runtime parameter system, so these must be resolved to static SQL during conversion.

Example filter-only field definition:

# In a view file — under a top-level `filters:` key
filters:
  status_filter:
    type: string
    default_filter:
      is: "Complete"
  order_date_filter:
    type: timestamp

Two reference patterns to detect in dimension/measure SQL:

Pattern 1 — Block (conditional) syntax:

{{# order_items.status_filter.filter }} order_items.status {{/ order_items.status_filter.filter }}

The block is conditionally active when the user applies a filter. A {{^ }} block is the fallback when no filter is applied:

{{# order_items.status_filter.filter }} order_items.status {{/ order_items.status_filter.filter }}
{{^ order_items.status_filter.filter }} 1=1 {{/ order_items.status_filter.filter }}

Pattern 2 — Value (direct injection) syntax:

-- Direct value substitution
DATE_TRUNC('day', created_at) >= '{{filters.order_items.order_date_filter.value}}'

-- Range variants for date filters
created_at BETWEEN '{{filters.order_items.order_date_filter.range_start}}' AND '{{filters.order_items.order_date_filter.range_end}}'

Scan all dimension and measure SQL for both patterns using these signatures:

{{# <view>.<field>.filter }} — block open
{{^ <view>.<field>.filter }} — block fallback open
{{filters.<view>.<field>.value}} — direct value
{{filters.<view>.<field>.range_start}} / {{filters.<view>.<field>.range_end}} — date ranges

Resolution logic — apply in order for each reference found:

Step 1 — Inline {{^ }} fallback (block pattern only):

If the SQL contains a {{^ view.field.filter }} fallback block, use the fallback expression as the static SQL — it's what executes when no filter is applied.

-- Input
{{# order_items.status_filter.filter }} order_items.status {{/ order_items.status_filter.filter }}
{{^ order_items.status_filter.filter }} 1=1 {{/ order_items.status_filter.filter }}

-- Resolved static SQL
1=1

Step 2 — default_filter on the filter field definition:

Find the referenced filter-only field in the view YAML and check for a default_filter property. Render it as a static SQL condition:

`default_filter` value	Rendered SQL
`is: "Complete"`	`field = 'Complete'`
`is: ["New York", "CA"]`	`field IN ('New York', 'CA')`
`is: true`	`field IS TRUE`
`greater_than: 100`	`field > 100`

For value syntax, substitute the rendered scalar value directly into the SQL string:

-- Input
DATE_TRUNC('day', created_at) >= '{{filters.order_items.order_date_filter.value}}'

-- default_filter: is: "2024-01-01"
-- Resolved
DATE_TRUNC('day', created_at) >= '2024-01-01'

For range syntax, use range_start / range_end from the default_filter if defined, otherwise warn the user.

Step 3 — No fallback and no default_filter — warn the user:

⚠️ Field <view>.<field> references filter-only field <view>.<filter_field> but has no default_filter and no inline {{^ }} fallback. It cannot be statically resolved for a Snowflake Semantic View. Options:

Skip this field from the output entirely.

Ask the user what static value or condition to hardcode.

Use 1=1 (always-true no-op) to preserve the field shape without the filter effect.

Summary decision tree:

Does the SQL reference a filter-only field?
  (via {{# view.field.filter }} OR {{filters.view.field.value}} etc.)
  │
  ├── Block pattern → Does SQL have {{^ view.field.filter }} fallback?
  │     ├── Yes → Use fallback expression as static SQL
  │     └── No  → Go to default_filter check ↓
  │
  ├── Value pattern → Go to default_filter check ↓
  │
  └── default_filter check:
        ├── Yes → Render default_filter as static SQL / value substitution
        └── No  → Warn user, ask how to proceed

⚠️ Filter-only fields themselves are never emitted as dimensions, metrics, or filters in the Semantic View output — they exist only to parameterize other fields' SQL.

AI Context → `module_custom_instructions`

If the topic has an ai_context parameter, include it as:

module_custom_instructions:
  question_categorization: <ai_context value>

Sample Queries → `verified_queries`

Convert each entry under sample_queries into a SQL statement for verified_queries. Use the prompt as the question and the description as context for writing the SQL.

✋ STOP — Review all dimensions, measures, and relationships with the user before generating the final output.

Step 7 — Generate and Execute the Semantic View

Output YAML structure

name: <name>
description: <string>

tables:
  - name: <name>
    description: <string>
    base_table:
      database: <database>
      schema: <schema>
      table: <table name>

    dimensions:
      - name: <name>
        synonyms: [ <string>, ... ]
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>

    time_dimensions:
      - name: <name>
        synonyms: [ <string>, ... ]
        description: <string>
        expr: <SQL expression>
        data_type: <data type>

    facts:
      - name: <name>
        synonyms: [ <string>, ... ]
        description: <string>
        expr: <SQL expression>
        data_type: <data type>

    metrics:
      - name: <name>
        synonyms: [ <string>, ... ]
        description: <string>
        expr: <SQL expression>

    filters:
      - name: <name>
        synonyms: [ <string>, ... ]
        description: <string>
        expr: <SQL expression>

relationships:
  - name: <string>
    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>

metrics:
  - name: <name>
    synonyms: [ <string>, ... ]
    description: <string>
    expr: <SQL expression>

verified_queries:
  - name: <string>
    question: <string>
    sql: <string>
    use_as_onboarding_question: <boolean>

Valid top-level keys only: name, description, tables, relationships, metrics, verified_queries, module_custom_instructions

Create the Semantic View

The SQL is the same regardless of environment. The difference is how it is executed.

SQL to run:

CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML('<database>.<schema>', $$
<yaml content here>
$$);

Execution by environment:

Environment	Command
Cortex Code	Execute the SQL directly in the active Snowflake session
`snow` CLI	`snow sql -q "CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML(...)"` or write YAML to a temp file and pipe it
SnowSQL	`snowsql -a <account> -u <user> -f <sql_file.sql>`
Python	`conn.cursor().execute("<sql>")`

Tip for CLI environments: If the YAML is long, write it to a temporary .sql file first and execute the file rather than passing it inline — this avoids shell escaping issues with the $$ dollar-quoting.

# snow CLI example with a file
snow sql -f /tmp/create_semantic_view.sql

Grant access

GRANT SELECT ON SEMANTIC VIEW <database>.<schema>.<name> TO ROLE <role>;

Execute this the same way as the CREATE call above, using whichever connection method was established during the Runtime Environment Detection step.

Reference

This skill ships inside the Omni Analytics Agent Skills plugin. Listed package contents include 3 agents. Installed components and skill versions may vary by AI tool.

Install as a Claude Code plugin

Typed inside the agent's own prompt, not in a terminal. This skill uses files kept elsewhere in its plugin, so install the whole plugin — on its own the skill would be missing them.

/plugin marketplace add exploreomni/omni-agent-skills

/plugin install omni-analytics@omni-analytics

What's inside

Files included with this skill.

View on GitHub

Same repository

omni-admin
Administer an Omni Analytics instance — manage connections, users, groups, user attributes, permissions, schedules, and schema refreshes via the Omni CLI. Use this skill whenever someone wants to manage users or groups, set up permissions on a dashboard or folder, configure user attributes, create or modify schedules, manage database connections, refresh a schema, set up access controls, provision users, or any variant of "add a user", "give access to", "set up permissions", "who has access", "configure connection", "refresh the schema", or "schedule a delivery".Read full description
omni-ai-eval
Evaluate Omni AI accuracy using Omni's built-in eval system — define a prompt set, run a judged eval against a model (or branch), and read the accuracy-judge verdicts. Use this skill whenever someone wants to evaluate Omni AI, benchmark Blobby, run regression tests, compare AI output across branches or model-context changes, measure AI quality, run A/B tests on model changes, assess the impact of an ai_context or modeling change, or any variant of "run evals", "test Blobby", "benchmark query generation", "compare AI results", "regression test", "how accurate is the AI", or "measure the impact of my changes".Read full description
omni-ai-optimizer
Optimize your Omni Analytics model for Blobby, the Omni Agent — configure ai_context, ai_fields, synonyms, sample_queries, and AI-specific topic extensions. Use this skill whenever someone wants to improve AI accuracy in Omni, make Blobby smarter, add AI context or example questions, curate which fields the AI sees, personalize AI context by user attribute, scope context to a model tier or agent, diagnose context-window pruning or truncation, control which topics AI can reach, troubleshoot why Blobby gives wrong answers, or any variant of "make the AI better", "Blobby isn't answering correctly", "optimize for AI", or "teach the AI about our data".Read full description
omni-content-builder
Create, update, and manage Omni Analytics documents and dashboards programmatically — document lifecycle, drafts, tiles, visualizations, filters, controls, and layouts — using the Omni CLI. Use this skill whenever someone wants to build a dashboard, create a workbook or document, add tiles or charts, configure dashboard filters or controls, set up a KPI view, lay out or rearrange tiles and pages, edit a dashboard as a draft and publish it, change dashboard settings, rename/move/duplicate/delete a dashboard, modify dashboard-level model customizations like workbook-specific joins or fields, or build and edit an Omni app (custom HTML content in place of a dashboard) — including casual phrasings like "make a dashboard for…", "add a chart to…", or "clean up this dashboard's layout" that don't name the skill. For running a query or pulling metrics use omni-query; for adding a field to the shared model use omni-model-builder.Read full description
omni-content-explorer
Find, browse, and organize content in Omni Analytics — dashboards, workbooks, folders, and labels — using the Omni CLI. Use this skill whenever someone wants to find an existing dashboard, search for content, list workbooks, browse folders, see what dashboards exist, find popular reports, download a dashboard as PDF or PNG, favorite content, manage labels on documents, or any variant of "find the dashboard about", "what reports do we have", "show me our dashboards", "where is the sales report", or "download this dashboard".Read full description
omni-embed
Embed Omni Analytics dashboards in external applications — URL signing, custom themes, iframe events, entity workspaces, and permission-aware content — using the @omni-co/embed SDK and Omni CLI. Use this skill whenever someone wants to embed a dashboard, sign an embed URL, customize the embedded theme, handle embed events, listen for clicks or drills in the iframe, send filters to an embedded dashboard, set up entity workspaces, look up embed users, build a permission-aware content list, white-label an embedded dashboard, or any variant of "embed this dashboard", "customize the iframe theme", "handle click events from the embed", "filter the embedded dashboard", "set up embedding", or "what dashboards can this user see".Read full description