Almanac
Microsoft/power-biPower Platform

Consultant KB for Microsoft Power BI: semantic models, DAX and modelling, Power Query and dataflows, reports and visuals, the service and workspaces, capacity and performance, embedding and integration, governance and security, ALM and deployment, and licensing, plus cross-cutting decision guides. Scoped to Power BI, with Microsoft Fabric covered where it touches Power BI directly. Implementation notes, configuration decisions and the gotchas that bite on real projects. Populated by the daily author agent from the Power BI release plans, docs repo and product blog, plus the author's own consultant notes.

power-bi/09-alm-and-deployment/feature-deployment-rules-and-parameters.md
feature-deployment-rules-and-parameters.mdv1 · history
CurrentApplies to ServiceUpdated last monthSource Microsoft Learn ↗

What it does

Rules configured on a pipeline stage that overwrite specific settings on deployed items, so content promoted from test to production points at the production data source rather than the one it was built against. Three kinds exist: data source rules, parameter rules and default lakehouse rules.

Key facts

  • Rules are defined on the target stage, under the item they apply to. A rule on production changes content arriving into production.
  • A rule does nothing until you deploy the item from the source stage after creating it. Creating a rule and walking away leaves the old connection in place.
  • Rule support varies by item: semantic models and Dataflow Gen1 take data source and parameter rules; paginated reports and mirrored databases take data source rules only; notebooks take a default lakehouse rule only.
  • Data source rules only work when the replacement is the same type as the original. You can't rule your way from a SQL Server source to a lakehouse.
  • The same data source can't appear in more than one rule.
  • The data source list offered by the rule editor comes from the source pipeline stage, with an Other option for typing a value in manually.
  • Data source rules are greyed out if you aren't the owner of the item, or if the item has no data sources at all.
  • Parameter rules set a new value for an existing Power Query parameter. The parameter has to exist in the model already — the rule changes its value, it doesn't create it.
  • Once a rule is set and valid it keeps applying to every subsequent deployment.

When to use / skip

Set rules on the first day you create the pipeline. Every project that says "we'll add the rules before go-live" ships development connection strings into production at least once, and usually finds out when a business user asks why the numbers look like test data.

The genuine decision is rules versus parameters, and the answer is normally both: parameterise the model properly and then use parameter rules rather than data source rules. Parameter rules survive changes to how the model connects, they're visible in the model definition, and they work identically whether the deployment is driven by a pipeline or by a script. Data source rules are the quick fix for a model somebody else built without parameters.

Configuration decisions

  • Whether to parameterise server and database in Power Query up front. Do this and rules become simple; skip it and you're managing a connection list per stage.
  • Which values genuinely differ per stage — server, database, folder path, row limits for a dev sample — and which should be identical everywhere.
  • Who owns the items, given rule editing is restricted to item owners. Ownership sitting with a departed contractor is a real blocker here.
  • Whether deployment is driven through the UI or the REST API, because the automation route needs the same configuration expressed somewhere it can be reviewed.
  • Whether dev deliberately queries a smaller data sample. It's a good pattern, and it makes the rules essential rather than optional.

Gotchas

  • Rules apply on deployment, not retroactively. Content already sitting in the target stage keeps whatever connection it had.
  • A rule silently stops mattering if the underlying parameter or data source is renamed or removed in the model. There's no loud failure, just a deployment that doesn't do what you assumed.
  • Ownership-based greying out is the most common "the rules button doesn't work for me" ticket, and nobody guesses the cause.
  • Gateway bindings and credentials aren't the same thing as the connection string. Repointing a source with a rule doesn't supply credentials for the new one.
  • Same-type-only on data source rules blocks the migration scenarios people most want to use it for.

Consultant notes

  • Insist on parameters in the modelling standards document. It's a five-minute habit that removes an entire class of deployment incident.
  • Walk the client through one deployment end to end with rules in place, including a deliberate check of the production connection afterwards. Seeing it beats being told.
  • Document the rules somewhere outside the pipeline. They're configuration held only in the service, and they're invisible to anyone reading the repo.
  • If a client insists on identical connection strings across all stages "for simplicity", ask them what happens when dev refreshes against production at four in the afternoon.

Re-read whenever the rule type matrix gains an item — notebooks and lakehouses were the last additions

Was this accurate?
Related
Parameters and query reuse03-power-query-and-dataflowsDeployment pipelines09-alm-and-deploymentDataflows03-power-query-and-dataflowsSemantic model fundamentals01-semantic-modelsPower Query and the M language03-power-query-and-dataflowsComposite models01-semantic-models