Create Numeric Parameters

Numeric parameters let analytics engineers define governed numeric values in the semantic layer and use them in metric definitions. Dashboard users can then change these values at runtime to explore different business assumptions without creating duplicate metrics.

For example, you can define a Top N parameter once, use it in a ranking metric, and let dashboard users switch between Top 5, Top 10, or Top 20 results directly from the dashboard.

The basic workflow is:

1. Create a numeric parameter.
2. Use the parameter in a metric with the {parameter/parameter_id} syntax.
3. Use the parameterized metric in a visualization.
4. Add the visualization to a dashboard, where users can change the parameter value at runtime.

Create a Numeric Parameter

You can create numeric parameters in the Analytics Catalog using a YAML definition.

Steps:

1. In your Catalog click Create and select Parameter.

   
   

2. In the Create parameter dialog, enter the parameter YAML definition and click Create.

   
   

Example Definition

id: top-n
title: Top N
description: Controls the Top-N window in ranking-style metrics.
definition:
  type: NUMBER
  defaultValue: 10
  constraints:
    min: 0
    max: 50
tags:
  - Favorites

The defaultValue is used whenever no runtime override is available. This ensures that metrics referencing the parameter can always be evaluated.

Use Parameter in Metric

Use the {parameter/parameter_id} syntax to reference a parameter in a MAQL metric definition.

Example:

id: total_sales_top_n_products
title: "Total Sales (Top N Products)"
maql: |
  SELECT {metric/total_sales}
  WHERE TOP({parameter/top-n}) IN (
      SELECT {metric/total_sales}
      BY {label/product_name}
      ALL OTHER
  )  

At execution time, GoodData replaces the parameter reference with the resolved numeric value. If no dashboard override is active, the metric uses the parameter default.

For example, if top-n has a default value of 10, the metric is evaluated as:

SELECT {metric/total_sales}
WHERE TOP(10) IN (
    SELECT {metric/total_sales}
    BY {label/product_name}
    ALL OTHER
)

View Parameter in Visualizations

After you create a metric that references a parameter, you can use it in visualizations like any other metric.

In Analytical Designer, add the parameterized metric to your visualization. The visualization is computed using the parameter value. If no runtime override is set, GoodData uses the parameter defaultValue.

For example, if the top-n parameter has defaultValue: 10, a visualization using the Total Sales (Top N Products) metric shows the top 10 products.

You can use parameterized metrics for scenarios such as:

• Top N rankings
• discount or margin assumptions
• growth-rate assumptions
• target or threshold comparisons
• numeric limits used in metric logic

View Parameter in Dashboards

When you add a visualization with a parameterized metric to a dashboard, the visualization works even if no parameter filter is added. In that case, the parameter resolves to its default value.

To let dashboard users change the parameter value at runtime, add the parameter to the dashboard as a filter.

When a user changes the parameter filter value, all dashboard visualizations that use metrics referencing that parameter are recalculated automatically. The dashboard updates without a page reload.

For example, if the dashboard includes the Top N parameter filter, users can change the value from 10 to 5. Any visualization using the Total Sales (Top N Products) metric then updates to show the top 5 products instead of the top 10.

Parameter filter values are preserved in the dashboard state, including saved views, share links, exports, alerts, and scheduled exports.

Limitations

The following are not supported yet:

• string, date, or enum parameters
• cascading or dependent parameters
• parameters that reference other parameters
• widget-level opt-out from dashboard-level parameter filter overrides
• conditional logic in metric templates
• parameter autocomplete in AI Assistant suggestions