Parameters

Parameters (params) are an action’s inputs. Params are declared in the Params section of the Definition tab and used in SQL. The run form, the inputs of a schedule and the types suggested in views are all generated from this list.

Syntax

Write a param in SQL with double curly braces:

SELECT id, email, status
FROM users
WHERE status = {{status}}
  AND created_at >= {{from}}

• A param name starts with a letter or _, contains only letters, digits and _, and is at most 64 characters. Spaces inside the braces are allowed: {{ status }}.
• A param can be used several times in the same statement.
• An action can have up to 50 params.

Values are always sent separately from the SQL

Param values are never concatenated into the statement. The server sends the SQL and the values to the database separately, so a value such as ' or 1=1-- is treated as an ordinary string. Do not write your own bind markers ($1, ?) in SQL; declare a param and use {{name}} instead.

Declaration check against the SQL

On Publish, the server compares the SQL with the param list and blocks publishing in these cases:

• The SQL uses a {{param}} that is not declared. The editor warns beforehand with “The SQL uses undeclared params: …” and an Add N params from the SQL button that adds the missing params.
• A param is declared but not used in the SQL.

For fixes, see Troubleshooting.

Parameter types

Type	Input on the form	Notes
string	Text box
number	Number box	Decimal numbers.
integer	Number box	Whole numbers.
boolean	Yes / No
date	Date picker
datetime	Date and time picker	Time is entered in the browser’s time zone; the form shows the time zone in use.
enum	Drop-down	Requires a list of values, or a list taken from another action.

Param options

Option	Meaning
Name	The name used inside {{...}}.
Label	The text shown on the run form.
Param type	One of the seven types above.
required	If left empty, the form shows an error and does not send the run.
Enum values	enum only: comma-separated values, no duplicates (up to 200 values).
Description (under Advanced)	Shown under the input on the run form.
Default value (under Advanced)	Pre-filled on the run form; must be valid for the param’s type.

Enums for dynamic column or table names

Normally, a param can only appear in a value position (after =, inside IN (...), in LIMIT…). When a column or table name depends on the user’s choice (for example a sort column), the param must be an enum with a fixed list of values:

SELECT id, email, created_at
FROM users
ORDER BY {{sort_by}}

With sort_by of type enum and values id, email, created_at:

• Publishing is accepted because every possible value is known in advance. On publish, the interface lists the params that are interpolated as identifiers.
• At run time, a value outside the list is rejected before it reaches the database.
• A param of any other type (for example string) in a column or table name position blocks publishing.
• An enum that takes its list from another action cannot be used in this position, because that list can change after publishing.

Option lists from another action (master data)

An enum param can take its options from a published action, for example a list of stores or categories.

1. On the enum param, set Values from to Another action.
2. Select the source action in Pick a published source action.
3. Choose the Value column (the value sent when running) and the Label column (the text shown in the list).

Conditions:

• The source action runs without params, so it must not have required params.
• The person running the action needs permission to run the source action. Otherwise, the picker shows “You don’t have access to this list — contact a project admin.”
• The source action must apply to the selected environment, and its data source must have a connection in that environment. Otherwise, the picker shows “This list isn’t available in the selected environment.”
• An action that provides an option list for another action’s param cannot be deleted until that link is removed.

Variables, secrets and built-in values

In addition to params entered by users, SQL can read values filled in by the server. These values start with $ and do not appear on the form:

Syntax	Value
{{$var.KEY}}	Variable KEY of the environment being run.
{{$secret.KEY}}	Secret KEY of the environment being run. Only decrypted on the execution server, right before the run.
{{$user.id}}, {{$user.email}}	The person running the action.
{{$env.id}}, {{$env.slug}}, {{$env.isProduction}}	The environment being run.

SELECT *
FROM tickets
WHERE assignee_email = {{$user.email}}
  AND region = {{$var.DEFAULT_REGION}}

• These values always sit in value positions and are sent separately from the SQL, like regular params; a secret is never concatenated into the statement.
• $user only has id and email; $env only has id, slug and isProduction. Any other field blocks publishing.
• Variable and secret keys may only contain UPPERCASE letters, digits and underscores, and cannot start with a digit (for example SUPPORT_EMAIL).
• JS actions can read variables but do not receive secrets. A secret is only used by the SQL action that needs it.

How to set variables and secrets: Variables and secrets.

Params for background, bulk and scheduled runs

• Bulk run (SQL actions in Writes data mode only): each element of the JSON array is one parameter set, checked with the same rules as the form (up to 10,000 elements). See Run actions.
• Schedules: no one fills in a form, so params are fixed when the schedule is created. See Jobs and schedules.
• Run history stores the params that were entered. Values of params whose names contain password, token, secret, api_key… are hidden.