Semantic Layer

The Semantic Layer turns your warehouse tables into consistent, reusable metrics and dimensions that work across BI tools, notebooks, and downstream applications.

---

Why a semantic layer matters

Without a semantic layer, the same metric (e.g., "revenue") gets defined differently across dashboards, notebooks, and reports. The Semantic Layer provides a single source of truth:

• Metrics — aggregations like revenue, churn rate, customer count
• Dimensions — categorical and time-based attributes for slicing data
• Entities — business objects (customer, account, product) that tie metrics together

All definitions live as YAML files in your GitHub repo, versioned and code-reviewed like any other artifact.

---

Browsing semantic definitions

Navigate to Semantic Layer in the sidebar. You'll see a paginated table of YAML files:

Column	Description
Filename	e.g., sales_analytics.yaml, revenue_metrics.yaml
Owner	Team member responsible for this definition
Status	Active, Draft, or Pending Review
Created	When the file was first created
Updated	Last modification timestamp

Click View on any file to open it in the semantic editor, where you can inspect dimensions, measures, and entities.

---

Creating a semantic layer configuration

1. Start from a model or from scratch

   You have two entry points:

   1. From the AI modeling workspace — after finalizing a gold model, Zingle automatically proposes a semantic YAML definition based on column names, types, and business rules.
   2. From the Semantic Layer page — click Create Semantic Layer to start a new file from scratch.

2. Define your semantic objects

   The editor supports three types of objects:

   Entities

   entities:
     - name: customer
       type: primary
       expr: customer_id

   Dimensions

   dimensions:
     - name: region
       type: categorical
       expr: customer_region
     - name: order_date
       type: time
       type_params:
         time_granularity: day

   Measures

   measures:
     - name: total_revenue
       type: sum
       expr: order_total
     - name: active_customers
       type: count_distinct
       expr: customer_id

3. Use the chat assistant

   The semantic layer creation flow includes a chat interface. You can describe what metrics you need, and the assistant generates the YAML structure. Refine it in the visual editor.

4. Ship via pull request

   When your definitions are ready, click Create PR. Zingle:

   • Creates or updates the YAML file in your GitHub repo
   • Links the semantic definition to the appropriate model files
   • Opens a PR for your team to review

---

How semantic files relate to models

Every semantic configuration is anchored to one or more warehouse tables — typically gold layer models. This means:

• Semantic files live alongside dbt models in your repo
• They reuse the same GitHub connection
• Changes are version-controlled and code-reviewed
• Lineage is preserved from source tables through to semantic definitions

---

Best practices

• Anchor metrics to gold models. Gold tables represent cleaned, business-ready data — the right foundation for consistent metrics.
• Use meaningful names. total_revenue is better than rev_sum. Your BI consumers will thank you.
• Set time granularity explicitly. Always specify time_granularity on time dimensions to avoid ambiguity.
• Review before merging. Semantic changes affect every downstream consumer. Treat PRs for semantic files with extra care.