IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-11 16:15:42 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Docs for Rows to fields and Config from query transformations (#36713)

Browse Source 
* Docs: Docs for new transformations rows to fields and config from query results

* Added config from query docs

* refinement

* Same lists everywhere

* minor tweak

* Added beta and version notices
This commit is contained in:
Torkel Ödegaard 2021-07-14 13:16:09 +02:00 committed by GitHub
parent 43ee7acecd
commit f29f190e73
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 267 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/sources/panels/thresholds.md
View File

@ -26,10 +26,8 @@ The **Base** value represents minus infinity. It is generally the “good” col
You can add as many thresholds to a panel as you want. Grafana automatically sorts thresholds from highest value to lowest.
> **Note:** These instructions apply only to the Stat, Gauge, Bar gauge, and Table visualizations.
1. Navigate to the panel you want to add a threshold to.
1. Click the **Field** tab.
1. Open the category **Thresholds** in the right side options pane.
1. Click **Add threshold**.
1. Grafana adds a threshold with suggested numerical and color values.
1. Accept the recommendations or edit the new threshold.

33
docs/sources/panels/transformations/_index.md
View File

@ -9,9 +9,8 @@ Transformations process the result set of a query before it’s passed on for vi
The transformations feature is accessible from the **Transform** tab of the Grafana panel editor.
> **Note:** Transformations is a Grafana 7.0 beta feature. Topics in this section will be frequently updated as we work on this feature.
Transformations sometimes result in data that cannot be graphed. When that happens, Grafana displays a suggestion on the visualization that you can click to switch to table visualization. This often helps you better understand what the transformation is doing to your data.
Transformations sometimes result in data that cannot be graphed. When that happens, click the `Table view` toggle above the visualization to switch to a table view of the data. This can help you understand
the final result of your transformations.
## Order of transformations
@ -23,13 +22,23 @@ The order in which transformations are applied can make a huge difference in how
Before you can configure and apply transformations:
- You must have entered a query and returned data from a data source. For more information on queries, refer to [Queries]({{< relref "../queries.md" >}}).
- You must have entered a query that return data. For more information on queries, refer to [Queries]({{< relref "../queries.md" >}}).
- You must have chosen a visualization that supports your query result and chosen transforms. Different transformations can result in a data structure that only some visualizations can render. For example, Graph visualization cannot show reduced data (that results from the Reduce transform). If your current visualization does not show you what you expect after applying a transform, switch to the Table visualization to check the result. For more information on the different types of visualizations, refer to:
- [Bar gauge]({{< relref "../visualizations/bar-gauge-panel.md" >}})
- [Gauge]({{< relref "../visualizations/gauge-panel.md" >}})
- [Graph]({{< relref "../visualizations/graph-panel.md" >}})
- [Heatmap]({{< relref "../visualizations/heatmap.md" >}})
- [Logs]({{< relref "../visualizations/logs-panel.md" >}})
- [Stat]({{< relref "../visualizations/stat-panel.md" >}})
- [Table]({{< relref "../visualizations/table/_index.md" >}})
## List of transformations
- [Add field from calculation]({{< relref "./types-options.md#add-field-from-calculation" >}})
- [Concatenate fields]({{< relref "./types-options.md#concatenate-fields" >}})
- [Config from query results]({{< relref "./config-from-query.md" >}})
- [Filter data by name]({{< relref "./types-options.md#filter-data-by-name" >}})
- [Filter data by query]({{< relref "./types-options.md#filter-data-by-query" >}})
- [Filter data by value]({{< relref "./types-options.md#filter-data-by-value" >}})
- [Group by]({{< relref "./types-options.md#group-by" >}})
- [Labels to fields]({{< relref "./types-options.md#labels-to-fields" >}})
- [Merge]({{< relref "./types-options.md#merge" >}})
- [Organize fields]({{< relref "./types-options.md#organize-fields" >}})
- [Outer join]({{< relref "./types-options.md#join-by-field-outer-join" >}})
- [Reduce]({{< relref "./types-options.md#reduce" >}})
- [Rename by regex]({{< relref "./types-options.md#rename-by-regex" >}})
- [Rows to fields]({{< relref "./rows-to-fields" >}})
- [Series to rows]({{< relref "./types-options.md#series-to-rows" >}})
- [Sort by]({{< relref "./types-options.md#sort-by" >}})

2
docs/sources/panels/transformations/apply-transformations.md
View File

@ -1,6 +1,6 @@
+++
title = "Apply a transformation"
weight = 300
weight = 1
+++

69
docs/sources/panels/transformations/config-from-query.md Normal file
View File

@ -0,0 +1,69 @@
+++
title = "Config from query results"
weight = 300
+++
# Config from query results transform
> **Note:** This is a new beta transformation introduced in v8.1.
This transformation allow you select one query and from it extract [standard options]({{< relref "./standard-options.md" >}}) like **Min**, **Max**, **Unit** and **Thresholds** and apply it to other query results. This enables dynamic query driven visualization configuration.
If you want to extract a unique config for every row in the config query result then try the [Rows to fields]({{< relref "./rows-to-fields" >}}) transformation instead.
### Options
- **Config query**: Selet the query that returns the data you want to use as configuration.
- **Apply to**: Select what fields or series to apply the configuration to.
- **Apply to options**: Usually a field type or field name regex depending on what option you selected in **Apply to**.
### Field mapping table
This transformation includes a field table which lists all fields in the data returned by the config query. This table gives you control over what field should be mapped to each config property (the *Use as** option). You can also choose which value to select if there are multiple rows in the returned data.
## Example
Input[0] (From query: A, name: ServerA)
| Time | Value |
| ------------- | ----- |
| 1626178119127 | 10 |
| 1626178119129 | 30 |
Input[1] (From query: B)
| Time | Value |
| ------------- | ----- |
| 1626178119127 | 100 |
| 1626178119129 | 100 |
Output (Same as Input[0] but now with config on the Value field)
| Time | Value (config: Max=100) |
| ------------- | ----------------------- |
| 1626178119127 | 10 |
| 1626178119129 | 30 |
As you can see each row in the source data becomes a separate field. Each field now also has a max config option set. Options like min, max, unit and thresholds are all part of field configuration and if set like this will be used by the visualization instead of any options manually configured in the panel editor options pane.
## Value mappings
You can also transform a query result into value mappings. This is is a bit different as here every row in the config query result will be used to define a single value mapping row. See example below.
Config query result:
| Value | Text | Color |
| ----- | ------ | ----- |
| L | Low | blue |
| M | Medium | green |
| H | High | red |
In the field mapping specify:
| Field | Use as | Select |
| ----- | ----------------------- | ---------- |
| Value | Value mappings / Value | All values |
| Text | Value mappings / Text | All values |
| Color | Value mappings / Ciolor | All values |
Grafana will build the value mappings from you query result and apply it the the real data query results. You should see values being mapped and colored according to the config query results.

72
docs/sources/panels/transformations/rows-to-fields.md Normal file
View File

@ -0,0 +1,72 @@
+++
title = "Rows to fields"
weight = 300
+++
# Rows to fields transform
> **Note:** This is a new beta transformation introduced in v8.1.
This transforms rows into separate fields. This can be useful as fields can be styled and configured individually, something rows cannot. It can also use additional fields as sources for dynamic field configuration or map them to field labels. The additional labels can then be used to define better display names for the resulting fields.
Useful when visualization data in:
- Gauge
- Stat
- Pie chart
If you want to extract config from one query and appply it to another you should use the [Config from query results]({{< relref "./config-from-query.md" >}}) transformation instead.
## Example
Input:
| Name | Value | Max |
| ------- | ----- | --- |
| ServerA | 10 | 100 |
| ServerB | 20 | 200 |
| ServerC | 30 | 300 |
Output:
| ServerA (config: max=100) | ServerB (config: max=200) | ServerC (config: max=300) |
| ------------------------- | ------------------------- | ------------------------- |
| 10 | 20 | 30 |
As you can see each row in the source data becomes a separate field. Each field now also has a max config option set. Options like **Min**, **Max**, **Unit** and **Thresholds** are all part of field configuration and if set like this will be used by the visualization instead of any options manually configured in the panel editor options pane.
## Configuration
To do this transformation Grafana needs to know how to use each field in the input data. The UI options for this transform shows you all fields and **Use as** option to tell Grafana how to use the field.
### The name field (required)
This transformation needs one field to use as the source of field names. By default the transform will use the first string field for this. But you can override this default behavior by selecting **Field name** in the **Use as** column for the field you want to use instead.
### The value field (required)
This transformation needs one field to use as the source of values. By default the transform will use the first number field for this. But you can override this default behavior by selecting **Field value** in the **Use as** column for the field you want to use instead.
### Map extra fields to config
You can map extra fields to configuration like min, max, unit and threshold. If the field name maps directly
to one of these config fields Grafana will handle this mapping automatically.
### Map extra fields to labels
If a field does not map to config property Grafana will automatically use it as source for a label on the output field-
Example:
| Name | DataCenter | Value |
| ------- | ---------- | ----- |
| ServerA | US | 100 |
| ServerB | EU | 200 |
Output:
| ServerA (labels: DataCenter: US) | ServerB (labels: DataCenter: EU) |
| -------------------------------- | -------------------------------- |
| 10 | 20 |
The extra labels can now be used in the field display name provide more complete field names.

49
docs/sources/panels/transformations/types-options.md
View File

@ -1,29 +1,28 @@
+++
title = "Transformation types and options"
weight = 300
title = "Types and options"
weight = 2
+++
# Transformation types and options
Grafana comes with the following transformations:
- [Transformation types and options](#transformation-types-and-options)
- [Reduce](#reduce)
- [Merge](#merge)
- [Filter data by name](#filter-data-by-name)
- [Filter data by query](#filter-data-by-query)
- [Organize fields](#organize-fields)
- [Join by field (outer join)](#join-by-field-outer-join)
- [Add field from calculation](#add-field-from-calculation)
- [Labels to fields](#labels-to-fields)
- [Value field name](#value-field-name)
- [Merging behavior](#merging-behavior)
- [Sort by](#sort-by)
- [Group by](#group-by)
- [Concatenate fields](#concatenate-fields)
- [Series to rows](#series-to-rows)
- [Filter data by value](#filter-data-by-value)
- [Rename by regex](#rename-by-regex)
- [Add field from calculation]({{< relref "./types-options.md#add-field-from-calculation" >}})
- [Concatenate fields]({{< relref "./types-options.md#concatenate-fields" >}})
- [Config from query results]({{< relref "./config-from-query.md" >}})
- [Filter data by name]({{< relref "./types-options.md#filter-data-by-name" >}})
- [Filter data by query]({{< relref "./types-options.md#filter-data-by-query" >}})
- [Filter data by value]({{< relref "./types-options.md#filter-data-by-value" >}})
- [Group by]({{< relref "./types-options.md#group-by" >}})
- [Labels to fields]({{< relref "./types-options.md#labels-to-fields" >}})
- [Merge]({{< relref "./types-options.md#merge" >}})
- [Organize fields]({{< relref "./types-options.md#organize-fields" >}})
- [Outer join]({{< relref "./types-options.md#join-by-field-outer-join" >}})
- [Reduce]({{< relref "./types-options.md#reduce" >}})
- [Rename by regex]({{< relref "./types-options.md#rename-by-regex" >}})
- [Rows to fields]({{< relref "./rows-to-fields" >}})
- [Series to rows]({{< relref "./types-options.md#series-to-rows" >}})
- [Sort by]({{< relref "./types-options.md#sort-by" >}})
Keep reading for detailed descriptions of each type of transformation and the options available for each, as well as suggestions on how to use them.
@ -81,8 +80,6 @@ Query B:
## Merge
> **Note:** This transformation is available in Grafana 7.1+.
Use this transformation to combine the result from multiple queries into one single result. This is helpful when using the table panel visualization. Values that can be merged are combined into the same row. Values are mergeable if the shared fields contain the same data. For information, refer to [Table panel]({{< relref "../visualizations/table/_index.md" >}}).
In the example below, we have two queries returning table data. It is visualized as two separate tables before applying the transformation.
@ -244,16 +241,12 @@ After merge:
## Sort by
> **Note:** This transformation is available in Grafana 7.4+.
This transformation will sort each frame by the configured field, When `reverse` is checked, the values will return in
the opposite order.
## Group by
> **Note:** This transformation is available in Grafana 7.2+.
This transformation groups the data by a specified field (column) value and processes calculations on each group. Click to see a list of calculation choices. For information about available calculations, refer to the [List of calculations]({{< relref "../calculations-list.md" >}}).
Here's an example of original data.
@ -312,8 +305,6 @@ This transformation allows you to extract some key information out of your time
## Concatenate fields
> **Note:** This transformation is available in Grafana 7.3+.
This transformation combines all fields from all frames into one result. Consider:
Query A:
@ -374,8 +365,6 @@ Here is the result after applying the Series to rows transformation.
## Filter data by value
> **Note:** This transformation is available in Grafana 7.4+.
This transformation allows you to filter your data directly in Grafana and remove some data points from your query result. You have the option to include or exclude data that match one or more conditions you define. The conditions are applied on a selected field.
This transformation is very useful if your data source does not natively filter by values. You might also use this to narrow values to display if you are using a shared query.
@ -437,8 +426,6 @@ Conditions that are invalid or incompletely configured are ignored.
## Rename by regex
> **Note:** This transformation is available in Grafana 7.4+.
Use this transformation to rename parts of the query results using a regular expression and replacement pattern.
You can specify a regular expression, which is only applied to matches, along with a replacement pattern that support back references. For example, let's imagine you're visualizing CPU usage per host and you want to remove the domain name. You could set the regex to `([^\.]+)\..+` and the replacement pattern to `$1`, `web-01.example.com` would become `web-01`.

64
public/app/core/components/TransformersUI/configFromQuery/ConfigFromQueryTransformerEditor.tsx
View File

@ -93,8 +93,70 @@ export const configFromQueryTransformRegistryItem: TransformerRegistryItem<Confi
help: `
### Use cases
Can take a query result and extract properties like min and max and apply it to the other query results.
This transformation allow you select one query and from it extract standard options like
**Min**, **Max**, **Unit** and **Thresholds** and apply it to other query results.
This enables dynamic query driven visualization configuration.
### Options
- **Config query**: Selet the query that returns the data you want to use as configuration.
- **Apply to**: Select what fields or series to apply the configuration to.
- **Apply to options**: Usually a field type or field name regex depending on what option you selected in **Apply to**.
### Field mapping table
Below the configuration listed above you will find the field table. Here all fields found in the data returned by the config query will be listed along with a **Use as** and **Select** option. This table gives you control over what field should be mapped to which config property and if there are multiple rows which value to select.
## Example
Input[0] (From query: A, name: ServerA)
| Time | Value |
| ------------- | ----- |
| 1626178119127 | 10 |
| 1626178119129 | 30 |
Input[1] (From query: B)
| Time | Value |
| ------------- | ----- |
| 1626178119127 | 100 |
| 1626178119129 | 100 |
Output (Same as Input[0] but now with config on the Value field)
| Time | Value (config: Max=100) |
| ------------- | ----------------------- |
| 1626178119127 | 10 |
| 1626178119129 | 30 |
As you can see each row in the source data becomes a separate field. Each field now also has a max
config option set. Options like min, max, unit and thresholds are all part of field configuration
and if set like this will be used by the visualization instead of any options manually configured
in the panel editor options pane.
## Value mappings
You can also transform a query result into value mappings. This is is a bit different as here every
row in the config query result will be used to define a single value mapping row. See example below.
Config query result:
| Value | Text | Color |
| ----- | ------ | ----- |
| L | Low | blue |
| M | Medium | green |
| H | High | red |
In the field mapping specify:
| Field | Use as | Select |
| ----- | ----------------------- | ---------- |
| Value | Value mappings / Value | All values |
| Text | Value mappings / Text | All values |
| Color | Value mappings / Ciolor | All values |
Grafana will build the value mappings from you query result and apply it the the real data query results. You should see values being mapped and colored according to the config query results.
`,
};

45
public/app/core/components/TransformersUI/rowsToFields/RowsToFieldsTransformerEditor.tsx
View File

@ -32,37 +32,36 @@ export const rowsToFieldsTransformRegistryItem: TransformerRegistryItem<RowToFie
help: `
### Use cases
This transformation transforms rows into separate fields. This can be useful as fields can be styled
and configured individually, something rows cannot. It can also use additional fields as sources for
data driven configuration or as sources for field labels. The additional labels can then be used to
define better display names for the resulting fields.
This transforms rows into separate fields. This can be useful as fields can be styled and configured
individually, something rows cannot. It can also use additional fields as sources for dynamic field
configuration or map them to field labels. The additional labels can then be used to define better
display names for the resulting fields.
Useful when visualization data in:
* Gauge
* Stat
* Pie chart
Useful when visualization data in:
- Gauge
- Stat
- Pie chart
### Configuration overview
* Select one field to use as the source of names for the new fields.
* Select one field to use as the values for the fields.
* Optionally map extra fields to config properties like min and max.
### Examples
## Example
Input:
Name | Value | Max
--------|-------|------
ServerA | 10 | 100
ServerB | 20 | 200
ServerC | 30 | 300
| Name | Value | Max |
| ------- | ----- | --- |
| ServerA | 10 | 100 |
| ServerB | 20 | 200 |
| ServerC | 30 | 300 |
Output:
ServerA (max=100) | ServerB (max=200) | ServerC (max=300)
------------------|------------------ | ------------------
10 | 20 | 30
| ServerA (config: max=100) | ServerB (config: max=200) | ServerC (config: max=300) |
| ------------------------- | ------------------------- | ------------------------- |
| 10 | 20 | 30 |
As you can see each row in the source data becomes a separate field. Each field now also has a max
config option set. Options like **Min**, **Max**, **Unit** and **Thresholds** are all part of field
configuration and if set like this will be used by the visualization instead of any options manually
configured in the panel editor options pane.
`,
};