Parameterised fields

Parameterised fields are a type of dynamic field. Unlike source data fields, which surface data already stored in your connected data source, parameterised fields are user-created and use configurable parameters to control how a custom field calculation behaves. Instead of creating multiple fields with hardcoded values, a single parameterised field can be reused across different reporting scenarios by changing its parameter selections.

This article explains what parameterised fields are, how they work, and how to create and configure them.

Parameterised fields are a type of custom field built using BRQL. If you're new to either, see Create a custom field and BRQL for custom fields before continuing.

To understand how parameterised fields fit alongside other dynamic field types, see Understand dynamic fields.

To see a practical walkthrough, see Orders containing a specific product.

To learn how to add a parameterised field to a report or update its selections, see Add and update dynamic fields in a report.

In this article

• When to use a parameterised field
• How parameterised fields work
• Create a parameterised field
• Use parameters in field expressions
• Show parameter values in field names
• Best practices
• Need more support?

When to use a parameterised field

Parameterised fields are useful when the same formula logic applies across multiple reporting scenarios, but one or more values need to change between uses.

Use a parameterised field when you want to:

• Reuse the same calculation with different inputs without creating duplicate fields
• Let report users select a value, such as a product, channel, or date, that controls what the field returns
• Make a report configurable without editing the underlying field expression each time

Example: Instead of creating separate fields for Image 200 pixels and Image 100 pixels, a single parameterised field can include a @Pixels parameter that controls how many pixels the image renders. The report user inputs their preference when the field is added.

How parameterised fields work

When a parameterised field is added to a report, a popup window opens automatically so parameter values can be selected before the field is applied. The same happens when a parameterised field is added as a filter.

If a parameter value is referenced in the field's display name, it appears using the @ParameterName     notation — but this is optional and not always present.

Parameter values are passed into the field expression at runtime, meaning the field evaluates using the selected values each time the report loads. This means the report does not need to be rebuilt each time — the same field adjusts its output based on what you selected when you added it. After they are added, parameter values persist in the report.

Create a parameterised field

Parameterised fields are created the same way as other custom fields, with parameters added during configuration.

1. Open a report
2. Select Edit
3. Select + Create new, then select Create Dimension or Create Measure
4. Select the Root table where the field should be created
5. Enter a Display name
6. Review or edit the auto-populated BRQL name
7. Select + Add parameter

For each parameter, configure the following settings:

Display name

The label shown to the report user when they are prompted to select a value. Use a clear, descriptive name that explains what the parameter controls.

Learn about injecting parameters in the display name in Show parameter values in field names.

Examples: Product, Channel, Year

BRQL name

The name used to reference the parameter in the field expression. This is auto-populated from the display name but can be edited. The BRQL name must not contain spaces or special characters.

When referencing parameters in expressions use the syntax [@BRQLName]    . Refer to the Use parameters in field expressions section for more information.

Example: A display name of Include shipping generates the BRQL name IncludeShipping    , referenced in custom field expressions as [@IncludeShipping]    .

Data type

The type of value the parameter accepts. Choose the data type that matches the values you intend to pass into the expression.

Value(s)

Controls whether the parameter accepts a single value or multiple values at once.

• Single value: The report user selects one value. Use this when the expression works with one input at a time.
• Multiple values: The report user can select more than one value. The custom field expression must use IN (SELECT VALUE FROM [@ParameterName])     syntax to handle multiple inputs correctly.

Required

Controls whether a value must be selected before the field can be added to the report.

• Yes: The field cannot be added without a parameter value. Use this when the expression cannot return a meaningful result without an input.
• No: The parameter is optional. Use this when a sensible default or fallback is already built into the custom field expression.

A parameter can be set to Required and still have a default value. The default is pre-filled, but the user must confirm or change it before the field can be applied.

Default value

Sets the value that is pre-selected when the parameter editor opens. This is optional but recommended for parameters that have a clear common-case value.

Default values can be defined in two ways:

Static default: A fixed value entered directly.

Example: TRUE     for a Yes/no parameter that should default to on.

Query-driven default: A BRQL query that returns the default value dynamically. This is useful when the default should reflect current data rather than a hardcoded value.

Example: The following query selects all available channels as the default, so the parameter starts with every channel included:

SELECT DISTINCT [o.Channel]
FROM [$Orders o]
ORDER BY 1

Input mode

Controls how the report user provides a value for the parameter.

Drop-down list values expression

When the input mode includes a drop-down list, you must provide the values that appear in it. These are defined using a BRQL expression.

The query runs independently from the report and returns the list of selectable values.

Single-column query (value only):

SELECT DISTINCT [p.Title]
FROM [$Products p]

The value returned becomes both the stored parameter value and the label shown in the drop-down.

Two-column query (stored value + display label):

SELECT [p.Id], [p.Title]
FROM [$Products p]
ORDER BY [p.Title]

When two columns are returned:

• The first column becomes the stored parameter value passed into the expression
• The second column becomes the label shown to the report user in the drop-down

This pattern is useful when you want the drop-down to display readable names while passing a more stable value — such as an ID — into the expression.

Example: A drop-down that displays product titles but stores product IDs. If a product title is later renamed, the field expression continues to work correctly because it uses the ID, not the title.

8. Select + Add parameter again if the field requires more than one parameter, and repeat the configuration steps above
9. Enter the field Expression, referencing each parameter using [@ParameterName]     syntax (see Use parameters in field expressions below)
10. Select OK

Use parameters in field expressions

If you're writing the field expression yourself, use the parameter's BRQL name to reference it in the expression. If you're editing an existing parameterised field and parameters are already defined, you may not need this section.

Parameters are referenced in the field expression using the parameter's BRQL name (the identifier you set during configuration), wrapped in [@     and ]    .

Syntax: [@BRQLName]   

Example:

(
    SELECT SUMZ([i.Quantity]) 
    FROM [$.AgreementLines i] 
    WHERE DATEDIFF(DAY,[i.Date.Day],TODAY()) <= [@NumberOfDays]
)

In this expression, [@NumberOfDays]     is replaced at runtime by the value entered for the Number of days parameter.

Multiple parameters

A single field can contain more than one parameter. Each parameter is referenced independently in the expression using its own BRQL name.

Example: A field with separate parameters for the product type and date variables:

MAXB(IS_TRUE([$.ProductType] = [@ProductType] AND [$.Order.ProcessedAt.Day] < [@Date.Day])) OVER (PARTITION BY [$.Order.CustomerId])

Multiple-values parameters

When a parameter is configured to accept multiple values, use IN (SELECT VALUE FROM [@ParameterName])     in the expression to evaluate against all selected values.

The following expression returns TRUE for any order that contains at least one of the selected products:

MAXB(
  IS_TRUE(
    [$.HistoricalProduct.Id] IN (
      SELECT VALUE FROM [@ProductIds]
    )
  )
  OVER (PARTITION BY [$.OrderId])
)

Show parameter values in field names

Parameter values can be injected into a field's display name so the name updates automatically based on the current parameter selection. This helps report users understand what a field is showing without needing to open the field editor.

Syntax: {@BRQLName}   

Example:

A field named Revenue for {@IncludedChannels}     displays as Revenue for Online Store when that channel is selected.

When more than three values are selected, the display name shows a count instead of listing all values.

Example: Revenue for 4 selected

Format injected values

Date and numeric values can be formatted within the display name using the following syntax:

{@BRQLName:format}

For a full list of supported format patterns, see Google Sheets number format patterns.

Formatting applied to injected parameter values is retained when the report is exported.

Override dynamic display names

Dynamic display names can be overridden at the report level using the title override option in the field editor. This is useful when a fixed label is preferred over a dynamic one for a specific report.

Best practices

Use stable identifiers

When building drop-down parameters, use IDs, SKUs, or other stable values as the stored parameter value rather than display names that may be edited over time. Pair them with readable display labels using a two-column drop-down query so users still see familiar names in the dropdown.

This prevents the field from breaking if a product title, collection, or other label is updated.

Use readable display labels

Always provide user-friendly display labels alongside stable underlying values. A drop-down that shows Blue T-Shirt — Large is easier to use than one that shows SKU-10042    , even if the SKU is what gets stored.

Reduce duplicate fields

When the same logic is needed with different values, use a parameterised field rather than creating separate fields for each variation. This keeps the logic in one place, reduces maintenance, and keeps your custom fields list manageable.

Use defaults thoughtfully

Default values reduce friction when adding fields to a report, particularly for parameters that have a common-case value. For multiple-value parameters, a query-driven default that returns all available values is useful when the expected workflow is to start with everything included and narrow down from there.