Parameter

Referencing a parameter from a SQL block lets you generate SQL dynamically based on the parameter's value. Once you define a parameter, an input form appears at the top of the doc page or grid page.

A notebook's parameter values and run results are synced between users currently viewing it. To keep them independent per user, use Version or Report.

Key features

• Scope: notebook-wide / page-specific
• Types and data types
• Usage patterns in SQL
• Escaping and dynamic references
• Relative dates
• Generating dynamic options
• Specifying values from a URL

Creating and managing

1. Open Parameter at the top of the main area.
2. Select Add parameter, then choose a scope (Notebook-wide / Page-specific) and a type.
3. In a SQL block, type /param/ and select the parameter from the suggestions.

Once selected, the parameter reference is embedded in the SQL. It's displayed using the parameter's label.

For example, if a string parameter labeled param1 has val1 entered, the following SQL expands to 'val1' at run time.

-- Display in the SQL block
SELECT {{param1}}

-- Generated SQL
SELECT 'val1'

TIP

The {{param1}} above is a notation used for explanation. On screen, it's shown as a labeled reference chip.

For each parameter, you can do the following.

Operation	Description
Settings	Edits the input form settings for that type (see Types and data types).
Default value	Sets the value applied when resetting. For date types, you can also choose a relative date.
Reset to default value	Resets that parameter's current value to its default value.
Delete	Deletes the parameter definition. A parameter currently referenced from a SQL block or elsewhere can't be deleted.

In the parameter form, you can switch the display between In use and Show all.

Display	Description
In use	Shows only parameters referenced from the SQL and so on of the selected page.
Show all	Shows all defined parameters, regardless of whether they're referenced.

The Reset button resets all displayed parameters to their default values at once.

Parameter scope

A parameter has one of two scopes. Regardless of scope, the value is held per page.

Scope	Description
Notebook-wide	The parameter definition is shared across all pages in the notebook. The value is held on each page.
Page-specific	The parameter definition is only valid within the selected page. The value is also held only on the selected page.

Choose Notebook-wide for use in a SQL block referenced from multiple pages, and Page-specific for use only within that page. For example, when referencing a chart created on a doc page from a grid page, the SQL block that's the chart's data source should use a notebook-wide parameter.

Resolving values and default values

What's embedded in SQL is the parameter value held on each page.

• The default value is written into the parameter's value when you run Reset (or the individual Reset to default value).
• A parameter with no value set (an empty input form) expands using the zero value for its type.
• Because the zero value is a value valid for SQL of each type, SQL usually doesn't error out even when the value is unset. See Usage patterns in SQL for how to write an optional filter when the value is unset.

If you set a relative date as a date's default value, the date at that point in time is written into the current value each time you reset. See Relative dates for when this is applied.

Overriding parameters

When referencing a SQL block (chaining SQL blocks), you might want to decouple the parameter dependency inside the referenced SQL. For example, in cases like the following.

• Chaining SQL across pages, where each page should reference its own specific parameter.
• Different SQL derived from the same base SQL should reference different parameters.

Hovering over a SQL block reference (including a grid page's query result or chart) shows a popup where you can Override internal parameter references. The override methods are as follows.

Method	Description
Override with another parameter	Replaces the value with another parameter of the same type.
Override with a fixed value	Specifies a fixed value.
Don't override	Follows the expansion rules (for example, a notebook-wide parameter uses the referencing page's value).

For how to insert a reference and its expansion settings (Don't wrap in parentheses / Add alias at the end), see Referencing SQL blocks.

Syncing parameter values

In a notebook, parameter values and run results are synced between users. Use Version if you want to avoid concurrent edits.

In Version and interactive reports, parameter changes aren't synced between users; they only apply to the user who made the change. In these features, parameter changes are also synced to the URL (see Specifying values from a URL).

Syncing across report pages

Enabling Sync parameter changes across pages when publishing a report syncs changes to notebook-wide parameters across published pages. Page-specific parameters aren't linked. See Report for details.