Data Studio reports: filter controls are undocumented and can't be configured via the CLI

[leobury]

Summary

Data Studio reports can render interactive filter controls (date-range picker, team picker, contributor picker) when reserved $-variables appear in a tile's SQL — but this behaviour is undocumented and the CLI provides no way to declare these controls or set their default values.

What works today

Adding a reserved selector variable to a tile's SQL auto-renders the matching control on the report:

• $start_date / $end_date — date-range picker
• $team_ids — team picker
• $contributors — contributor picker

Example (tested, works):

WHERE m.date >= $start_date::date AND m.date <= $end_date::date
  AND (-1 IN ($team_ids) OR du.team_id IN (
    SELECT descendant_id FROM dx_team_hierarchies WHERE ancestor_id IN ($team_ids)))

Gaps

1. Not documented — including in the official skill. Neither dx studio reports --help, the report YAML schema, nor the official dx-cli agent skill shipped with the CLI mention these report-level selector variables. The only $-variables documented anywhere (skill references + docs) are for scorecard checks ($entity_identifier, $entity_github_repo_ids, …) in references/scorecards-management.md — a different mechanism. references/report-creation.md covers the report YAML but says nothing about filter controls.
2. No control declaration / defaults via CLI. The report YAML (init/create/update) exposes only name, owner_email, description, markdown_notes, access fields, and tiles {id, title, sql, chart_type, chart_config}. There is no controls / variables / defaults field, and dx studio reports info --json returns none either. So a report authored/edited via the CLI cannot ship with default filter values (default date range, team = all), and may load in an undefined filter state until a user sets the controls manually in the UI.
3. --variable doesn't apply to saved reports. It only exists for ad-hoc dx studio query, so it can't seed a report's control defaults.

Requests

• Document the reserved report selector variables and how they render controls (ideally in references/report-creation.md / dx studio reports --help).
• Add YAML support to declare report controls and set their default values (default date range, default team/contributor selection).

Environment

• dx CLI: 0.5.5
• Node: v22.22.3

[emmahoggan]

Thanks for the report @leobury - we've got some upcoming plans to add variable support for the cli, but in the interim the help/skills documentation has been updated with some context and a note on the current limitations.