* Consolidated four add mappings tasks into one
* Moved images from tasks to types of value mappings section
* Removed edit value mappings section
* Moved sentence about reordering mappings to intro section
* Docs: Add to and update Configure value mappings page (#80104)
* Added to do notes
* Updated intro text and screenshot
* More intro edits
* Updated Types of value mappings section
Replaced bullet list items with headings
Updated text and screenshots of section
* Updated Add a value mapping task
* Recast sentence to remove passive voice
* Replaced local image files with images on admin
description: Configure value mappings to change the visual treatment of data in your visualizations
description: Configure value mappings to change how data appears in your visualizations
weight: 90
---
# Configure value mappings
In addition to field overrides, value mapping is a technique that you can use to change the visual treatment of data that appears in a visualization.
In addition to field overrides, value mapping is a technique you can use to change how data appears in a visualization.
Values mapped using value mappings bypass the unit formatting. This means that a text value mapped to a numerical value is not formatted using the configured unit.
For example, the mapping applied in the following image causes the visualization to display the text `Cold`, `Good`, and `Hot` in blue, green, and red for ranges of temperatures rather than actual temperature values. Using value mappings this way can make data faster and easier to understand and interpret.
If value mappings are present in a panel, then Grafana displays a summary in the side pane of the panel editor.
Value mappings bypass unit formatting set in the **Standard options** section of panel editor, like color or number of decimal places displayed. When value mappings are present in a panel, Grafana displays a summary of them in the **Value mappings** section of the editor panel.
## Types of value mappings
{{% admonition type="note" %}}
The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap.
{{% /admonition %}}
Grafana supports the following value mapping types:
Grafana supports the following value mappings:
### Value
- **Value:** Maps text values to a color or different display text. For example, you can configure a value mapping so that all instances of the value `10` appear as **Perfection!** rather than the number.
- **Range:** Maps numerical ranges to a display text and color. For example, if a value is within a certain range, you can configure a range value mapping to display **Low** or **High** rather than the number.
- **Regex:** Maps regular expressions to replacement text and a color. For example, if a value is `www.example.com`, you can configure a regex value mapping so that Grafana displays **www** and truncates the domain.
- **Special** Maps special values like `Null`, `NaN` (not a number), and boolean values like `true` and `false` to a display text and color. For example, you can configure a special value mapping so that `null` values appear as **N/A**.
A **Value** mapping maps specific values to text and a color. For example, you can configure a mapping so that all instances of the value `10` appear as **Perfection!** rather than the number. Use **Value** mapping when you want to format a single value.
You can also use the dots on the left to drag and reorder value mappings in the list.
### Range
A **Range** mapping maps numerical ranges to text and a color. For example, if a value is within a certain range, you can configure a range value mapping to display **Low** or **High** rather than the number. Use **Range** mapping when you want to format multiple, continuous values.
### Regex
A **Regex** mapping maps regular expressions to text and a color. For example, if a value is `www.example.com`, you can configure a regular expression value mapping so that Grafana displays **www** and truncates the domain. Use the **Regex** mapping when you want to format the text and color of a regular expression value.
### Special
A **Special** mapping maps special values like `Null`, `NaN` (not a number), and boolean values like `true` and `false` to text and color. For example, you can configure a special value mapping so that `null` values appear as **N/A**. Use the **Special** mapping when you want to format uncommon, boolean, or empty values.
## Examples
@ -51,19 +60,19 @@ Refer to the following examples to learn more about value mapping.
### Time series example
The following image shows a time series visualization with value mappings. Value mapping colors are not applied to this visualization, but the display text is shown on the axis.
The following image shows a time series visualization with value mappings. Value mapping colors aren't applied to this visualization, but the display text is shown on the axis.
### Stat example
The following image shows a Stat visualization with value mappings and text colors applied. You can hide the sparkline so it doesn't interfere with the values.
The following image shows a stat visualization with value mappings and text colors applied. You can hide the sparkline so it doesn't interfere with the values.
### Bar gauge example
The following image shows a bar gauge visualization with value mappings. The value mapping colors are applied to the text, but not to the gauges.
The following image shows a bar gauge visualization with value mappings. Note that the value mapping colors are applied to the text, but not to the gauges.
@ -73,64 +82,22 @@ The following image shows a table visualization with value mappings. If you want
Map a value when you want to format a single value.
1. Open a panel for which you want to map a value.
1. In panel display options, locate the **Value mappings** section and click **Add value mappings**.
1. Click **Add a new mapping** and then select **Value**.
1. Enter the value for Grafana to match.
1. (Optional) Enter display text.
1. (Optional) Set the color.
1. Click **Update** to save the value mapping.
## Add a value mapping
## Map a range
1. Navigate to the panel you want to update.
1. Hover over any part of the panel you want to work on to display the menu on the top right corner.
1. Click the menu and select **Edit**.
1. Scroll to the **Value mappings** section and expand it.
1. Click **Add value mappings**.
1. Click **Add a new mapping** and then select one of the following:
Map a range of values when you want to format multiple, continuous values.
- **Value** - Enter a single value to match.
- **Range** - Enter the beginning and ending values of a range to match.
- **Regex** - Enter a regular expression pattern to match.
- **Special** - Select a special value to match.
1. Edit the panel for which you want to map a range of values.
1. In panel display options, in the **Value mappings** section, click **Add value mappings**.
1. Click **Add a new mapping** and then select **Range**.
1. Enter the beginning and ending values in the range for Grafana to match.
1. (Optional) Enter display text.
1. (Optional) Set the color.
1. Click **Update** to save the value mapping.
## Map a regular expression
Map a regular expression when you want to format the text and color of a regular expression value.
1. Edit the panel for which you want to map a regular expression.
1. In the **Value mappings** section of the panel display options, click **Add value mappings**.
1. Click **Add a new mapping** and then select **Regex**.
1. Enter the regular expression pattern for Grafana to match.
1. (Optional) Enter display text.
1. (Optional) Set the color.
1. Click **Update** to save the value mapping.
## Map a special value
Map a special value when you want to format uncommon, boolean, or empty values.
1. Edit the panel for which you want to map a special value.
1. In panel display options, locate the **Value mappings** section and click **Add value mappings**.
1. Click **Add a new mapping** and then select **Special**.
1. Select the special value for Grafana to match.
1. (Optional) Enter display text.
1. (Optional) Set the color.
1. Click **Update** to save the value mapping.
## Edit a value mapping
You can edit a value mapping at any time.
1. Edit the panel that contains the value mapping you want to edit.
1. In the panel display options, in the **Value mappings** section, click **Edit value mappings**.
1. Make the changes and click **Update**.
After you've added a mapping, the **Edit value mappings** button replaces the **Add value mappings** button. Click the edit button to add or update mappings.
Isabel
1 year ago
committed by