# Parameters ## Tools A parameter is referenced from a widget argument template. Defaults are the only persisted parameter state — a viewer changing one is ephemeral and never written back. | Tool | What it does | | |---|---|---| | [`set_parameter`](#set_parameter) | Set parameter | Destructive write | ## set_parameter `Destructive write` · `Reaches outside Vistazo` Define, update or remove a dashboard parameter, read in argument templates as {{ params.\ }}, or with `notebookId` a notebook's (rules on that field). `label` + `type` DEFINE it (re-defining a `key` rewrites it, options included); creating REQUIRES one default intent: `value`, `defaultEmpty: true` or `defaultRule` (sourced selects). `value` alone changes only the default; `remove: true` deletes it. A multi_select fills a hole with its values joined by a bare comma ("KEN,USA"; {{ params.\ | dump }} for a JSON array) and takes `minSelections` / `maxSelections`; its default must fit. Date values may be relative: `today` or `now`, then up to three steps applied left to right — an offset ±N with unit d|w|mo|y (default d) or a round-down /d|/w|/mo|/y — e.g. today-30, today-1mo/mo, now/y-1d (Dec 31 last year). Options: static `options` or a `source` widget's rows. STATIC OPTIONS ARE NOT VALIDATED: verify ids first (call_tool on the source's lookup tool, or explore_dashboard `params`). Requires edit access. ### `value` The parameter's DEFAULT — the only persisted parameter state: refreshes render with it and every viewer lands on it (a viewer's own filter changes are never stored). Alone it changes only the default and keeps the definition; with `label` and `type` it is the new definition's default. A new default RE-BASELINES the dashboard for everyone; to try a value without publishing, pass it to explore_dashboard's `params`. A notebook's default is what run_notebook, schedules and the public view run with. Shape by type: text→string, integer/decimal→number, boolean→true|false|null (null = don't filter), date→ISO string or relative expression, datetime→ISO datetime, date_range→{start,end} (each endpoint ISO or relative), select→one of its option VALUES exactly as stored (get_dashboard lists them; not the display label), multi_select→an array of them. Prefer a relative date ("today-90", "today-1mo/mo") for a rolling default so it moves with the clock. ### `remove` true removes the parameter `key`. On a dashboard, widget templates referencing it render it empty thereafter, including the source of a sourced parameter that reads this key, and manage_version `restore` (kind dashboard) brings it back. On a notebook, a cell reading it raises until it is defined again, and manage_version `restore` (kind notebook) brings it back with the cells. ### `notebookId` The notebook to define, update or remove the parameter on, in place of `dashboardId` (pass exactly one). The key is a Python identifier, read as vistazo.param("\") in python and {{ params.\ }} in a data cell's args or in prose. Options are static `options` only, never `source` or `defaultRule`; at most 20 per notebook. The reply's `referencedBy` lists the cells reading the key (on remove, `warnings` names the ones that will now raise). A new default runs nothing: outputs stay as they ran until the next run_notebook or schedule, and readers try their own values on the page without saving them.