---
name: semantic-view
description: "**[REQUIRED]** Use for ALL requests that mention: create, build, debug, fix, troubleshoot, optimize, improve, or analyze a semantic view — AND for requests about VQR suggestions, verified queries, verified query representations, seeding/generating queries, suggesting metrics, suggesting filters, recommending metrics/filters/facts, or enriching a semantic view. This is the REQUIRED entry point - even if the request seems simple. DO NOT attempt to create, debug, or generate suggestions for semantic views manually - always invoke this skill first. This skill guides users through creation, setup, auditing, VQR suggestion generation, filter & metric suggestions, and SQL generation debugging workflows for semantic views with Cortex Analyst."
---

# Semantic View Skill

## When to Use

When a user wants to create, debug, optimize semantic views, generate VQR (verified query) suggestions, or get filter & metric suggestions for Cortex Analyst. This is the entry point for all semantic view workflows including VQR and filter/metric suggestion generation.

## Prerequisites

- Fully qualified semantic view name (DATABASE.SCHEMA.VIEW_NAME)
- Snowflake access configured
- Python dependencies: `tomli`, `urllib3`, `requests`, `pyyaml`, `snowflake-connector-python`
  - Install via: `uv pip install tomli urllib3 requests pyyaml snowflake-connector-python`

## ⚠️ MANDATORY INITIALIZATION (Required Before ANY Workflow)

**Before creating, auditing, or debugging semantic views, you MUST complete initialization:**

### Step 1: Load Core Concepts ✋ BLOCKING

**Load**: [semantic_view_concepts.md](reference/semantic_view_concepts.md)

\*After loading, confirm you understand:\*\*

- Logical vs physical table/column names
- Which semantic model elements can be added vs enhanced only
- Required use of semantic_view_get.py and semantic_view_set.py tools

**DO NOT PROCEED until you have loaded semantic_view_concepts.md.**

### Step 2: Complete Setup ✋ BLOCKING

**Load**: [setup/SKILL.md](setup/SKILL.md)

**This will:**

- Get BASE_WORKING_DIR from user (where to create files)
- Create session directory WORKING_DIR (timestamped)

**After setup completes, you will have these variables:**

- `SKILL_BASE_DIR` - Script location
- `BASE_WORKING_DIR` - User's chosen base directory
- `WORKING_DIR` - Session directory: `{BASE_WORKING_DIR}/semantic_view_{TIMESTAMP}`

**DO NOT PROCEED until setup is complete.**

### Step 3: Workflow Routing and Available Skills ✋

**After setup completes**, you will be routed to the appropriate workflow based on whether you're working with a NEW or EXISTING semantic view.

#### Workflow Decision Tree

```
Setup/SKILL.md Part 2: Workflow Routing
    ↓
Determine: NEW, IMPORT, EXISTING, VQR SUGGESTIONS, or FILTER & METRIC SUGGESTIONS?
    ↓
┌────┴────┬──────────┬──────────┬──────────┐
↓         ↓          ↓          ↓          ↓
NEW     IMPORT    EXISTING   VQR       FILTERS &
↓         ↓          ↓      SUGGEST.   METRICS
Load    Load      Continue    ↓          ↓
creation/ import_     to     Load       Load
SKILL.md  tableau/   Part 3  vqr_       filters_and_
          SKILL.md          suggestions/ metrics_suggestions/
                            SKILL.md    SKILL.md
    ↓        ↓          ↓
Create   Import     Create
creation/ Tableau   optimization/
subdir    file      subdir
    ↓        ↓          ↓
Generate Generate   Download
semantic semantic   existing
model    model      model
                       ↓
                   Present mode
                   selection
                       ↓
                   ┌───┴───┐
                   ↓       ↓
               AUDIT    DEBUG
                MODE     MODE
```

#### Supporting Skills Available

Throughout any workflow, you can load these supporting skills as needed:

**Validation**:

- **Load**: [validation/SKILL.md](validation/SKILL.md)
- **Purpose**: Validation procedures used by both audit and debug workflows
- **When to use**: To validate semantic models before applying changes

**Optimization Patterns**:

- **Load**: [optimization/SKILL.md](optimization/SKILL.md)
- **Purpose**: Library of optimization patterns for semantic view improvements
- **When to use**: When you need guidance on specific optimization techniques

**Upload**:

- **Load**: [upload/SKILL.md](upload/SKILL.md)
- **Purpose**: Upload optimized semantic view YAML to Snowflake
- **When to use**: Only when user explicitly requests deployment to Snowflake

**SVA verified-query SQL (reference)**:

- **Load**: [reference/sva_validate_verified_queries.md](reference/sva_validate_verified_queries.md) — compile-check VQR SQL (`validate_verified_queries`), bulk or inline
- **Load**: [reference/sva_expand_truncate_verified_query.md](reference/sva_expand_truncate_verified_query.md) — semantic ↔ physical SQL (`expand_verified_query` / `truncate_verified_query`)
- **When to use**: User asks to validate VQRs compile, expand/truncate verified query SQL, or you need SQL templates for `SYSTEM$CORTEX_ANALYST_SVA_TOOL` (use with a local YAML path from optimization setup or user-provided file)

**Time Tracking** (Optional):

- **Load**: [time_tracking/SKILL.md](time_tracking/SKILL.md)
- **Purpose**: Track execution time for tool calls and workflow steps
- **When to use**: Only if user explicitly requests time tracking

**⚠️ After setup, refer to Core Capabilities below for detailed information on each workflow.**

## Core Capabilities

**Routing note:** `setup/SKILL.md` Part 2 only chooses **Creation** vs **Optimization** (existing view → Part 3 download). **VQR Suggestions**, **Filters & Metrics Suggestions**, and **Tableau Import** below are loaded **directly from this list** when the user’s intent matches — they **do not** require Part 3. For SVA SQL against a downloaded model, complete optimization setup first or use a user-supplied YAML path.

### Creation Mode

Create new semantic views from scratch with proper structure, relationships, and validation using table metadata and VQRs (SQL Queries).

**When to use**: User wants to CREATE a new semantic view (not optimize an existing one)

**Action**: Load [creation/SKILL.md](creation/SKILL.md)

### VQR Suggestions

Generate verified query suggestions by mining Cortex Analyst usage and Snowflake query history. Runs both modes in parallel and merges results.

**When to use**: User wants to suggest, generate, seed, or populate VQRs for a semantic view — including right after creation

**Action**: Load [vqr_suggestions/SKILL.md](vqr_suggestions/SKILL.md)

### Filters & Metrics Suggestions

Suggest metrics, named filters, and computed facts for a semantic view by mining Snowflake query history via `SYSTEM$CORTEX_ANALYST_SVA_TOOL`.

**When to use**: User wants to suggest, recommend, or auto-generate metrics, filters, or facts for a semantic view

**Action**: Load [filters_and_metrics_suggestions/SKILL.md](filters_and_metrics_suggestions/SKILL.md)

### Tableau Import Mode

Import Tableau workbooks (.twb, .twbx) and datasources (.tds, .tdsx) into Snowflake Semantic Views. Handles published datasources, custom SQL, and provides flexible deployment options.

**When to use**: User wants to IMPORT or CONVERT a Tableau file to a semantic view

**Trigger keywords**: import Tableau, convert Tableau, Tableau to semantic view, migrate workbook, .twb, .twbx

**Action**: Load [import_tableau/SKILL.md](import_tableau/SKILL.md)

### Optimization, Audit, and Debug

For working with EXISTING semantic views.

**When to use**: User wants to optimize, audit, or debug an existing semantic view

**Action**: Continue in setup/SKILL.md (Part 3)

#### 1. Audit and Optimize Loop

Comprehensive audit system for semantic views including:

1. VQR testing (behavioral — CA without VQR hints)
2. Best Practices verification
3. Custom Criteria evaluation
4. SVA VQR compile check (`validate_verified_queries` — see [reference/sva_validate_verified_queries.md](reference/sva_validate_verified_queries.md))

**Load**: [audit/SKILL.md](audit/SKILL.md) when user chooses AUDIT MODE

#### 2. Debug Loop

Targeted problem-solving for specific issues with SQL generation from natural language queries.

**Load**: [debug/SKILL.md](debug/SKILL.md) when user chooses DEBUG MODE

## Supporting Skills

### Validation

**Load**: [validation/SKILL.md](validation/SKILL.md) - Validation procedures used by both audit and debug workflows

### Optimization Patterns

**Load**: [optimization/SKILL.md](optimization/SKILL.md) - Library of optimization patterns for semantic view improvements

### Time Tracking (Optional)

**Load**: [time_tracking/SKILL.md](time_tracking/SKILL.md) - Track execution time for tool calls and workflow steps (only load if user explicitly requests time tracking)

### Upload

**Load**: [upload/SKILL.md](upload/SKILL.md) - Upload optimized semantic view YAML to Snowflake (only load when user wants to deploy/upload)

### SVA verified-query SQL (reference)

**Load**: [reference/sva_validate_verified_queries.md](reference/sva_validate_verified_queries.md), [reference/sva_expand_truncate_verified_query.md](reference/sva_expand_truncate_verified_query.md) — Snowflake Analyst VQR compile validation and semantic/physical SQL conversion

## Workflow Decision Tree

**Complete visual representation of the initialization and routing flow:**

```
Start Session
    ↓
Step 1: Load semantic_view_concepts.md ✋
    ↓
Step 2: Load setup/SKILL.md ✋
    ├─ Part 1: Directory Initialization
    │   ├─ Capture SKILL_BASE_DIR
    │   ├─ Get BASE_WORKING_DIR (ask or infer)
    │   └─ Create WORKING_DIR (semantic_view_{TIMESTAMP})
    │
    ├─ Part 2: Workflow Routing
    │   └─ Determine: NEW, IMPORT, EXISTING, VQR SUGGESTIONS, or FILTER & METRIC SUGGESTIONS?
    │       ↓
    │   ┌───┴───┬─────┬──────────┬──────────┐
    │   ↓       ↓     ↓          ↓          ↓
    │  NEW   IMPORT EXISTING  VQR       FILTERS &
    │   ↓       ↓     ↓      SUGGEST.   METRICS
    │  Load   Load  Continue    ↓          ↓
    │ creation/ import_ Part 3 Load       Load
    │ SKILL.md tableau/       vqr_        filters_and_
    │         SKILL.md        suggestions/ metrics_suggestions/
    │                         SKILL.md    SKILL.md
    │
    └─ Part 3: Optimization Setup (if EXISTING)
        ├─ Create {WORKING_DIR}/optimization/
        ├─ Download semantic model
        └─ Present mode selection
            ↓
        ┌───┴───┐
        ↓       ↓
    AUDIT    DEBUG
     MODE     MODE
```

**See above for supporting skills available throughout any workflow.**

## Key Principles

1. **Progressive Disclosure**: Load skills incrementally as needed
2. **Modularity**: Each skill is self-contained and reusable
3. **User Confirmation**: Stop at mandatory checkpoints for user input
4. **Validation First**: Always validate before applying changes

## Rules

1. **⚠️ Test Locally First**: By default, test with local YAML files using `semantic_model_file` parameter. Only upload to Snowflake when user explicitly requests deployment.
2. **⚠️ MANDATORY CHECKPOINT FOR ALL OPTIMIZATIONS**: Before any actual semantic view optimization:
   - Wait for explicit user approval (e.g., "approved", "looks good", "proceed")
   - NEVER chain separate optimization edits without user approval between them
3. **⚠️ Always use `uv run python` for scripts**. DO NOT use `python script.py` or `python3 script.py`.
