Parameters

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.

Destructive write · Reaches outside Vistazo

Define, update or remove a dashboard parameter, read in argument templates as {{ params.<key> }}, 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.<key> | 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("<key>") in python and {{ params.<key> }} 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.