diff --git a/docs/sources/panels/configure-value-mappings/index.md b/docs/sources/panels/configure-value-mappings/index.md new file mode 100644 index 00000000000..aa4f1f9e1ff --- /dev/null +++ b/docs/sources/panels/configure-value-mappings/index.md @@ -0,0 +1,128 @@ +--- +aliases: + - /docs/grafana/latest/panels/configure-value-mappings/ + - /docs/grafana/latest/panels/format-data/ + - /docs/grafana/latest/panels/value-mappings/ + - /docs/grafana/latest/panels/format-data/about-value-mapping/ + - /docs/grafana/latest/panels/format-data/edit-value-mapping/ + - /docs/grafana/latest/panels/format-data/map-a-range/ + - /docs/grafana/latest/panels/format-data/map-a-regular-expression/ + - /docs/grafana/latest/panels/format-data/map-a-special-value/ + - /docs/grafana/latest/panels/format-data/map-a-value/ +title: Configure value mappings +menuTitle: Configure value mappings +weight: 600 +--- + +# 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. + +Values mapped via value mappings bypass the unit formatting. This means that a text value mapped to a numerical value is not formatted using the configured unit. + +![Value mappings example](/static/img/docs/value-mappings/value-mappings-example-8-0.png) + +If value mappings are present in a panel, then Grafana displays a summary in the side pane of the panel editor. + +> **Note:** The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap. + +## Types of value mappings + +Grafana supports the following value mappings: + +- **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**. + +You can also use the dots on the left to drag and reorder value mappings in the list. + +## Examples + +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. + +![Value mappings time series example](/static/img/docs/value-mappings/value-mappings-summary-example-8-0.png) + +### 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. + +![Value mappings stat example](/static/img/docs/value-mappings/value-mappings-stat-example-8-0.png) + +### 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. + +![Value mappings bar gauge example](/static/img/docs/value-mappings/value-mappings-bar-gauge-example-8-0.png) + +### Table example + +The following image shows a table visualization with value mappings. If you want value mapping colors displayed on the table, then set the cell display mode to **Color text** or **Color background**. + +![Value mappings table example](/static/img/docs/value-mappings/value-mappings-table-example-8-0.png) + +## Map a value + +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. + +![Map a value](/static/img/docs/value-mappings/map-value-8-0.png) + +## Map a range + +Map a range of values when you want to format multiple, continuous values. + +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 range](/static/img/docs/value-mappings/map-range-8-0.png) + +## 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. + +![Map a value](/static/img/docs/value-mappings/map-special-value-8-0.png) + +## Edit a value mapping + +You can change 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**. diff --git a/docs/sources/panels/format-data/_index.md b/docs/sources/panels/format-data/_index.md deleted file mode 100644 index aa02d556864..00000000000 --- a/docs/sources/panels/format-data/_index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/ - - /docs/grafana/latest/panels/value-mappings/ - - /docs/sources/panels/format-data/ -title: Format data using value mapping -weight: 600 ---- - -# Format data using value mapping - -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. - -{{< section >}} diff --git a/docs/sources/panels/format-data/about-value-mapping.md b/docs/sources/panels/format-data/about-value-mapping.md deleted file mode 100644 index b249364e506..00000000000 --- a/docs/sources/panels/format-data/about-value-mapping.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/about-value-mapping/ - - /docs/sources/panels/format-data/about-value-mapping/ -title: About value mapping -weight: 10 ---- - -# About value mapping - -Value mapping allows you to replace values or ranges in your visualizations with words or emojis. - -Values mapped via value mappings will skip the unit formatting. This means that a text value mapped to a numerical value will not be formatted using the configured unit. - -![Value mappings example](/static/img/docs/value-mappings/value-mappings-example-8-0.png) - -If value mappings are present in a panel, then Grafana displays a summary in the side pane of the panel editor. - -> **Note:** The new value mappings are not compatible with some visualizations, such as Graph (old), Text, and Heatmap. - -## Types of value mappings - -Grafana supports the following value mappings: - -- **Value** maps text values to a color or different display text. For example, if a value is `10`, I want Grafana to display **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, I want Grafana 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', I want Grafana to display just **www**, truncating 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, if Grafana encounters a `null`, I want Grafana to display **N/A**. - -You can also use the dots on the left as a "handle" to drag and reorder value mappings in the list. - -## Time series example - -Here's an example showing 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. - -![Value mappings time series example](/static/img/docs/value-mappings/value-mappings-summary-example-8-0.png) - -## Stat example - -Here's an example showing a Stat visualization with value mappings. You might want to hide the sparkline so it doesn't interfere with the values. Value mapping text colors are applied. - -![Value mappings stat example](/static/img/docs/value-mappings/value-mappings-stat-example-8-0.png) - -## Bar gauge example - -Here's an example showing a Bar gauge visualization with value mappings. The value mapping colors are applied to the text but not the gauges. - -![Value mappings bar gauge example](/static/img/docs/value-mappings/value-mappings-bar-gauge-example-8-0.png) - -## Table example - -Here's an example showing a Table visualization with value mappings. If you want value mapping colors displayed on the table, then set the cell display mode to **Color text** or **Color background**. - -![Value mappings table example](/static/img/docs/value-mappings/value-mappings-table-example-8-0.png) diff --git a/docs/sources/panels/format-data/edit-value-mapping.md b/docs/sources/panels/format-data/edit-value-mapping.md deleted file mode 100644 index 16ca9fc996f..00000000000 --- a/docs/sources/panels/format-data/edit-value-mapping.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/edit-value-mapping/ - - /docs/sources/panels/format-data/edit-value-mapping/ -title: Edit a value mapping -weight: 60 ---- - -# Edit a value mapping - -You can change a value mapping at any time. - -## Before you begin - -- Ensure you have an existing value mapping to edit. - -**To edit a value mapping**: - -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**. diff --git a/docs/sources/panels/format-data/map-a-range.md b/docs/sources/panels/format-data/map-a-range.md deleted file mode 100644 index bc86d1fbc6e..00000000000 --- a/docs/sources/panels/format-data/map-a-range.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/map-a-range/ - - /docs/sources/panels/format-data/map-a-range/ -title: Map a range -weight: 30 ---- - -# Map a range - -Map a range of values when you want to format multiple, continuous values. - -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 range](/static/img/docs/value-mappings/map-range-8-0.png) diff --git a/docs/sources/panels/format-data/map-a-regular-expression.md b/docs/sources/panels/format-data/map-a-regular-expression.md deleted file mode 100644 index 75879c7c91b..00000000000 --- a/docs/sources/panels/format-data/map-a-regular-expression.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/map-a-regular-expression/ - - /docs/sources/panels/format-data/map-a-regular-expression/ -title: Map a regular expression -weight: 40 ---- - -# 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. diff --git a/docs/sources/panels/format-data/map-a-special-value.md b/docs/sources/panels/format-data/map-a-special-value.md deleted file mode 100644 index b4a3005f1c8..00000000000 --- a/docs/sources/panels/format-data/map-a-special-value.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/map-a-special-value/ - - /docs/sources/panels/format-data/map-a-special-value/ -title: Map a special value -weight: 50 ---- - -# 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. Options include: - - Null - - NaN (Not a Number) - - Null + NaN - - True - - False - - Empty -1. (Optional) Enter display text. -1. (Optional) Set the color. -1. Click **Update** to save the value mapping. - -![Map a value](/static/img/docs/value-mappings/map-special-value-8-0.png) diff --git a/docs/sources/panels/format-data/map-a-value.md b/docs/sources/panels/format-data/map-a-value.md deleted file mode 100644 index 02e39594fe8..00000000000 --- a/docs/sources/panels/format-data/map-a-value.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -aliases: - - /docs/grafana/latest/panels/format-data/map-a-value/ - - /docs/sources/panels/format-data/map-a-value/ -title: Map a value -weight: 20 ---- - -# Map a value - -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. - -![Map a value](/static/img/docs/value-mappings/map-value-8-0.png) diff --git a/docs/sources/visualizations/state-timeline.md b/docs/sources/visualizations/state-timeline.md index b6295cf0cf4..3fe9d4fe8c2 100644 --- a/docs/sources/visualizations/state-timeline.md +++ b/docs/sources/visualizations/state-timeline.md @@ -48,7 +48,7 @@ Controls the opacity of state regions. ## Value mappings -To assign colors to boolean or string values, use [Value mappings]({{< relref "../panels/format-data/about-value-mapping/" >}}). +To assign colors to boolean or string values, you can use [Value mappings]({{< relref "../panels/configure-value-mappings/" >}}). {{< figure src="/static/img/docs/v8/value_mappings_side_editor.png" max-width="300px" caption="Value mappings side editor" >}} diff --git a/docs/sources/whatsnew/whats-new-in-v8-0.md b/docs/sources/whatsnew/whats-new-in-v8-0.md index 410c96d1c69..bdbee2077e3 100644 --- a/docs/sources/whatsnew/whats-new-in-v8-0.md +++ b/docs/sources/whatsnew/whats-new-in-v8-0.md @@ -121,7 +121,7 @@ Lots of panel editor improvements, heavily informed by user research and communi - All options are now shown in a single pane. - You can now search panel options. -- The Value mappings feature has been completely redesigned. For more information, refer to [About value mappings]({{< relref "../panels/format-data/about-value-mapping/" >}}). +- The Value mappings feature has been completely redesigned. For more information, refer to [Configure value mappings]({{< relref "../panels/configure-value-mappings/" >}}). - New **Table view** option is always available. The [Panels]({{< relref "../panels/" >}}) section has been updated to reflect these changes.