direct-lake-operations

Direct Lake Operations

This skill covers working with Direct Lake semantic models in Semantic Link Labs.

When to Use This Skill

Use this skill when you need to:

Migrate models to Direct Lake
Check and fix Direct Lake fallback issues
Sync schema between lakehouse and model
Work with Direct Lake guardrails
Warm Direct Lake cache

Overview

Direct Lake is a storage mode for Power BI semantic models that reads data directly from Delta tables in OneLake, providing fast query performance without data import.

Key Files

File	Purpose
`src/sempy_labs/directlake/`	Direct Lake submodule
`_dl_helper.py`	Core Direct Lake utilities
`_guardrails.py`	Guardrail checking
`_directlake_schema_sync.py`	Schema synchronization
`_warm_cache.py`	Cache warming utilities

Direct Lake Functions

Core Functions

Function	Purpose
`check_fallback_reason`	Check why model falls back to DirectQuery
`get_direct_lake_lakehouse`	Get lakehouse connected to model
`get_direct_lake_source`	Get SQL endpoint and lakehouse info
`generate_direct_lake_semantic_model`	Create new Direct Lake model

Schema Management

Function	Purpose
`direct_lake_schema_compare`	Compare model schema with lakehouse
`direct_lake_schema_sync`	Sync model schema from lakehouse

Guardrails

Function	Purpose
`get_direct_lake_guardrails`	Get guardrail limits for model
`get_sku_size`	Get SKU capacity info
`get_directlake_guardrails_for_sku`	Get guardrails for specific SKU

Cache Management

Function	Purpose
`warm_direct_lake_cache_isresident`	Warm cache using IsResident
`warm_direct_lake_cache_perspective`	Warm cache using perspective

Connection Updates

Function	Purpose
`update_direct_lake_model_connection`	Update lakehouse connection
`update_direct_lake_model_lakehouse_connection`	Legacy connection update

Checking Fallback Reasons

Direct Lake models can fall back to DirectQuery mode. Use check_fallback_reason to diagnose:

from sempy_labs.directlake import check_fallback_reason
 
# Check specific model
result = check_fallback_reason(
    dataset="My Direct Lake Model",
    workspace="My Workspace"
)
 
# Returns DataFrame with fallback reasons per table
print(result)

Common Fallback Reasons

Reason	Cause	Solution
`ColumnNotInPartition`	Column missing from Delta table	Add column to lakehouse table
`ParquetTypeMismatch`	Data type mismatch	Update lakehouse table schema
`UnsupportedFilter`	DAX filter not supported	Modify DAX query
`Guardrail`	Exceeded capacity limits	Upgrade capacity or reduce data

Schema Synchronization

Compare Schemas

Sync Schema

Guardrails

Direct Lake has limits based on capacity SKU:

Guardrail Limits

Guardrail	Description
Max Rows Per Table	Maximum rows per table
Max Size Per Table	Maximum table size in GB
Max Columns Per Table	Maximum columns per table
Max Model Size	Maximum total model size

Generating Direct Lake Models

Create a new Direct Lake model from lakehouse tables:

Updating Connections

Change the lakehouse a Direct Lake model points to:

Cache Warming

Warm the Direct Lake cache after model refresh:

Using IsResident

Using Perspective

Migration to Direct Lake

The library provides migration tools in src/sempy_labs/migration/:

Migration Workflow

Migrate calculated tables to lakehouse as Delta tables
Create Direct Lake model with same structure
Migrate measures and other objects
Validate and test

Example Migration

Best Practices

Do's

✅ Always check guardrails before deploying
✅ Use schema sync after lakehouse changes
✅ Warm cache after scheduled refreshes
✅ Monitor fallback reasons regularly

Don'ts

❌ Don't ignore fallback warnings
❌ Don't exceed guardrail limits
❌ Don't modify lakehouse schema without syncing model
❌ Don't use unsupported DAX patterns

Troubleshooting

Model Falls Back to DirectQuery

Run check_fallback_reason() to identify cause
Check column mappings with direct_lake_schema_compare()
Verify data types match between model and lakehouse
Check guardrails with get_direct_lake_guardrails()

Schema Mismatch

Run direct_lake_schema_compare() to see differences
Run direct_lake_schema_sync() to fix mismatches
Verify partition entity mappings

Performance Issues

Check cache state with warm_direct_lake_cache_isresident()
Verify partitions are properly configured
Review query patterns for unsupported filters

Related Resources

Resource	URL
Direct Lake Overview	Microsoft Docs
Guardrails	Microsoft Docs
Migration Notebook	Notebook
API Docs	ReadTheDocs