Refreshing Semantic Models

Trigger, monitor, validate, and troubleshoot semantic model refreshes via the Power BI Enhanced Refresh REST API and Fabric CLI.

Core Concepts

A semantic model refresh reloads data from upstream sources and/or recalculates dependent objects (calculated columns, calculated tables, measures). The scope can be the entire model, specific tables, or individual partitions.

Six refresh types are available via the REST API; a seventh (

add

full

automatic

dataOnly

calculate

clearValues

defragment

add

*

dataOnly

calculate

For detailed descriptions, behavior with incremental refresh policies, commit modes, and parallelism options, consult

references/refresh-types.md

Refresh Workflow

Step 1: Resolve IDs

Extract the workspace and model GUIDs needed for API calls:

WS_ID=$(fab get "WorkspaceName.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "WorkspaceName.Workspace/ModelName.SemanticModel" -q "id" | tr -d '"')

Step 2: Query Baseline Data (Pre-Refresh Validation)

Before triggering the refresh, capture a baseline snapshot to later verify that data actually changed. Execute a DAX query against the model to get current row counts or max dates:

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/executeQueries" \
  -X post -i '{
    "queries": [{"query": "EVALUATE ROW(\"RowCount\", COUNTROWS(FactSales), \"MaxDate\", MAX(FactSales[OrderDate]))"}],
    "serializerSettings": {"includeNulls": true}
  }'

Record the output. This baseline is compared after refresh to confirm new data arrived.

Step 3: Trigger the Refresh

Full model refresh (simplest):

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

Refresh specific tables:

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{
    "type": "full",
    "objects": [{"table": "FactSales"}, {"table": "DimProduct"}]
  }'

Refresh specific partitions:

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{
    "type": "full",
    "objects": [
      {"table": "FactSales", "partition": "FactSales_2024"},
      {"table": "FactSales", "partition": "FactSales_2023"}
    ]
  }'

Data-only refresh (skip recalculation):

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"dataOnly","objects":[{"table":"FactSales"}]}'

Calculate only (no data reload):

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"calculate"}'

Clear values from a table:

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"clearValues","objects":[{"table":"StagingTable"}]}'

For the script-based approach with CLI arguments, use

scripts/refresh_model.py

Step 4: Monitor Status

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

Status values:

Unknown

InProgress

Completed

Failed

Disabled

Cancelled

Step 5: Post-Refresh Validation

After the refresh completes, re-run the same DAX query from Step 2 and compare:

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/executeQueries" \
  -X post -i '{
    "queries": [{"query": "EVALUATE ROW(\"RowCount\", COUNTROWS(FactSales), \"MaxDate\", MAX(FactSales[OrderDate]))"}],
    "serializerSettings": {"includeNulls": true}
  }'

If data has not changed after a successful refresh:

• The upstream data source has not been updated
• The ETL pipeline (Fabric pipeline, notebook, Data Factory, or other orchestration) needs to run first
• Check the lakehouse/warehouse/SQL database to verify fresh data exists
• For Fabric lakehouses: run

  fab run "Workspace.Workspace/Pipeline.DataPipeline"

  or trigger the notebook
• The refresh only pulls what the source provides; if the source is stale, the refresh will succeed but show no new data

Step 6: Cancel (if needed)

To cancel an in-progress enhanced refresh, first retrieve the

requestId

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

The response includes a

requestId

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes/<requestId>" \
  -X delete

Only works for refreshes triggered via the Enhanced API (not scheduled or portal refreshes).

Using the Refresh Script

The

scripts/refresh_model.py

# Full refresh
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID

# Refresh specific tables
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --tables Sales,Calendar

# Refresh specific partitions
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --partitions Sales:Sales_2024

# Data-only then calculate (two-phase)
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID -t dataOnly --tables FactSales
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID -t calculate

# Partial batch with parallelism
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --commit partialBatch --parallelism 4

# Skip incremental refresh policy
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --no-policy

# Check status only
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --status-only

# Poll until complete
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --poll

Enhanced Refresh Options

The Enhanced Refresh API (Premium/Fabric capacity required) extends the standard refresh with:

type

automatic

commitMode

transactional

maxParallelism

10

retryCount

0

objects

applyRefreshPolicy

true

effectiveDate

timeout

05:00:00

Common Patterns

Two-Phase Refresh (Large Models)

Split data loading and recalculation for better control and failure isolation:

1. dataOnly

   with

   partialBatch

   to reload all tables (each committed independently)

2. calculate

   with

   transactional

   to recalculate everything atomically

Selective Partition Refresh

For tables with incremental refresh, refresh only specific time-range partitions rather than the entire table. To discover partition names, query the model's TMSL metadata via the XMLA endpoint using Tabular Editor, SSMS, or by exporting with the Fabric CLI:

fab export "Workspace.Workspace/Model.SemanticModel" -o /tmp/model -f

Inspect the exported TMDL table files; each

partition

objects

Refresh After ETL

When orchestrating a data pipeline:

1. Run the upstream ETL (Fabric pipeline, notebook, ADF, or custom)
2. Verify fresh data in the source (lakehouse, warehouse, SQL)
3. Trigger the semantic model refresh
4. Validate with a DAX query that row counts or max dates changed
5. If unchanged, investigate the ETL output; the semantic model refresh succeeded but the source was stale

Troubleshooting

Quick reference for the most common failures. For the full troubleshooting guide with debugging workflows and detailed error tables, read

references/troubleshooting.md

fab cp

Table.TransformColumnTypes

Table.RenameColumns

dataOnly

calculate

Debugging per-table failures

When a full refresh fails, isolate the failing table by refreshing individual tables via the Enhanced Refresh API:

# Refresh dimensions first
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full","objects":[{"table":"Customers"}]}'

# Then facts
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full","objects":[{"table":"Invoices"}]}'

# Then recalculate
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"calculate"}'

Check the failing table's partition expression and compare source schema against the model's expected column names and types via

fab export

fab table schema

Large Model Strategies

Models over 1 GB or with refresh times exceeding an hour benefit from targeted approaches:

• Partition-level refresh: Refresh individual table partitions via the enhanced REST API or XMLA endpoint instead of the full model. Requires Premium/Fabric capacity.
• Incremental refresh: Automatically partition large tables by date; only recent data refreshes each cycle. Configure

  RangeStart

  /

  RangeEnd

  parameters in Power Query. Also supports detect-data-changes to skip unchanged partitions entirely.
• Aggregations: Pre-aggregate large fact tables at a coarser grain into an import-mode aggregation table. Detail queries fall through to DirectQuery. Reduces both refresh time and memory.
• Hybrid tables: Historical partitions in import mode; a real-time DirectQuery partition for recent data. Related tables must be Dual storage mode.
• Scale-out: Isolate refresh from query workloads by enabling semantic model scale-out on Premium capacities. A read-only replica handles queries while the primary refreshes.

Capacity Limits

Pro capacity supports only full-model standard refreshes. Enhanced refresh features (table/partition targeting, commit modes, parallelism, cancel, timeout override) require Premium or Fabric capacity.

Requirements

• Workspace contributor or higher permissions

• fab

  CLI authenticated:

  fab auth login

Additional Resources

Reference Files

• references/refresh-types.md

  -- Complete reference for all 7 refresh types, commit modes, parallelism, incremental policy interaction, status values, XMLA/TMSL details, and the two-phase refresh pattern

• references/troubleshooting.md

  -- Comprehensive troubleshooting guide: credential errors, type/schema mismatches, timeouts, capacity limits, incremental refresh issues, debugging workflows, and large model strategies

Scripts

• scripts/refresh_model.py

  -- CLI tool for triggering and monitoring refreshes with all enhanced options

Related Skills

• review-semantic-model

  -- Structured model quality and performance review

• lineage-analysis

  -- Downstream report discovery and impact analysis

• standardize-naming-conventions

  -- Naming audit and remediation

• fabric-cli

  (fabric-cli plugin) -- Workspace and item management via

  fab

  CLI