building-dbt-semantic-layer
Use when creating or modifying dbt Semantic Layer components — semantic models, metrics, dimensions, entities, measures, or time spines. Covers MetricFlow configuration, metric types (simple, derived, cumulative, ratio, conversion), and validation for both latest and legacy YAML specs.
dbt-labs · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add dbt-labs/dbt-agent-skills --skill building-dbt-semantic-layer技能说明
name: building-dbt-semantic-layer description: Use when creating or modifying dbt Semantic Layer components — semantic models, metrics, dimensions, entities, measures, or time spines. Covers MetricFlow configuration, metric types (simple, derived, cumulative, ratio, conversion), and validation for both latest and legacy YAML specs. user-invocable: false metadata: author: dbt-labs
Building the dbt Semantic Layer
This skill guides the creation and modification of dbt Semantic Layer components: semantic models, entities, dimensions, and metrics.
- Semantic models - Metadata configurations that define how dbt models map to business concepts
- Entities - Keys that identify the grain of your data and enable joins between semantic models
- Dimensions - Attributes used to filter or group metrics (categorical or time-based)
- Metrics - Business calculations defined on top of semantic models (e.g., revenue, order count)
Additional Resources
- Time Spine Setup - Required for time-based metrics and aggregations
- Best Practices - Design patterns and recommendations for semantic models and metrics
- Latest Spec Authoring Guide - Full YAML reference for dbt Core 1.12+ and Fusion
- Legacy Spec Authoring Guide - Full YAML reference for dbt Core 1.6-1.11
Determine Which Spec to Use
There are two versions of the Semantic Layer YAML spec:
- Latest spec - Semantic models are configured as metadata on dbt models. Simpler authoring. Supported by dbt Core 1.12+ and Fusion.
- Legacy spec - Semantic models are defined as separate top-level resources. Uses measures as building blocks for metrics. Supported by dbt Core 1.6 through 1.11. Also supported by Core 1.12+ for backwards compatibility.
Step 1: Check for Existing Semantic Layer Config
Look for existing semantic layer configuration in the project:
- Top-level
semantic_models:key in YAML files → legacy spec semantic_model:block nested under a model → latest spec
Step 2: Route Based on What You Found
If semantic layer already exists:
- Determine which spec is currently in use (legacy or latest)
- Check dbt version for compatibility:
- Legacy spec + Core 1.6-1.11 → Compatible. Use legacy spec guide.
- Legacy spec + Core 1.12+ or Fusion → Compatible, but offer to upgrade first using
uvx dbt-autofix deprecations --semantic-layeror the migration guide. They don't have to upgrade; continuing with legacy is fine. - Latest spec + Core 1.12+ or Fusion → Compatible. Use latest spec guide.
- Latest spec + Core <1.12 → Incompatible. Help them upgrade to dbt Core 1.12+.
If no semantic layer exists:
- Core 1.12+ or Fusion → Use latest spec guide (no need to ask).
- Core 1.6-1.11 → Ask if they want to upgrade to Core 1.12+ for the easier authoring experience. If yes, help upgrade. If no, use legacy spec guide.
Step 3: Follow the Spec-Specific Guide
Once you know which spec to use, follow the corresponding guide's implementation workflow (Steps 1-4) for all YAML authoring. The guides are self-contained with full examples.
Minimal latest spec example (dbt Core 1.12+ / Fusion) — use this as your starting point to avoid guessing the structure:
# models/fct_orders.yml
models:
- name: fct_orders
semantic_model:
enabled: true
agg_time_dimension: order_date
columns:
- name: order_id
entity:
type: primary
name: order
- name: customer_id
entity:
type: foreign
name: customer
- name: order_date
granularity: day
dimension:
type: time
- name: status
dimension:
type: categorical
metrics:
- name: total_revenue
type: simple
label: Total Revenue
agg: sum
expr: amount
Minimal legacy spec example (dbt Core 1.6–1.11) — use this if the project is on an older version:
# models/sem_orders.yml
semantic_models:
- name: orders
model: ref('fct_orders')
defaults:
agg_time_dimension: order_date
entities:
- name: order
type: primary
expr: order_id
dimensions:
- name: order_date
type: time
type_params:
time_granularity: day
measures:
- name: revenue
agg: sum
expr: amount
metrics:
- name: total_revenue
type: simple
label: Total Revenue
type_params:
measure: revenue
Entry Points
Users may ask questions related to building metrics with the semantic layer in a few different ways. Here are the common entry points to look out for:
Business Question First
When the user describes a metric or analysis need (e.g., "I need to track customer lifetime value by segment"):
- Search project models or existing semantic models by name, description, and column names for relevant candidates
- Present top matches with brief context (model name, description, key columns)
- User confirms which model(s) / semantic models to build on / extend / update
- Work backwards from users need to define entities, dimensions, and metrics
Model First
When the user specifies a model to expose (e.g., "Add semantic layer to customers model"):
- Read the model SQL and existing YAML config
- Identify the grain (primary key / entity)
- Suggest dimensions based on column types and names
- Ask what metrics the user wants to define
Both paths converge on the same implementation workflow.
Open Ended
User asks to build the semantic layer for a project or models that are not specified. ("Build the semantic layer for my project")
- Identify high importanc