DocsKnowledge SyncSemantic Layer

DocsKnowledge SyncSemantic Layer

Knowledge Sync8 min readAdvancedUpdated Jan 2026

Semantic Layer

The semantic layer is your single source of truth for business metrics and dimensions, ensuring consistent calculations across all your analytics. No more 'which revenue number is correct?' conversations.

What is a Semantic Layer?

A semantic layer sits between your raw data models and your BI tools, providing a consistent, governed interface for analytics.

Consistent metrics

Define revenue once, use everywhere

Business terminology

Map technical columns to business names

Governed access

Control who can query what

Self-service analytics

Let analysts explore without SQL

DataChonk + dbt Semantic Layer

DataChonk generates semantic layer definitions compatible with dbt's MetricFlow, the industry-standard semantic layer for dbt projects.

Semantic Model Definition

models/semantic/orders_semantic.yml

semantic_models:
  - name: orders
    model: ref('fct_orders')
    
    entities:
      - name: order_id
        type: primary
      - name: customer_id
        type: foreign
        
    dimensions:
      - name: order_date
        type: time
        type_params:
          time_granularity: day
      - name: status
        type: categorical
        
    measures:
      - name: order_total
        agg: sum
        expr: amount
      - name: order_count
        agg: count
        expr: order_id

Metric Definitions

models/metrics/revenue_metrics.yml

metrics:
  - name: revenue
    label: Total Revenue
    description: Sum of all order amounts
    type: simple
    type_params:
      measure: order_total
      
  - name: average_order_value
    label: AOV
    description: Average revenue per order
    type: derived
    type_params:
      expr: revenue / order_count
      metrics:
        - revenue
        - order_count

Creating Semantic Models

From the UI

Navigate to a Metric Chonk

Open the chonk you want to add semantic definitions to

Click Configure Semantic Layer

Access the semantic layer configuration panel

Define entities, dimensions, and measures

Map your columns to semantic concepts

Preview the generated YAML

Review before generating

Generate and push

Push to your dbt project

From the CLI

Terminal

# Generate semantic layer from existing models
datachonk semantic generate --model fct_orders

# Validate semantic definitions
datachonk semantic validate

# Preview metric queries
datachonk semantic query --metric revenue --group-by order_date

Best Practices

Entity Design

Use clear, consistent naming (customer_id, not cust_id)
Define primary entities for fact tables
Create foreign entities to enable joins

Dimension Design

Use time dimensions for date/datetime columns
Use categorical for string/enum values
Document with clear descriptions

Measure Design

Use descriptive names (total_revenue not rev)
Include units in descriptions where applicable
Define base measures first, derived metrics second

Integration with BI Tools

Once your semantic layer is defined, it integrates with popular BI platforms.

Property	Type	Default	Description
Tableau	-	-	dbt Semantic Layer connector
Looker	-	-	LookML generation from metrics
Power BI	-	-	DirectQuery with semantic layer API
Hex	-	-	Native dbt Semantic Layer support
Mode	-	-	dbt Cloud integration

Querying the Semantic Layer

Use MetricFlow to query your semantic layer directly.

MetricFlow CLI

# Query metrics with dimensions
mf query --metrics revenue,order_count \
  --group-by metric_time__month,customer__region \
  --where "metric_time__month >= '2024-01-01'"

# Results
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ metric_time__month  ┃ customer__region┃ revenue   ┃ order_count ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ 2024-01             │ North America   │ 1,245,000 │ 4,521       │
│ 2024-01             │ Europe          │ 892,000   │ 3,102       │
│ 2024-02             │ North America   │ 1,389,000 │ 4,892       │
└─────────────────────┴─────────────────┴───────────┴─────────────┘

Version Compatibility

Property	Type	Default	Description
dbt 1.9+	-	-	Full MetricFlow integration
dbt 1.8.x	-	-	Semantic models (beta)
dbt 1.7.x	-	-	Legacy metrics (deprecated)

Upgrade Recommended

If you're on dbt 1.7 or earlier, DataChonk will generate legacy metric definitions. We recommend upgrading to 1.8+ for the full semantic layer experience.

Semantic Layer

What is a Semantic Layer?

A semantic layer sits between your raw data models and your BI tools, providing a consistent, governed interface for analytics.

Consistent metrics

Define revenue once, use everywhere

Business terminology

Map technical columns to business names

Governed access

Control who can query what

Self-service analytics

Let analysts explore without SQL

DataChonk + dbt Semantic Layer

DataChonk generates semantic layer definitions compatible with dbt's MetricFlow, the industry-standard semantic layer for dbt projects.

Semantic Model Definition

models/semantic/orders_semantic.yml

semantic_models:
  - name: orders
    model: ref('fct_orders')
    
    entities:
      - name: order_id
        type: primary
      - name: customer_id
        type: foreign
        
    dimensions:
      - name: order_date
        type: time
        type_params:
          time_granularity: day
      - name: status
        type: categorical
        
    measures:
      - name: order_total
        agg: sum
        expr: amount
      - name: order_count
        agg: count
        expr: order_id

Metric Definitions

models/metrics/revenue_metrics.yml

metrics:
  - name: revenue
    label: Total Revenue
    description: Sum of all order amounts
    type: simple
    type_params:
      measure: order_total
      
  - name: average_order_value
    label: AOV
    description: Average revenue per order
    type: derived
    type_params:
      expr: revenue / order_count
      metrics:
        - revenue
        - order_count

Creating Semantic Models

From the UI

Navigate to a Metric Chonk

Open the chonk you want to add semantic definitions to

Click Configure Semantic Layer

Access the semantic layer configuration panel

Define entities, dimensions, and measures

Map your columns to semantic concepts

Preview the generated YAML

Review before generating

Generate and push

Push to your dbt project

From the CLI

Terminal

# Generate semantic layer from existing models
datachonk semantic generate --model fct_orders

# Validate semantic definitions
datachonk semantic validate

# Preview metric queries
datachonk semantic query --metric revenue --group-by order_date

Best Practices

Entity Design

Use clear, consistent naming (customer_id, not cust_id)
Define primary entities for fact tables
Create foreign entities to enable joins

Dimension Design

Use time dimensions for date/datetime columns
Use categorical for string/enum values
Document with clear descriptions

Measure Design

Use descriptive names (total_revenue not rev)
Include units in descriptions where applicable
Define base measures first, derived metrics second

Integration with BI Tools

Once your semantic layer is defined, it integrates with popular BI platforms.

Property	Type	Default	Description
Tableau	-	-	dbt Semantic Layer connector
Looker	-	-	LookML generation from metrics
Power BI	-	-	DirectQuery with semantic layer API
Hex	-	-	Native dbt Semantic Layer support
Mode	-	-	dbt Cloud integration

Querying the Semantic Layer

Use MetricFlow to query your semantic layer directly.

MetricFlow CLI

# Query metrics with dimensions
mf query --metrics revenue,order_count \
  --group-by metric_time__month,customer__region \
  --where "metric_time__month >= '2024-01-01'"

# Results
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ metric_time__month  ┃ customer__region┃ revenue   ┃ order_count ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ 2024-01             │ North America   │ 1,245,000 │ 4,521       │
│ 2024-01             │ Europe          │ 892,000   │ 3,102       │
│ 2024-02             │ North America   │ 1,389,000 │ 4,892       │
└─────────────────────┴─────────────────┴───────────┴─────────────┘

Version Compatibility

Property	Type	Default	Description
dbt 1.9+	-	-	Full MetricFlow integration
dbt 1.8.x	-	-	Semantic models (beta)
dbt 1.7.x	-	-	Legacy metrics (deprecated)

Upgrade Recommended

If you're on dbt 1.7 or earlier, DataChonk will generate legacy metric definitions. We recommend upgrading to 1.8+ for the full semantic layer experience.

What is a Semantic Layer?

Consistent metrics

Business terminology

Governed access

Self-service analytics

DataChonk + dbt Semantic Layer

Semantic Model Definition

Metric Definitions

Creating Semantic Models

From the UI

Navigate to a Metric Chonk

Click Configure Semantic Layer

Define entities, dimensions, and measures

Preview the generated YAML

Generate and push

From the CLI

Best Practices

Entity Design

Dimension Design

Measure Design

Integration with BI Tools

Querying the Semantic Layer

Version Compatibility

Related Documentation

Metric Chonks

Best Practices

What is a Semantic Layer?

Consistent metrics

Business terminology

Governed access

Self-service analytics

DataChonk + dbt Semantic Layer

Semantic Model Definition

Metric Definitions

Creating Semantic Models

From the UI

Navigate to a Metric Chonk

Click Configure Semantic Layer

Define entities, dimensions, and measures

Preview the generated YAML

Generate and push

From the CLI

Best Practices

Entity Design

Dimension Design

Measure Design

Integration with BI Tools

Querying the Semantic Layer

Version Compatibility

Related Documentation

Metric Chonks

Best Practices