Skip to content

refresh_semanticmodel

Refresh a semantic model and wait for the refresh to finish. A published model holds no data until it refreshes.

Step fragment for a hooks file. Shared step keys are under Steps.

- action: refresh_semanticmodel
  item: <Name>.SemanticModel         # `.SemanticModel` may be omitted
  timeout_seconds: 900
  poll_seconds: 15
  request:                           # optional: an enhanced refresh
    type: full
    commitMode: transactional
    objects:
      - table: Sales
      - table: Orders
        partition: Orders-2026
  on_error: fail                     # default: stop the deploy here; `continue` logs it and goes on

Keys

Key Required Description
item yes The model, <Name> or <Name>.SemanticModel.
timeout_seconds no Seconds to wait before failing. Default 900.
poll_seconds no Seconds between status checks. Default 15.
request no The body of an enhanced refresh, in Power BI's own keys: type, commitMode, maxParallelism, retryCount, timeout, applyRefreshPolicy, effectiveDate and objects, a list of table or table and partition. allez sends it unchanged and adds notifyOption: NoNotification. A key Power BI does not know fails the step with Power BI's message. It must be a mapping; a string fails the file at load.

Behaviour

fab job run does not cover semantic models, so this uses Power BI's refresh API through fab api -A powerbi.

With request: an enhanced refresh

  1. POST groups/<ws>/datasets/<id>/refreshes with the request plus notifyOption. Power BI answers with the refresh's id, so a scheduled refresh that starts at the same time is never mistaken for this one.
  2. GET groups/<ws>/datasets/<id>/refreshes/<id> every poll_seconds. Each table or partition prints a line the poll its status changes, with the elapsed time it was seen at.
  3. When the refresh ends, a report (below). A Direct Lake model returns no metrics; the attempt's duration then comes from its start and end times.
  refresh 87f31ef7 of <Name> requested (full, transactional, 2 objects); polling every 15s
  ✓ Sales                            Completed   seen at 0:45 (±15s)
  ✓ Orders | Orders-2026             Completed   seen at 1:00 (±15s)
  refresh of <Name> completed in 1m 12s, 1 attempt
    attempt 1 (Data): 71.3s · external query 24.2s · CPU 24.7s · 432,682 rows · peak memory 410 MB
    warning 0xC11C0021: …
  objects: 2 completed, 0 failed

Completed means the step succeeded. Failed, TimedOut, Disabled or Cancelled fails the step. The report then also shows each attempt's error code and description and the objects that did not complete, and the step's error names the first of them.

Running past timeout_seconds sends DELETE groups/<ws>/datasets/<id>/refreshes/<id>, which cancels the refresh, then fails the step.

On the step's Would run line, allez deploy --plan prints objects as a count.

Without request: a plain refresh

  1. POST groups/<ws>/datasets/<id>/refreshes with {"notifyOption": "NoNotification"}, the only option a service principal may send.
  2. GET groups/<ws>/datasets/<id>/refreshes?$top=1 every poll_seconds until the newest refresh leaves Unknown (in progress). Completed means the step succeeded. Failed or Disabled fails the step, with Power BI's error detail.

Power BI serves no details and no cancel for a plain refresh. Nothing prints while it runs, and running past timeout_seconds fails the step while the refresh carries on. The model's refresh history in the portal shows how it ended.

The deploying identity must own the model, or Power BI answers 403. Run a takeover first: a fab_api step under pre_deploy_hooks. The model also needs credentials for its data source.

Refresh Dataset In Group · Get Refresh Execution Details In Group · Cancel Refresh In Group · Get Refresh History In Group