# Parameters

## What is a notebook parameter?

A parameter is a named input that a notebook's cells read, such as a country, a date window or a
threshold. It works like a dashboard filter. Each parameter has a default, and the defaults are what
everyone sees when they open the notebook. Schedules, `run_notebook` and the public view always run
with the defaults.

Anyone who can open the notebook, other than a guest, can try their own values in the
**Parameters** tab. Those runs are yours alone, and nothing about them is saved.

## How do you add a parameter?

Ask the built-in assistant in the notebook's panel, or your agent, to add one:

> Add a country parameter with the G7 countries, defaulting to the US, and make the cells read it.

It calls `set_parameter` with the notebook's id. Adding, changing a default and removing a parameter
all take **Editor** on the notebook. There is no form for it in the notebook itself.

- A parameter has a key, a label, a type and a default. The types are a dashboard parameter's
  ([types](/docs/dashboards/parameters#what-types-can-a-parameter-be)).
- The key is what cells use. It holds letters, digits and underscores, and doesn't start with a
  digit, so `country` or `min_rate`.
- A `select` or `multi_select` takes a fixed list of options, up to 500, or 200 for a
  `multi_select`. A notebook parameter can't fetch its options from a data source.
- A date default can be relative, such as `today-30`, so it moves with the calendar
  ([relative dates](/docs/dashboards/parameters#how-do-relative-dates-work)).
- Changing a default runs nothing. The outputs stay as they last ran until the next run or schedule.

When you remove a parameter, the reply names the cells that read it. Those cells fail when they next
run, until you add it back or change them.

## How do cells read a parameter?

Each kind of cell reads it its own way, and none of them pastes the value into your code.

- **Python** calls `vistazo.param('country')`, without `await`. It returns the value in its own
  type, a list for a multi-select and a start and end for a date range. Asking for a key the notebook
  doesn't define raises an error that lists the keys it does.
- **Data** writes `{{ params.country }}` in an argument. A hole can be the whole argument or part of
  longer text, such as `Sales in {{ params.country }}`. `{{ dates.today-30 }}` fills in a date the
  same way.
- **Text** writes `{{ params.country }}` in prose, and the page shows the value there. A pick list
  shows its option's label. The value always reads as plain text, never as a link or formatting.

A text cell shows the values the last run used, or the defaults when nothing has run. While you
edit the text, the holes stay as you wrote them.

## How do you try your own values?

Open the **Parameters** tab in the notebook's side panel, beside the built-in assistant. On a phone
it is in the bar at the bottom. The tab appears once the notebook has a parameter.

1. Change one or more values. The revert button beside a row puts its default back.
2. Press **Apply**. The notebook runs with your values, and **Stop** halts it.
3. Read the results. The page says **Showing your values** while they are on screen.
4. Press **Reset** to go back to the published run.

The first **Apply** runs every cell. A later one runs again from the first cell your change affects,
and keeps the cells above it. Hovering over an output shows the values it ran with. A cell whose
output came from other values than the ones in effect is marked **outdated**.

A link to the notebook can carry values of its own. Opening it fills in the form, and nothing runs
until you press **Apply**, since a run uses your compute.

## What happens to a run with your values?

It runs in your own kernel, with your own connections. When a data cell reads a source you haven't
connected, the page asks you to connect it before anything runs. A run never borrows anyone else's
connection. It uses your compute, as any run does ([Usage](/docs/billing/usage)).

Nothing about it is saved. Nobody else sees your values or their outputs, and neither do the
built-in assistant, your agent or the public view. Reloading the page shows the published run again.
Your saved variables from your own runs of the notebook are kept, and come back after **Reset**.

A viewer runs the notebook only through **Apply**, and can't run single cells or change the code. An
editor who presses **Run** on a cell while their values are showing runs it with those values.
Guests and people reading the public view see the published run, with no **Parameters** tab.

## What else carries parameters?

- **Duplicate** copies a notebook's parameters along with its cells.
- A Jupyter file carries no parameters either way. **Download** writes the `vistazo.param` calls as
  code. **Import .ipynb** defines none, and the note at the top names each cell that reads one, so you
  can add them.

## What limits a run with your values?

| | Limit |
|---|---|
| Parameters in one notebook | 20 |
| Your values for one run | 16 KB in total |
| One cell's output with your values | 4 MB. A longer table keeps the rows that fit, and a larger chart shows a message instead |
| Everything else | The same as any run. See [Running](/docs/notebooks/running#what-limits-a-notebook) |