Skip to main content
A parameterized query is a tracked query that declares one or more inputs. Instead of hard-coding a region or a customer into the SQL, the query leaves a slot the dashboard fills in — from a control the viewer changes, or from who the viewer is. The query re-runs at the source with the new value, so the numbers are always computed on live data, not filtered client-side. This is the mechanism behind interactive and personalized dashboards: a control on the dashboard sets a parameter, and every artifact bound to that parameter re-runs.

​
Declaring a parameter

Ask the agent for it in plain language — “make region a filter”, “scope this to the signed-in user’s team” — and it declares the parameter when it builds the query. You can also review and adjust declarations in the query editor’s Params panel, beside the SQL. Each parameter has:

​
Using a parameter in SQL

Reference a parameter with a colon placeholder — :region. Bag of words binds the value safely (never string-substituted), so a parameter can’t be used for SQL injection.
The (:region IS NULL OR region = :region) shape is the idiom for an optional filter: when the control is set to a value, only those rows return; when it’s cleared (NULL), all rows return. A list parameter uses IN instead:
Each connector binds parameters in its own dialect — a DAX measure filter for Power BI, a bound parameter for SQL sources. You write the query in the source’s language; the placeholder is the same :name everywhere.

​
Where a value comes from

Every parameter draws its value from one of three sources. This is the setting that turns an ordinary filter into a personalized one.

input

The viewer sets it from a control on the dashboard. A plain interactive filter.

identity

The value is bound to the viewer’s identity and resolved server-side per person. It is never editable and never sent from the browser.

input_identity_default

Defaults to the viewer’s identity, but the viewer can override it with a control — personal by default, explorable when allowed.
An identity parameter is what makes one shared dashboard show each person their own slice: bind team to the viewer’s team and everyone opens the same artifact but sees only their team’s rows. Because identity parameters resolve on the server, a viewer cannot read or change another person’s value. See personalization.
An identity parameter scopes data by a value Bag of words resolves from the viewer’s profile. It is not a substitute for source-enforced security on sources that already model per-user visibility (a Power BI tenant with RLS, a warehouse with row-level security). For those, use a per-user connection so the source filters under each viewer’s own credentials.

​
Giving a control its choices

A control that offers a fixed set of values needs to know that set. There are two ways to supply it, and one rule.
  • Static options — a list you declare on the parameter (Rock, Jazz, Classical).
  • Options source — another query in the same report supplies the choices: point the parameter at that query and name its value and label columns. A Genres query can feed the genre control of an Albums by Genre query.
A control must never derive its choices from the rows it filters. Selecting a value would then collapse the list to just that value. Always supply choices from a static list or a separate options-source query — the “filter-space” pattern — so the full set of choices stays stable as the viewer selects.

​
What the viewer experiences

On a dashboard, each declared input parameter renders as a control at the top of the artifact. Changing it re-runs the consuming queries and refreshes the affected visualizations in place — the rest of the dashboard is untouched. Identity parameters render as a read-only “scoped to you” note rather than a control. Results are cached per viewer and per set of values, so re-opening a dashboard with the same inputs is instant, while a new combination runs fresh.

Dashboard artifacts

Interactive controls, per-viewer personalization, and View-as.

Authentication and Access

Per-user connections, so a source enforces its own row-level security.