gh-data-goblin-fabric-cli-plugin-fabric-cli-plugin/skills/fabric-cli/references/semantic-models.md

Semantic Model Operations

Comprehensive guide for working with semantic models (Power BI datasets) using the Fabric CLI.

Overview

Semantic models in Fabric use TMDL (Tabular Model Definition Language) format for their definitions. This guide covers getting, updating, exporting, and managing semantic models.

Getting Model Information

Basic Model Info

# Check if model exists
fab exists "Production.Workspace/Sales.SemanticModel"

# Get model properties
fab get "Production.Workspace/Sales.SemanticModel"

# Get model with all details (verbose)
fab get "Production.Workspace/Sales.SemanticModel" -v

# Get only model ID
fab get "Production.Workspace/Sales.SemanticModel" -q "id"

Get Model Definition

The model definition contains all TMDL parts (tables, measures, relationships, etc.):

# Get full definition (all TMDL parts)
fab get "Production.Workspace/Sales.SemanticModel" -q "definition"

# Save definition to file
fab get "Production.Workspace/Sales.SemanticModel" -q "definition" -o /tmp/model-def.json

Get Specific TMDL Parts

# Get model.tmdl (main model properties)
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?path=='model.tmdl'].payload | [0]"

# Get specific table definition
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?path=='definition/tables/Customers.tmdl'].payload | [0]"

# Get all table definitions
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?starts_with(path, 'definition/tables/')]"

# Get relationships.tmdl
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?path=='definition/relationships.tmdl'].payload | [0]"

# Get functions.tmdl (DAX functions)
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?path=='definition/functions.tmdl'].payload | [0]"

# Get all definition part paths (for reference)
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[].path"

Exporting Models

Export as PBIP (Power BI Project)

PBIP format is best for local development in Power BI Desktop or Tabular Editor:

# Export using the export script
python3 scripts/export_semantic_model_as_pbip.py \
  "Production.Workspace/Sales.SemanticModel" -o /tmp/exports

Export as TMDL

The export script creates PBIP format which includes TMDL in the definition folder:

python3 scripts/export_semantic_model_as_pbip.py \
  "Production.Workspace/Sales.SemanticModel" -o /tmp/exports

# TMDL files will be in: /tmp/exports/Sales.SemanticModel/definition/

Export Specific Parts Only

# Export just tables
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?starts_with(path, 'definition/tables/')]" -o /tmp/tables.json

# Export just measures (within tables)
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?contains(path, '/tables/')]" | grep -A 20 "measure"

Listing Model Contents

# List all items in model (if OneLake enabled)
fab ls "Production.Workspace/Sales.SemanticModel"

# Query model structure via API
fab api workspaces -q "value[?displayName=='Production'].id | [0]" | xargs -I {} \
  fab api "workspaces/{}/items" -q "value[?type=='SemanticModel']"

Updating Model Definitions

CRITICAL: When updating semantic models, you must:

1. Get the full definition
2. Modify the specific parts you want to change
3. Include ALL parts in the update request (modified + unmodified)
4. Never include .platform file
5. Test immediately

Update Workflow

# 1. Get workspace and model IDs
WS_ID=$(fab get "Production.Workspace" -q "id")
MODEL_ID=$(fab get "Production.Workspace/Sales.SemanticModel" -q "id")

# 2. Get current definition
fab get "Production.Workspace/Sales.SemanticModel" -q "definition" -o /tmp/current-def.json

# 3. Modify definition (edit JSON file or use script)
# ... modify /tmp/current-def.json ...

# 4. Wrap definition in update request
cat > /tmp/update-request.json <<EOF
{
  "definition": $(cat /tmp/current-def.json)
}
EOF

# 5. Update via API
fab api -X post "workspaces/$WS_ID/semanticModels/$MODEL_ID/updateDefinition" \
  -i /tmp/update-request.json \
  --show_headers

# 6. Extract operation ID from Location header and poll status
OPERATION_ID="<extracted-from-Location-header>"
fab api "operations/$OPERATION_ID"

Example: Add a Measure

# Python script to add measure to definition
import json

with open('/tmp/current-def.json', 'r') as f:
    definition = json.load(f)

# Find the table's TMDL part
for part in definition['parts']:
    if part['path'] == 'definition/tables/Sales.tmdl':
        # Decode base64 content
        import base64
        tmdl_content = base64.b64decode(part['payload']).decode('utf-8')

        # Add measure (simplified - real implementation needs proper TMDL syntax)
        measure_tmdl = """
measure 'Total Revenue' = SUM(Sales[Amount])
    formatString: #,0.00
    displayFolder: "KPIs"
"""
        tmdl_content += measure_tmdl

        # Re-encode
        part['payload'] = base64.b64encode(tmdl_content.encode('utf-8')).decode('utf-8')

# Save modified definition
with open('/tmp/modified-def.json', 'w') as f:
    json.dump(definition, f)

Executing DAX Queries

Use Power BI API to execute DAX queries against semantic models:

# Get model ID
MODEL_ID=$(fab get "Production.Workspace/Sales.SemanticModel" -q "id")

# Execute simple DAX query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE VALUES(Date[Year])"
  }]
}'

# Execute TOPN query
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE TOPN(10, Sales, Sales[Amount], DESC)"
  }]
}'

# Execute multiple queries
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [
    {"query": "EVALUATE VALUES(Date[Year])"},
    {"query": "EVALUATE SUMMARIZE(Sales, Date[Year], \"Total\", SUM(Sales[Amount]))"}
  ],
  "serializerSettings": {
    "includeNulls": false
  }
}'

# Execute query with parameters
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{
    "query": "EVALUATE FILTER(Sales, Sales[Year] = @Year)",
    "parameters": [
      {"name": "@Year", "value": "2024"}
    ]
  }]
}'

Using the DAX query script

python3 scripts/execute_dax.py \
  --workspace "Production.Workspace" \
  --model "Sales.SemanticModel" \
  --query "EVALUATE TOPN(10, Sales)" \
  --output /tmp/results.json

Refreshing Models

# Get workspace and model IDs
WS_ID=$(fab get "Production.Workspace" -q "id")
MODEL_ID=$(fab get "Production.Workspace/Sales.SemanticModel" -q "id")

# Trigger full refresh
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" -X post -i '{"type":"Full"}'

# Check latest refresh status
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

# Get refresh history
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes"

# Cancel refresh
REFRESH_ID="<refresh-request-id>"
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes/$REFRESH_ID" -X delete

Model Refresh Schedule

MODEL_ID=$(fab get "Production.Workspace/Sales.SemanticModel" -q "id")

# Get current schedule
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule"

# Update schedule (daily at 2 AM)
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule" -X patch -i '{
  "enabled": true,
  "days": ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
  "times": ["02:00"],
  "localTimeZoneId": "UTC"
}'

# Disable schedule
fab api -A powerbi "datasets/$MODEL_ID/refreshSchedule" -X patch -i '{
  "enabled": false
}'

Copying Models

# Copy semantic model between workspaces (full paths required)
fab cp "Dev.Workspace/Sales.SemanticModel" "Production.Workspace/Sales.SemanticModel" -f

# Copy with new name
fab cp "Dev.Workspace/Sales.SemanticModel" "Production.Workspace/SalesProduction.SemanticModel" -f

# Note: Both source and destination must include workspace.Workspace/model.SemanticModel
# This copies the definition, not data or refreshes

Model Deployment Workflow

Dev to Production

#!/bin/bash

DEV_WS="Development.Workspace"
PROD_WS="Production.Workspace"
MODEL_NAME="Sales.SemanticModel"

# 1. Export from dev
fab export "$DEV_WS/$MODEL_NAME" -o /tmp/deployment

# 2. Test locally (optional - requires Power BI Desktop)
# Open /tmp/deployment/Sales/*.pbip in Power BI Desktop

# 3. Import to production
fab import "$PROD_WS/$MODEL_NAME" -i /tmp/deployment/$MODEL_NAME

# 4. Trigger refresh in production
PROD_MODEL_ID=$(fab get "$PROD_WS/$MODEL_NAME" -q "id")
fab api -A powerbi "datasets/$PROD_MODEL_ID/refreshes" -X post -i '{"type": "Full"}'

# 5. Monitor refresh
sleep 10
fab api -A powerbi "datasets/$PROD_MODEL_ID/refreshes" -q "value[0]"

Working with Model Metadata

Update Display Name

fab set "Production.Workspace/Sales.SemanticModel" -q displayName -i "Sales Analytics Model"

Update Description

fab set "Production.Workspace/Sales.SemanticModel" -q description -i "Primary sales analytics semantic model for production reporting"

Advanced Patterns

Extract All Measures

# Get all table definitions containing measures
fab get "Production.Workspace/Sales.SemanticModel" -q "definition.parts[?contains(path, '/tables/')]" -o /tmp/tables.json

# Process with script to extract measures
python3 << 'EOF'
import json
import base64

with open('/tmp/tables.json', 'r') as f:
    parts = json.load(f)

measures = []
for part in parts:
    if 'tables' in part['path']:
        content = base64.b64decode(part['payload']).decode('utf-8')
        # Extract measure definitions (simple regex - real parser needed for production)
        import re
        measure_blocks = re.findall(r'measure\s+[^\n]+\s*=.*?(?=\n\s*(?:measure|column|$))', content, re.DOTALL)
        measures.extend(measure_blocks)

for i, measure in enumerate(measures, 1):
    print(f"\n--- Measure {i} ---")
    print(measure)
EOF

Compare Models (Diff)

# Export both models
fab get "Production.Workspace/Sales.SemanticModel" -q "definition" -o /tmp/model1-def.json
fab get "Dev.Workspace/Sales.SemanticModel" -q "definition" -o /tmp/model2-def.json

# Use diff tool
diff <(jq -S . /tmp/model1-def.json) <(jq -S . /tmp/model2-def.json)

# jq -S sorts keys for consistent comparison

Backup Model Definition

#!/bin/bash

WORKSPACE="Production.Workspace"
MODEL="Sales.SemanticModel"
BACKUP_DIR="/backups/$(date +%Y%m%d)"

mkdir -p "$BACKUP_DIR"

# Export as multiple formats for redundancy
fab get "$WORKSPACE/$MODEL" -q "definition" -o "$BACKUP_DIR/definition.json"

# Export as PBIP
python3 scripts/export_semantic_model_as_pbip.py \
  "$WORKSPACE/$MODEL" -o "$BACKUP_DIR/pbip"

# Save metadata
fab get "$WORKSPACE/$MODEL" -o "$BACKUP_DIR/metadata.json"

echo "Backup completed: $BACKUP_DIR"

TMDL Structure Reference

A semantic model's TMDL definition consists of these parts:

model.tmdl                          # Model properties, culture, compatibility
.platform                           # Git integration metadata (exclude from updates)
definition/
├── model.tmdl                     # Alternative location for model properties
├── database.tmdl                  # Database properties
├── roles.tmdl                     # Row-level security roles
├── relationships.tmdl             # Relationships between tables
├── functions.tmdl                 # DAX user-defined functions
├── expressions/                   # M queries for data sources
│   ├── Source1.tmdl
│   └── Source2.tmdl
└── tables/                        # Table definitions
    ├── Customers.tmdl             # Columns, measures, hierarchies
    ├── Sales.tmdl
    ├── Products.tmdl
    └── Date.tmdl

Common TMDL Parts to Query

MODEL="Production.Workspace/Sales.SemanticModel"

# Model properties
fab get "$MODEL" -q "definition.parts[?path=='model.tmdl'].payload | [0]"

# Roles and RLS
fab get "$MODEL" -q "definition.parts[?path=='definition/roles.tmdl'].payload | [0]"

# Relationships
fab get "$MODEL" -q "definition.parts[?path=='definition/relationships.tmdl'].payload | [0]"

# Data source expressions
fab get "$MODEL" -q "definition.parts[?starts_with(path, 'definition/expressions/')]"

# All tables
fab get "$MODEL" -q "definition.parts[?starts_with(path, 'definition/tables/')].path"

Troubleshooting

Model Not Found

# Verify workspace exists
fab exists "Production.Workspace"

# List semantic models in workspace
WS_ID=$(fab get "Production.Workspace" -q "id")
fab api "workspaces/$WS_ID/items" -q "value[?type=='SemanticModel']"

Update Definition Fails

Common issues:

1. Included .platform file: Never include this in updates
2. Missing parts: Must include ALL parts, not just modified ones
3. Invalid TMDL syntax: Validate TMDL before updating
4. Encoding issues: Ensure base64 encoding is correct

# Debug update operation
fab api "operations/$OPERATION_ID" -q "error"

DAX Query Errors

# Check model is online
fab get "Production.Workspace/Sales.SemanticModel" -q "properties"

# Try simple query first
MODEL_ID=$(fab get "Production.Workspace/Sales.SemanticModel" -q "id")
fab api -A powerbi "datasets/$MODEL_ID/executeQueries" -X post -i '{
  "queries": [{"query": "EVALUATE {1}"}]
}'

Storage Mode

Check table partition mode to determine if model is Direct Lake, Import, or DirectQuery.

# Get table definition and check partition mode
fab get "ws.Workspace/Model.SemanticModel" -q "definition.parts[?contains(path, 'tables/TableName')].payload | [0]"

Output shows partition type:

# Direct Lake
partition TableName = entity
    mode: directLake
    source
        entityName: table_name
        schemaName: schema
        expressionSource: DatabaseQuery

# Import
partition TableName = m
    mode: import
    source =
        let
            Source = Sql.Database("connection", "database"),
            Data = Source{[Schema="schema",Item="table"]}[Data]
        in
            Data

Workspace Access

# Get workspace ID
fab get "ws.Workspace" -q "id"

# List users with access
fab api -A powerbi "groups/<workspace-id>/users"

Output:

{
  "value": [
    {
      "emailAddress": "user@domain.com",
      "groupUserAccessRight": "Admin",
      "displayName": "User Name",
      "principalType": "User"
    }
  ]
}

Access rights: Admin, Member, Contributor, Viewer

Find Reports Using a Model

Check report's definition.pbir for byConnection.semanticmodelid:

# Get model ID
fab get "ws.Workspace/Model.SemanticModel" -q "id"

# Check a report's connection
fab get "ws.Workspace/Report.Report" -q "definition.parts[?contains(path, 'definition.pbir')].payload | [0]"

Output:

{
  "datasetReference": {
    "byConnection": {
      "connectionString": "...semanticmodelid=bee906a0-255e-..."
    }
  }
}

To find all reports using a model, check each report's definition.pbir for matching semanticmodelid.

Performance Tips

1. Cache model IDs: Don't repeatedly query for the same ID
2. Use JMESPath filtering: Get only what you need
3. Batch DAX queries: Combine multiple queries in one request
4. Export during off-hours: Large model exports can be slow
5. Use Power BI API for queries: It's optimized for DAX execution

Security Considerations

1. Row-Level Security: Check roles before exposing data
2. Credentials in data sources: Don't commit data source credentials
3. Sensitive measures: Review calculated columns/measures for sensitive logic
4. Export restrictions: Ensure exported models don't contain sensitive data

Related Scripts

• scripts/create_direct_lake_model.py - Create Direct Lake model from lakehouse table
• scripts/export_semantic_model_as_pbip.py - Export model as PBIP
• scripts/execute_dax.py - Execute DAX queries