DocsChonk TypesEntity Chonks

DocsChonk TypesEntity Chonks

Chonk Types6 min readIntermediateUpdated Jan 2026

Entity Chonks

Entity chonks create dimension tables that represent business entities like customers, products, or locations. They bring together attributes from multiple sources into a single, analysis-ready table.

What They Generate

Entity chonks produce dimension models with aggregated metrics, business classifications, and optional slowly-changing dimension (SCD) support.

dim_[entity].sql

The dimension model SQL with joins and aggregations

Surrogate Keys

Optional hashed keys for multi-column joins

Pre-aggregations

Lifetime metrics baked into the dimension

Entity Types

Type 1 (Overwrite)

Simple dimensions that don't track history. Current state only. Great for attributes that don't change or where history isn't important.

Example: Product categories, static reference data

Type 2 (Historical)

Slowly changing dimensions that track changes over time with valid_from/valid_to dates. Essential for accurate historical analysis.

Example: Customer segments, employee departments

Choose Type 2 when you need to answer questions like "What was this customer's segment when they made this purchase?" or "Which department was the employee in last quarter?"

Example Output

Here's a customer dimension with lifetime metrics and business segmentation.

models/marts/core/dim_customers.sql

with customers as (
    select * from {{ ref('stg_ecommerce__customers') }}
),

orders as (
    select * from {{ ref('stg_ecommerce__orders') }}
),

customer_orders as (
    select
        customer_id,
        min(order_date) as first_order_date,
        max(order_date) as most_recent_order_date,
        count(*) as number_of_orders,
        sum(order_total) as lifetime_value
    from orders
    group by 1
),

final as (
    select
        customers.customer_id,
        customers.first_name,
        customers.last_name,
        customers.email,
        customers.created_at as customer_created_at,
        
        -- order metrics
        coalesce(customer_orders.first_order_date, null) as first_order_date,
        coalesce(customer_orders.most_recent_order_date, null) as most_recent_order_date,
        coalesce(customer_orders.number_of_orders, 0) as number_of_orders,
        coalesce(customer_orders.lifetime_value, 0) as lifetime_value,
        
        -- derived segmentation
        case
            when customer_orders.number_of_orders >= 10 then 'vip'
            when customer_orders.number_of_orders >= 3 then 'regular'
            when customer_orders.number_of_orders >= 1 then 'new'
            else 'prospect'
        end as customer_segment

    from customers
    left join customer_orders using (customer_id)
)

select * from final

Best Practices

Include useful aggregates — pre-calculate lifetime metrics to speed up queries
Add business segments — classify entities for easier filtering and analysis
Use surrogate keys — hash multi-column natural keys for simpler joins
Test relationships — ensure referential integrity with fact tables
Keep it wide — dimensions should have many columns; facts should be narrow

Performance Tip

Pre-aggregating metrics in dimensions (like lifetime_value) trades storage for query performance. Users get faster dashboards, and you avoid repeated aggregation logic.

Configuration Options

Property	Type	Default	Description
scd_type	1 \| 2	1	Slowly Changing Dimension type
include_surrogate_key	boolean	false	Generate hashed surrogate key
aggregate_metrics	boolean	true	Include pre-calculated lifetime metrics
business_segments	boolean	true	Generate business classification columns
valid_from_column	string	valid_from	SCD Type 2 start date column
valid_to_column	string	valid_to	SCD Type 2 end date column

Entity Chonks

What They Generate

Entity chonks produce dimension models with aggregated metrics, business classifications, and optional slowly-changing dimension (SCD) support.

dim_[entity].sql

The dimension model SQL with joins and aggregations

Surrogate Keys

Optional hashed keys for multi-column joins

Pre-aggregations

Lifetime metrics baked into the dimension

Entity Types

Type 1 (Overwrite)

Simple dimensions that don't track history. Current state only. Great for attributes that don't change or where history isn't important.

Example: Product categories, static reference data

Type 2 (Historical)

Slowly changing dimensions that track changes over time with valid_from/valid_to dates. Essential for accurate historical analysis.

Example: Customer segments, employee departments

Choose Type 2 when you need to answer questions like "What was this customer's segment when they made this purchase?" or "Which department was the employee in last quarter?"

Example Output

Here's a customer dimension with lifetime metrics and business segmentation.

models/marts/core/dim_customers.sql

with customers as (
    select * from {{ ref('stg_ecommerce__customers') }}
),

orders as (
    select * from {{ ref('stg_ecommerce__orders') }}
),

customer_orders as (
    select
        customer_id,
        min(order_date) as first_order_date,
        max(order_date) as most_recent_order_date,
        count(*) as number_of_orders,
        sum(order_total) as lifetime_value
    from orders
    group by 1
),

final as (
    select
        customers.customer_id,
        customers.first_name,
        customers.last_name,
        customers.email,
        customers.created_at as customer_created_at,
        
        -- order metrics
        coalesce(customer_orders.first_order_date, null) as first_order_date,
        coalesce(customer_orders.most_recent_order_date, null) as most_recent_order_date,
        coalesce(customer_orders.number_of_orders, 0) as number_of_orders,
        coalesce(customer_orders.lifetime_value, 0) as lifetime_value,
        
        -- derived segmentation
        case
            when customer_orders.number_of_orders >= 10 then 'vip'
            when customer_orders.number_of_orders >= 3 then 'regular'
            when customer_orders.number_of_orders >= 1 then 'new'
            else 'prospect'
        end as customer_segment

    from customers
    left join customer_orders using (customer_id)
)

select * from final

Best Practices

Include useful aggregates — pre-calculate lifetime metrics to speed up queries
Add business segments — classify entities for easier filtering and analysis
Use surrogate keys — hash multi-column natural keys for simpler joins
Test relationships — ensure referential integrity with fact tables
Keep it wide — dimensions should have many columns; facts should be narrow

Performance Tip

Pre-aggregating metrics in dimensions (like lifetime_value) trades storage for query performance. Users get faster dashboards, and you avoid repeated aggregation logic.

Configuration Options

Property	Type	Default	Description
scd_type	1 \| 2	1	Slowly Changing Dimension type
include_surrogate_key	boolean	false	Generate hashed surrogate key
aggregate_metrics	boolean	true	Include pre-calculated lifetime metrics
business_segments	boolean	true	Generate business classification columns
valid_from_column	string	valid_from	SCD Type 2 start date column
valid_to_column	string	valid_to	SCD Type 2 end date column

Entity Chonks

What They Generate

dim_[entity].sql

Surrogate Keys

Pre-aggregations

Entity Types

Type 1 (Overwrite)

Type 2 (Historical)

Example Output

Best Practices

Configuration Options

Related Documentation

Fact Chonks

Metric Chonks

Entity Chonks

What They Generate

dim_[entity].sql

Surrogate Keys

Pre-aggregations

Entity Types

Type 1 (Overwrite)

Type 2 (Historical)

Example Output

Best Practices

Configuration Options

Related Documentation

Fact Chonks

Metric Chonks