Semantic Models

Overview

Semantic models bridge the gap between technical metadata and business context. While traditional data catalogs show table names, column types, and lineage, semantic models define the entities, metrics, relationships, and business logic that represent how your organization actually uses data.

By creating semantic models in Select Star, you enable:

• AI-powered insights: Ask AI can reference business concepts like "customer," "ARR," or "churn rate" with proper context, generating accurate SQL queries

• Consistent metrics: Define metrics once and use them across your organization

• Business context: Add descriptions, synonyms, and sample business questions that help both humans and AI understand your data

• Integration: Export to tools like Snowflake Cortex Analyst or use with Select Star MCP for AI coding assistants

Semantic models work with all data warehouses and BI tools supported by Select Star.

Quick Start

Want to create your first semantic model in 5 minutes? Here's the fastest path:

1. Choose your source:

   • Have dashboards? Go to your BI tool (Power BI, Tableau, etc.) and select 1-3 dashboards that represent a business domain

   • No dashboards? Go to your data warehouse and select the core tables for a business area (e.g., orders, customers, payments)

2. Generate the model:

   • Select your assets → Click AI Assist → Generate Semantic Model

   • Give it a name → Click Generate

   • Wait for email notification (usually 2-5 minutes)

3. Enable in Ask AI:

   • Open your semantic model → Go to Settings tab

   • Toggle Enable Ask AI to ON

   • Add custom instructions if needed (optional)

4. Start asking questions:

   • Go to Ask AI → Select your semantic model

   • Ask business questions like "What are our top customers by revenue?"

That's it! For detailed instructions and advanced features, continue reading below.

Getting Started

Prerequisites

Before creating semantic models:

1. Select Star AI features must be enabled for your organization

2. Permissions:

   • Admins and Data Managers: Can create, edit, and delete semantic models

   • Viewers: Can view semantic models but cannot make changes

3. Source data: Have at least one dashboard or table in Select Star to use as a source

Creating a Semantic Model

You can create semantic models from dashboards or tables. Both follow the same basic process but differ in their starting point:

Creation Steps

The creation process is the same regardless of source:

For Dashboards:

1. Navigate to your BI tool (Power BI, Tableau, etc.)

2. Select one or more dashboards

3. Click AI Assist → Generate Semantic Model

For Tables:

1. Navigate to your data warehouse (Snowflake, BigQuery, etc.)

2. Select one or more tables

3. Click AI Assist → Generate Semantic Model

Then for both:

1. Enter a Display Name for your semantic model

2. Click Generate

What Gets Generated

Select Star automatically creates:

• Entities: Logical tables based on your source data

• Relationships: Inferred from primary/foreign keys in your ERD

• Metrics: From dashboard calculations, existing metrics, and downstream dashboards

• Example Queries: Generated from table structure and common patterns

All components are AI-generated and can be edited after creation.

Generation Time

• Standard models: Typically complete within a few minutes

• Large or complex models: May take up to an hour if:

  • The semantic model includes many tables

  • Descriptions need to be generated for columns

  • Metrics need to be calculated

  • Example queries need to be created

You'll receive an email notification when generation is complete. You can monitor progress from the Semantic Models list page.

Working with Semantic Models

List View

Find all semantic models in your organization with their status, descriptions, and creation details. Search and filter to locate specific models quickly.

Overview Tab

View the semantic model's purpose, business questions it answers, source assets, and ownership details. Track changes in the history panel.

Entities Tab

Browse all logical tables (entities) in your model with their fields, data types, and business descriptions.

Adding Entities

To add new entities to your semantic model:

1. Navigate to the Relationships tab

2. Click the Add Entity button

3. Select a data source (e.g., Snowflake)

4. Choose a table from the dropdown

5. Select which columns to include:

   • Check Select All to include all columns

   • Or select individual columns

6. Click Add Entity

The new entity will be added with:

• All selected fields

• Inferred data types

• Descriptions from the source table (or AI-generated if none exist)

Editing Entities

You can modify entities through the Relationships tab:

• Click the menu (⋮) on an entity card

• Select Edit Fields to change which columns are included

Removing Entities

To remove an entity:

1. Navigate to the Relationships tab

2. Click the menu (⋮) on the entity card

3. Select Delete Entity

4. Confirm the deletion

Relationships Tab

The Relationships tab shows how entities join using primary key and foreign key relationships.

Visualize connections between tables and manage how entities relate to each other. Add new entities or edit existing relationships as needed.

Metrics Tab

View business metrics with their definitions, synonyms, and SQL expressions. By default, semantic models include the top 10 most relevant metrics to ensure optimal AI performance.

Example Queries Tab

See popular business questions with their SQL answers. These queries help Ask AI understand typical questions and demonstrate what's possible with your data.

Settings Tab

Control how your semantic model integrates with Ask AI and external tools like Snowflake Cortex Analyst. Toggle Ask AI availability, add custom instructions for business rules, and configure Snowflake export options (YAML to stage or SQL view to database).

YAML Specification

Viewing and Downloading YAML

Every semantic model has a YAML representation following the Snowflake Cortex Analyst specification.

To view the YAML:

1. Click the YAML button in the top-right corner of any semantic model page

2. The YAML modal displays the complete model definition

YAML Contents:

• Model name and description

• Business questions

• Source assets and tables

• Entity definitions (dimensions, time dimensions, facts)

• Relationships between entities

• Metrics with expressions

• Example queries with SQL

Download Options:

• Click the download icon to save the YAML file

• Filename format: {model_name}_{date}.yaml

• The downloaded file can be:

  • Used with Snowflake Cortex Analyst

  • Imported into other tools

  • Version controlled in Git

  • Shared with your team

YAML Structure

The YAML follows this structure:

name: Model Name
description: Model description and business context

entities:
  - name: EntityName
    description: Entity description
    base_table:
      database: DATABASE
      schema: SCHEMA
      table: TABLE_NAME
    dimensions:
      - name: column_name
        synonyms: [alternative_name, ...]
        description: Column description
        expr: column_name
        data_type: TYPE
        sample_values: [...]
    time_dimensions:
      - name: date_column
        ...
    facts:
      - name: numeric_column
        ...

relationships:
  - name: relationship_name
    left_table: EntityA
    right_table: EntityB
    relationship_columns:
      - left_column: column_a
        right_column: column_b

metrics:
  - name: metric_name
    synonyms: [...]
    expr: SUM(EntityName.column_name)

example_queries:
  - name: query_name
    question: Business question in natural language?
    sql: SELECT ... FROM ...

Integrations

Ask AI

Semantic models enhance Ask AI's ability to understand your data and generate accurate queries.

How Semantic Models Help Ask AI

When a semantic model is enabled in Ask AI:

1. Business Context: Ask AI understands business terms and metrics, not just table names

2. Accurate Joins: Relationships ensure correct table joins

3. Consistent Metrics: Metrics are calculated the same way every time

4. Sample Questions: Example queries guide what's possible

Using Semantic Models in Ask AI

When semantic models are enabled for Ask AI, they automatically enrich the AI's context. The AI agent intelligently selects the most appropriate semantic model(s) to answer your questions.

You can also manually select a semantic model from the dropdown if you want to focus on a specific business domain.

Ask AI will:

• Automatically use relevant semantic models based on your question

• Apply business entities, relationships, and metrics

• Generate accurate SQL using your business terminology

• Suggest follow-up questions from example queries

Benefits:

• Smarter AI: Understands your business terms, not just table names

• Accurate queries: Correct joins and metric calculations

• Faster answers: Pre-defined context speeds up query generation

Select Star MCP

Semantic models are also available through the Select Star MCP Server, enabling AI coding assistants like Cursor and Claude Desktop to:

• Discover and understand your semantic models

• Reference business entities and metrics in code

• Generate queries using established business logic

• Access example queries for common patterns

Example Use Case:

You're writing Python code and ask your AI assistant: "Using the Sales Analytics semantic model, write a query to calculate total revenue by customer segment"

Your AI assistant will:

• Discover the "Sales Analytics" semantic model via MCP

• Use the defined "Revenue" metric

• Apply correct joins via relationships

• Generate: SELECT customer_segment, SUM(revenue) FROM sales_model GROUP BY customer_segment

You can also let the AI discover semantic models automatically by asking: "What semantic models are available?" or "Write a query for customer revenue analysis" and the AI will find and use the appropriate model.

This gives your AI assistant deep understanding of your business data context, improving code generation quality.

Best Practices

Create semantic models for:

• Core business domains (Sales, Marketing, Finance)

• Data used by multiple teams

• Frequently asked business questions

Choose dashboards when:

• Metrics are already defined in your BI tool

• You want only relevant tables/columns

Choose tables when:

• Building a new semantic layer from scratch

• You need full control over entities

Maintain quality by:

• Adding business context to AI-generated descriptions

• Validating relationships match your business logic

• Using custom instructions to document business rules, date defaults, and key filters

Troubleshooting

Model Generation Taking Too Long

If your semantic model is stuck "In Progress":

• Check email: You'll receive a notification when complete (may take up to an hour for large models)

• Review size: Very large dashboards with many tables may take longer

• Wait for metrics: Metric generation can be time-intensive

• Contact support: If generation exceeds 2 hours, contact [email protected]

Relationships Not Showing Correctly

If entities aren't connected in the ERD:

1. Verify primary keys are defined on your tables in Select Star's ERD

2. Check that foreign key relationships exist in your ERD

3. Manually add relationships if needed using the Relationships tab

Snowflake Publish Failing

If publishing to Snowflake fails:

For Stage publish:

• Verify the stage exists: SHOW STAGES LIKE 'stage_name' IN SCHEMA database.schema;

• Check Select Star has WRITE permission on the stage

• Ensure stage name is fully qualified: database.schema.stage

For Semantic View publish:

• Verify database and schema exist

• Check Select Star has CREATE VIEW permission

• Ensure the credential used by Select Star has sufficient privileges

• Review Snowflake error logs for specific permission issues

Metrics Missing or Incorrect

If expected metrics aren't appearing:

• Check metric limit: Only top 10 most relevant metrics are included by default

• Review source assets: Metrics come from your dashboards, tables, and existing metric definitions

• Verify entity columns: Ensure the columns used in metric expressions exist in your entities

• Check complexity: Very complex calculations may not be included

Ask AI Not Using Semantic Model

If Ask AI isn't using your semantic model:

1. Verify Enable Ask AI is toggled on in Settings

2. Ensure you've selected the semantic model in the Ask AI interface

3. Check that your question relates to entities in the model

4. Try rephrasing using terms from entity and metric names

Additional Resources

• Ask AI Documentation - Learn more about using semantic models with Ask AI

• Select Star MCP - Use semantic models with AI coding assistants

• Metrics Documentation - Understand metrics in Select Star

Have questions or feedback? Contact us at [email protected]