> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard Variables

Variables allow you to dynamically apply filters to charts. The values of variables can be constant or can be edited by users when they are looking at a dashboard.

When a user edits the value of a variable in the dashboard, it will not be saved. It will only be applied to the current session.
This allows you to build generic dashboards, for example: a postgres dashboard showing performance metrics for different a particular database. Then users can select the database they're interested in.

## Variable Components

A variable is made up of these components:

* Name - The name of the variable which will be referenced when applying the filter.
* Possible Values - Suggested values for the variable. This is all the values of a particular tag for traces or metrics.
* Default Value - The default value of the variable. This is the value that will be applied when the variable is not edited by the user.
  If the value is `*` then it is for all values of the key.
* Overridable - Whether a user can edit the value of the variable inside the dashboard for their session.

An example variable definition is below:

<img src="https://mintcdn.com/metoro/ZLKLeijcjMYiIwum/images/example_variable.png?fit=max&auto=format&n=ZLKLeijcjMYiIwum&q=85&s=3b880d8ebfedfa8062aaa0ca7ebb09ea" alt="Variable configuration form showing name, possible values from trace data, and default value fields" width="2046" height="874" data-path="images/example_variable.png" />

This variable has a name of `serviceName` and a default value of `*` which means all service names. The possible values are the unique values of the serviceName tag for traces.

## Creating Variables

You can create a variable by clicking the variable icon on any group widget in edit mode.

<img src="https://mintcdn.com/metoro/JQ7xkDXZJ0ErZc8O/images/variables_icon.png?fit=max&auto=format&n=JQ7xkDXZJ0ErZc8O&q=85&s=f4b580cfbe5a348a2acbfaf17bff5339" alt="Dashboard toolbar with variables (x) icon highlighted in red box" width="552" height="184" data-path="images/variables_icon.png" />

After a variable is created, you will see it in the header of the group widget.

<img src="https://mintcdn.com/metoro/JQ7xkDXZJ0ErZc8O/images/variable_header.png?fit=max&auto=format&n=JQ7xkDXZJ0ErZc8O&q=85&s=871cd3ea551628801b59455c4b355f4d" alt="Group widget header displaying $serviceName variable pill with asterisk default value" width="684" height="172" data-path="images/variable_header.png" />

## Using Variables

After you have created a variable you can use it in the filters of any chart that is nested below that group.

In the chart editor you can set any filter equal to the variable value.

<img src="https://mintcdn.com/metoro/JQ7xkDXZJ0ErZc8O/images/variable_usage.png?fit=max&auto=format&n=JQ7xkDXZJ0ErZc8O&q=85&s=b6c705b4561b72e3da213eabbd5bb1de" alt="Chart Builder showing $serviceName variable used in the filter where clause" width="4134" height="2146" data-path="images/variable_usage.png" />

After using a variable in the chart. Change the value of the variable by clicking the variable in the widget and selecting (or typing) the new value.
