# Parameters

## What is a parameter?

A parameter is a named value set once on a dashboard and read by every widget that should follow it.
A country picker, a date range and a metric toggle are all parameters. Readers meet them in the
dashboard's **Filters** panel.

You add a parameter by asking the built-in assistant or your agent:

> Add a country filter with the G7 countries, defaulting to the US, and make every chart follow it.

## What types can a parameter be?

| Type | Takes |
|---|---|
| `text` | A string |
| `integer`, `decimal` | A number |
| `boolean` | True, false, or unset. Unset applies no filter |
| `select` | One choice |
| `multi_select` | Any number of choices |
| `date`, `datetime` | A point in time |
| `date_range` | A start and an end |

## Where does a picker get its options?

A `select` or `multi_select` gets its options in one of two ways. Static options are a fixed list
written into the parameter, which suits a small set that rarely changes. Sourced options are fetched
from a data source when the dashboard refreshes, which suits a long list or one that follows the
data.

Vistazo does not check static options against any data source. A wrong country code or ticker shows
up later as a failed refresh. Have your agent check the values against the source's own lookup tool
first.

A sourced list holds up to 500 options, or 200 for a `multi_select`. Past that, the filter takes
typed text instead.

## How does one filter narrow another?

A sourced filter can narrow to the value of another filter. A City filter fetched for the chosen
Country lists only that country's cities. Ask your agent to build one, since it wires the City list
to read the Country value.

When you change the parent and press **Apply**, Vistazo fetches the child's list again, along with
the charts that read either filter. Nothing else refreshes. A choice the new list no longer holds is
dropped, and a line under the filter says so. A chain goes at most three sourced filters deep.

## How do relative dates work?

A date parameter can hold a relative expression instead of a fixed date. Vistazo works it out in UTC
at every refresh, so "the last 90 days" still means the last 90 days next month.

| Expression | Resolves to |
|---|---|
| `today` or `now` | Today's date |
| `today-90` | 90 days ago |
| `today-2w` | Two weeks ago |
| `today-1mo/mo` | The first day of last month |
| `now/y-1d` | December 31 of last year |

An offset takes a unit of `d`, `w`, `mo` or `y`, and days when the unit is left off. A trailing
`/unit` rounds down to the start of that unit. Weeks start on Monday. `today` and `now` both resolve
to a date with no time of day, so there is no way to say "this hour".

Relative expressions work on `date` and `date_range` only. A `datetime` default takes a fixed ISO
date and time, and `integer` and `decimal` take a plain number.

## What does the default value do?

A parameter's default is the only value Vistazo saves. Scheduled refreshes draw every widget at the
defaults, and every reader opens the dashboard at them.

A filter you change while reading gives you your own view of the dashboard
([Dashboards](/docs/dashboards/overview#what-does-each-reader-see)). It is never written back for anyone else. The
dashboard keeps publishing its defaults, and other readers see no change. Filtering runs on your own
connections and costs nothing from anyone's allowance.

Changing a default is an edit to the dashboard. The next refresh publishes at the new value, and
every reader lands there.

> [!TIP]
> To try a value without changing the default, ask the built-in assistant or your agent to explore
> the dashboard with that value. It runs the charts and shows you the result without publishing
> anything.

## How do you share a filtered view?

Pressing **Apply** puts the filter values in the address bar. Bookmark it, or send it to a colleague.
Opening the link runs the dashboard at those values as whoever opened it, on their own connections.

```
/dashboards/abc123?p.country=US,DE&p.window=2026-01-01..2026-03-31&p.active=true
```

The link holds every filter in the panel, including the ones still at their default. It keeps
meaning the same thing after the owner changes a default. A rolling value, such as the last 30 days,
is written as the rolling expression and keeps rolling. Relative dates in a link resolve in UTC.

The values are plain text and can be edited by hand. Revert one filter and press **Apply** to take
it out of the link, or press **Reset** to clear them all.

A value that no longer applies is dropped, and that filter opens at its default. This happens when a
filter was removed or an option no longer exists. A reader who cannot filter opens the link at the
defaults.

The [public view](/docs/sharing/overview) has no filters and ignores filter values in the address.
Everyone reading it sees the defaults. An embed on your own website can show other values, which
your server signs into the embed's token. See [Embeds](/docs/sharing/embeds).

## What order do filters appear in?

A parameter can carry an explicit position in the **Filters** panel. Parameters without one come after
those that have one, sorted by label. Alphabetical order reverses some natural pairs, so an unordered
Start and End lists End first. Ask for an order that reads coarse before fine and start before end.