building-dbt-semantic-layer

Name: building-dbt-semantic-layer
Author: dbt-labs

637stars55forks

How to install building-dbt-semantic-layer?

dbt-labs/dbt-agent-skills/building-dbt-semantic-layer

$npx -y skills add dbt-labs/dbt-agent-skills --skill building-dbt-semantic-layer

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Building the dbt Semantic Layer
2
3	This skill guides the creation and modification of dbt Semantic Layer components: semantic models, entities, dimensions, and metrics.
4
5	- Semantic models - Metadata configurations that define how dbt models map to business concepts
6	- Entities - Keys that identify the grain of your data and enable joins between semantic models
7	- Dimensions - Attributes used to filter or group metrics (categorical or time-based)
8	- Metrics - Business calculations defined on top of semantic models (e.g., revenue, order count)
9
10	## Additional Resources
11
12	- [Time Spine Setup](references/time-spine.md) - Required for time-based metrics and aggregations
13	- [Best Practices](references/best-practices.md) - Design patterns and recommendations for semantic models and metrics
14	- [Latest Spec Authoring Guide](references/latest-spec.md) - Full YAML reference for dbt Core 1.12+ and Fusion
15	- [Legacy Spec Authoring Guide](references/legacy-spec.md) - Full YAML reference for dbt Core 1.6-1.11
16
17	## Determine Which Spec to Use
18
19	There are two versions of the Semantic Layer YAML spec:
20
21	- Latest spec - Semantic models are configured as metadata on dbt models. Simpler authoring. Supported by dbt Core 1.12+ and Fusion.
22	- 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.
23
24	### Step 1: Check for Existing Semantic Layer Config
25
26	Look for existing semantic layer configuration in the project:
27	- Top-level `semantic_models:` key in YAML files → legacy spec
28	- `semantic_model:` block nested under a model → latest spec
29
30	### Step 2: Route Based on What You Found
31
32	If semantic layer already exists:
33
34	1. Determine which spec is currently in use (legacy or latest)
35	2. Check dbt version for compatibility:
36	- Legacy spec + Core 1.6-1.11 → Compatible. Use [legacy spec guide](references/legacy-spec.md).
37	- Legacy spec + Core 1.12+ or Fusion → Compatible, but offer to upgrade first using `uvx dbt-autofix deprecations --semantic-layer` or the [migration guide](https://docs.getdbt.com/docs/build/latest-metrics-spec). They don't have to upgrade; continuing with legacy is fine.
38	- Latest spec + Core 1.12+ or Fusion → Compatible. Use [latest spec guide](references/latest-spec.md).
39	- Latest spec + Core <1.12 → Incompatible. Help them upgrade to dbt Core 1.12+.
40
41	If no semantic layer exists:
42
43	1. Core 1.12+ or Fusion → Use [latest spec guide](references/latest-spec.md) (no need to ask).
44	2. 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](references/legacy-spec.md).
45
46	### Step 3: Follow the Spec-Specific Guide
47
48	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.
49
50	Minimal latest spec example (dbt Core 1.12+ / Fusion) — use this as your starting point to avoid guessing the structure:
51
52	```yaml
53	# models/fct_orders.yml
54	models:
55	- name: fct_orders
56	semantic_model:
57	enabled: true
58	agg_time_dimension: order_date
59	columns:
60	- name: order_id
61	entity:
62	type: primary
63	name: order
64	- name: customer_id
65	entity:
66	type: foreign
67	name: customer
68	- name: order_date
69	granularity: day
70	dimension:
71	type: time
72	- name: status
73	dimension:
74	type: categorical
75	metrics:
76	- name: total_revenue
77	type: simple
78	label: Total Revenue
79	agg: sum
80	expr: amount
81	```
82
83	Minimal legacy spec example (dbt Core 1.6–1.11) — use this if the project is on an older version:
84
85	```yaml
86	# models/sem_orders.yml
87	semantic_models:
88	- name: orders
89	model: ref('fct_orders')
90	defaults:
91	agg_time_dimension: order_date
92	entities:
93	- name: order
94	type: primary
95	expr: order_id
96	dimensions:
97	- name: order_date
98	type: time
99	type_params:
100	time_granularity: day
101	measures:
102	- name: revenue
103	agg: sum
104	expr: amount
105
106	metrics:
107	- name: total_revenue
108	type: simple
109	label: Total Revenue
110	type_params:
111	measure: revenue
112	```
113
114	## Entry Points
115
116	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:
117
118	### Business Question First
119
120	Whe

People who liked this also viewed

6 picks

Type

building-dbt-semantic-layer

637stars55forks

View on GitHub

How to install building-dbt-semantic-layer?

dbt-labs/dbt-agent-skills/building-dbt-semantic-layer

$npx -y skills add dbt-labs/dbt-agent-skills --skill building-dbt-semantic-layer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Building the dbt Semantic Layer
2
3	This skill guides the creation and modification of dbt Semantic Layer components: semantic models, entities, dimensions, and metrics.
4
5	- Semantic models - Metadata configurations that define how dbt models map to business concepts
6	- Entities - Keys that identify the grain of your data and enable joins between semantic models
7	- Dimensions - Attributes used to filter or group metrics (categorical or time-based)
8	- Metrics - Business calculations defined on top of semantic models (e.g., revenue, order count)
9
10	## Additional Resources
11
12	- [Time Spine Setup](references/time-spine.md) - Required for time-based metrics and aggregations
13	- [Best Practices](references/best-practices.md) - Design patterns and recommendations for semantic models and metrics
14	- [Latest Spec Authoring Guide](references/latest-spec.md) - Full YAML reference for dbt Core 1.12+ and Fusion
15	- [Legacy Spec Authoring Guide](references/legacy-spec.md) - Full YAML reference for dbt Core 1.6-1.11
16
17	## Determine Which Spec to Use
18
19	There are two versions of the Semantic Layer YAML spec:
20
21	- Latest spec - Semantic models are configured as metadata on dbt models. Simpler authoring. Supported by dbt Core 1.12+ and Fusion.
22	- 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.
23
24	### Step 1: Check for Existing Semantic Layer Config
25
26	Look for existing semantic layer configuration in the project:
27	- Top-level `semantic_models:` key in YAML files → legacy spec
28	- `semantic_model:` block nested under a model → latest spec
29
30	### Step 2: Route Based on What You Found
31
32	If semantic layer already exists:
33
34	1. Determine which spec is currently in use (legacy or latest)
35	2. Check dbt version for compatibility:
36	- Legacy spec + Core 1.6-1.11 → Compatible. Use [legacy spec guide](references/legacy-spec.md).
37	- Legacy spec + Core 1.12+ or Fusion → Compatible, but offer to upgrade first using `uvx dbt-autofix deprecations --semantic-layer` or the [migration guide](https://docs.getdbt.com/docs/build/latest-metrics-spec). They don't have to upgrade; continuing with legacy is fine.
38	- Latest spec + Core 1.12+ or Fusion → Compatible. Use [latest spec guide](references/latest-spec.md).
39	- Latest spec + Core <1.12 → Incompatible. Help them upgrade to dbt Core 1.12+.
40
41	If no semantic layer exists:
42
43	1. Core 1.12+ or Fusion → Use [latest spec guide](references/latest-spec.md) (no need to ask).
44	2. 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](references/legacy-spec.md).
45
46	### Step 3: Follow the Spec-Specific Guide
47
48	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.
49
50	Minimal latest spec example (dbt Core 1.12+ / Fusion) — use this as your starting point to avoid guessing the structure:
51
52	```yaml
53	# models/fct_orders.yml
54	models:
55	- name: fct_orders
56	semantic_model:
57	enabled: true
58	agg_time_dimension: order_date
59	columns:
60	- name: order_id
61	entity:
62	type: primary
63	name: order
64	- name: customer_id
65	entity:
66	type: foreign
67	name: customer
68	- name: order_date
69	granularity: day
70	dimension:
71	type: time
72	- name: status
73	dimension:
74	type: categorical
75	metrics:
76	- name: total_revenue
77	type: simple
78	label: Total Revenue
79	agg: sum
80	expr: amount
81	```
82
83	Minimal legacy spec example (dbt Core 1.6–1.11) — use this if the project is on an older version:
84
85	```yaml
86	# models/sem_orders.yml
87	semantic_models:
88	- name: orders
89	model: ref('fct_orders')
90	defaults:
91	agg_time_dimension: order_date
92	entities:
93	- name: order
94	type: primary
95	expr: order_id
96	dimensions:
97	- name: order_date
98	type: time
99	type_params:
100	time_granularity: day
101	measures:
102	- name: revenue
103	agg: sum
104	expr: amount
105
106	metrics:
107	- name: total_revenue
108	type: simple
109	label: Total Revenue
110	type_params:
111	measure: revenue
112	```
113
114	## Entry Points
115
116	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:
117
118	### Business Question First
119
120	Whe

People who liked this also viewed

6 picks

Type