mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Transformations: Separate useful doc content for UI use (#75781)
* baldm0mma/doc_builder/ add to gitignore * baldm0mma/doc_builder/ add makefile commands * baldm0mma/doc_builder/ add content * baldm0mma/doc_builder/ format content * baldm0mma/doc_builder/ update makefile * baldm0mma/docs_builder/ update content * baldm0mma/doc_builder/ add back content * baldm0mma/doc_builder/ run builder * baldm0mma/doc_builder/ update naming * baldm0mma/doc_builder/ remove unused note * baldm0mma/doc_builder/ update template * baldm0mma/doc_builder/ add new line in makefile * baldm0mma/doc_builder/ rem new line * baldm0mma/doc_builder/ add final line * Much of this full PR was Co-Authored-By: Jack Baldry <jack.baldry@grafana.com> * baldm0mma/doc_builder/ update readme * baldm0mma/doc_builder/ update guidlines * Update scripts/docs/generate-transformations.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update scripts/docs/generate-transformations.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update scripts/docs/generate-transformations.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update scripts/docs/generate-transformations.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update scripts/docs/generate-transformations.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update docs/README.md Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update docs/README.md Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * Update scripts/docs/generate-transformations.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * baldm0mma/doc_builder/ update concat * baldmomma/doc_builder/ finish concat table * baldm0mma/docs_builder/ update with suggestions * baldm0mma/doc_builder/ update content to use getHelperDocs * baldm0mma/doc_builder/ update calculateField * baldm0mma/doc_builder/ update to byRefId * baldm0mma/doc_builder/ update filterByValue * baldm0mma/doc_builder/ update filterFieldsByName * baldm0mma/doc_builder/ update formatTime * baldm0mma/doc_builder/ update groupBy * baldm0mma/doc_builder/ update groupingToMatrix * baldm0mma/doc_update/ update heatmap * baldm0mma/doc_builder/ update histogram * baldm0mma/doc_builder/ update joinByField * baldm0mma/doc_builder/ update joinByLabels * baldm0mma/doc_builder/ update labelsToFields * baldm0mma/doc_builder/ update limit * baldm0mma/doc_builder/ update merge * baldm0mma/doc_builder/ update organize * baldm0mma/doc_builder/ update partitionByValues * baldm0mma/doc_builder/ update prepareTimeSeries * baldm0mma/doc_builder/ update reduce * baldm0mma/doc_builder/ update renameByRegex * baldm0mma/doc_builder/ update rowsToFields * baldm0mma/doc_builder/ update seriesToRows * baldm0mma/doc_builder/ update sortBy * baldm0mma/doc_builder/ update spatial * baldm0mma/doc_builder/ update timeSeriesTable * baldm0mma/doc_builder/ rerender all * baldm0mma/doc_builder/ update calculateField * baldm0mma/doc_builder/ gitignore conflicts * baldm0mma/doc_builder/ add formatString * baldm0mma/doc_builder/ update vars * baldm0mma/doc_builder/ update naming * baldm0mma/doc_builder/ rerender markdown * Update public/app/features/transformers/docs/content.ts Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> * baldm0mma/doc_builder/ update content * baldm0mma/doc_builder/ add to codeownders * baldm0mma/doc_builder/ correct spelling * baldm0mma/doc_builder/ update comment --------- Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>
This commit is contained in:
Jev Forsberg
GitHub
parent
ec84caf389
commit
41db5b645c
1
.github/CODEOWNERS
vendored
1
.github/CODEOWNERS
vendored
@ -513,6 +513,7 @@ cypress.config.js @grafana/grafana-frontend-platform
|
||||
/scripts/verify-repo-update/ @grafana/grafana-delivery
|
||||
scripts/generate-icon-bundle.js @grafana/plugins-platform-frontend @grafana/grafana-frontend-platform
|
||||
|
||||
/scripts/docs/generate-transformations.ts @grafana/grafana-bi-squad
|
||||
/scripts/webpack/ @grafana/frontend-ops
|
||||
/scripts/generate-a11y-report.sh @grafana/grafana-frontend-platform
|
||||
.pa11yci.conf.js @grafana/grafana-frontend-platform
|
||||
|
||||
6
.gitignore
vendored
6
.gitignore
vendored
@ -202,4 +202,8 @@ deployment_tools_config.json
|
||||
.pr-body.txt
|
||||
|
||||
# Core plugin builds
|
||||
public/app/plugins/**/dist/
|
||||
public/app/plugins/**/dist/
|
||||
|
||||
# Ignore transpiled JavaScript resulting from the generate-transformations.ts script.
|
||||
/public/app/features/transformers/docs/*.js
|
||||
/scripts/docs/generate-transformations.js
|
||||
|
||||
@ -6,3 +6,11 @@ MAKEFLAGS += --warn-undefined-variables
|
||||
MAKEFLAGS += --no-builtin-rule
|
||||
|
||||
include docs.mk
|
||||
|
||||
.PHONY: sources/panels-visualizations/query-transform-data/transform-data/index.md
|
||||
sources/panels-visualizations/query-transform-data/transform-data/index.md: ## Generate the Transform Data page source.
|
||||
sources/panels-visualizations/query-transform-data/transform-data/index.md:
|
||||
cd $(CURDIR)/..
|
||||
npx tsc ../scripts/docs/generate-transformations.ts
|
||||
node ../scripts/docs/generate-transformations.js > $(CURDIR)/$@
|
||||
npx prettier -w $(CURDIR)/$@
|
||||
|
||||
@ -23,7 +23,17 @@ If you have the grafana/website repo checked out in the same directory as the gr
|
||||
|
||||
## Content guidelines
|
||||
|
||||
Edit content in the `sources` directory.
|
||||
Generally, one can edit content in the `sources` directory.
|
||||
|
||||
NOTE: the following paths are built instead from a typescript file and are auto-generated. Please do not edit these files directly.
|
||||
Instead, navigate to the appropriate typescript source file and edit the content there, then follow the build instructions to generate the markdown files.
|
||||
|
||||
- Transformations
|
||||
- Auto-generated markdown location:
|
||||
- docs/sources/panels-visualizations/query-transform-data/transform-data/index.md
|
||||
- Typescript location for editing and instructions:
|
||||
- scripts/docs/generate-transformations.ts - Includes all content not specific to a transformation.
|
||||
- public/app/features/transformers/docs/content.ts - Transformation-specific content.
|
||||
|
||||
### [Contributing](/contribute/documentation/README.md)
|
||||
|
||||
|
||||
@ -1,4 +1,16 @@
|
||||
---
|
||||
comments: |
|
||||
This Markdown file is auto-generated. Do not edit this file directly.
|
||||
To build this Markdown, do the following:
|
||||
|
||||
$ cd /docs (from the root of the repository)
|
||||
$ make sources/panels-visualizations/query-transform-data/transform-data/index.md
|
||||
$ make docs
|
||||
|
||||
Browse to http://localhost:3003/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/
|
||||
|
||||
Refer to ./docs/README.md "Content guidelines" for more information about editing and building these docs.
|
||||
|
||||
aliases:
|
||||
- ../../panels/reference-transformation-functions/
|
||||
- ../../panels/transform-data/
|
||||
@ -123,21 +135,21 @@ Use this transformation to add a new field calculated from two other fields. Eac
|
||||
- **Alias -** (Optional) Enter the name of your new field. If you leave this blank, then the field will be named to match the calculation.
|
||||
- **Replace all fields -** (Optional) Select this option if you want to hide all other fields and display only your calculated field in the visualization.
|
||||
|
||||
In the example below, I added two fields together and named them Sum.
|
||||
In the example below, we added two fields together and named them Sum.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/add-field-from-calc-stat-example-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
### Concatenate fields
|
||||
|
||||
This transformation combines all fields from all frames into one result. Consider:
|
||||
Use this transformation to combine all fields from all frames into one result. Consider the following:
|
||||
|
||||
Query A:
|
||||
**Query A:**
|
||||
|
||||
| Temp | Uptime |
|
||||
| ---- | ------- |
|
||||
| 15.4 | 1230233 |
|
||||
|
||||
Query B:
|
||||
**Query B:**
|
||||
|
||||
| AQI | Errors |
|
||||
| --- | ------ |
|
||||
@ -151,9 +163,9 @@ After you concatenate the fields, the data frame would be:
|
||||
|
||||
### Config from query results
|
||||
|
||||
This transformation allow you to 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.
|
||||
|
||||
If you want to extract a unique config for every row in the config query result then try the rows to fields transformation.
|
||||
Use this transformation to select one query and from it extract standard options such as
|
||||
**Min**, **Max**, **Unit**, and **Thresholds** and apply them to other query results.
|
||||
This enables dynamic query driven visualization configuration.
|
||||
|
||||
#### Options
|
||||
|
||||
@ -161,9 +173,63 @@ If you want to extract a unique config for every row in the config query result
|
||||
- **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 |
|
||||
|
||||
Each row in the source data becomes a separate field. Each field now also has a maximum
|
||||
configuration option set. Options such as **min**, **max**, **unit**, and **thresholds** are all part of field configuration, and if they are set like this, they will be used by the visualization instead of any options that are 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 because every
|
||||
row in the configuration query result is used to define a single value mapping row. See the following example.
|
||||
|
||||
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.
|
||||
|
||||
### Convert field type
|
||||
|
||||
This transformation changes the field type of the specified field.
|
||||
Use this transformation to change the field type of the specified field.
|
||||
|
||||
- **Field -** Select from available fields
|
||||
- **as -** Select the FieldType to convert to
|
||||
@ -173,7 +239,9 @@ This transformation changes the field type of the specified field.
|
||||
- Will show an option to specify a DateFormat as input by a string like yyyy-mm-dd or DD MM YYYY hh:mm:ss
|
||||
- **Boolean -** will make the values booleans
|
||||
|
||||
For example the following query could be modified by selecting the time field, as Time, and Date Format as YYYY.
|
||||
For example, the following query could be modified by selecting the time field, as Time, and Date Format as YYYY.
|
||||
|
||||
#### Sample Query
|
||||
|
||||
| Time | Mark | Value |
|
||||
| ---------- | ----- | ----- |
|
||||
@ -184,6 +252,8 @@ For example the following query could be modified by selecting the time field, a
|
||||
|
||||
The result:
|
||||
|
||||
#### Transformed Query
|
||||
|
||||
| Time | Mark | Value |
|
||||
| ------------------- | ----- | ----- |
|
||||
| 2017-01-01 00:00:00 | above | 25 |
|
||||
@ -191,29 +261,6 @@ The result:
|
||||
| 2019-01-01 00:00:00 | below | 29 |
|
||||
| 2020-01-01 00:00:00 | above | 22 |
|
||||
|
||||
### Create heatmap
|
||||
|
||||
Use this transformation to prepare histogram data to be visualized over time. Similar to the [Heatmap panel][], this transformation allows you to convert histogram metrics to buckets over time.
|
||||
|
||||
#### X Bucket
|
||||
|
||||
This setting determines how the x-axis is split into buckets.
|
||||
|
||||
- **Size** - Specify a time interval in the input field. For example, a time range of `1h` makes the cells one hour wide on the x-axis.
|
||||
- **Count** - For non-time related series, use this option to define the number of elements in a bucket.
|
||||
|
||||
#### Y Bucket
|
||||
|
||||
This setting determines how the y-axis is split into buckets.
|
||||
|
||||
#### Y Bucket scale
|
||||
|
||||
Use this option to set the scale of the y-axes. Select from:
|
||||
|
||||
- **Linear**
|
||||
- **Logarithmic** - Use a base 2 or base 10.
|
||||
- **Symlog** - A symmetrical logarithmic scale. Use a base 2 or base 10; allows negative values.
|
||||
|
||||
### Extract fields
|
||||
|
||||
Use this transformation to select one source of data and extract content from it in different formats. Set the following fields:
|
||||
@ -221,13 +268,15 @@ Use this transformation to select one source of data and extract content from it
|
||||
- **Source** - Select the field for the source of data.
|
||||
- **Format** - Select one of the following:
|
||||
- **JSON** - To parse JSON content from the source.
|
||||
- **Key+value parse** - To parse content in the format `a=b` or `c:d` from the source.
|
||||
- **Key+value parse** - To parse content in the format 'a=b' or 'c:d' from the source.
|
||||
- **Auto** - To discover fields automatically.
|
||||
- **Replace all fields** - Optional: Select this option if you want to hide all other fields and display only your calculated field in the visualization.
|
||||
- **Keep time** - Optional: Only available if **Replace all fields** is true. Keep the time field in the output.
|
||||
|
||||
Consider the following data set:
|
||||
|
||||
#### Data Set Example
|
||||
|
||||
| Timestamp | json_data |
|
||||
| ------------------- | ------------- |
|
||||
| 1636678740000000000 | {"value": 1} |
|
||||
@ -239,19 +288,21 @@ You could prepare the data to be used by a [Time series panel][] with this confi
|
||||
- Source: json_data
|
||||
- Format: JSON
|
||||
- Field: value
|
||||
- alias: my_value
|
||||
- Alias: my_value
|
||||
- Replace all fields: true
|
||||
- Keep time: true
|
||||
|
||||
This will generate the following output:
|
||||
|
||||
#### Transformed Data
|
||||
|
||||
| Timestamp | my_value |
|
||||
| ------------------- | -------- |
|
||||
| 1636678740000000000 | 1 |
|
||||
| 1636678680000000000 | 5 |
|
||||
| 1636678620000000000 | 12 |
|
||||
|
||||
### Field lookup
|
||||
### Lookup fields from resource
|
||||
|
||||
Use this transformation on a field value to look up additional fields from an external source.
|
||||
|
||||
@ -262,6 +313,8 @@ This transformation currently supports spatial data.
|
||||
|
||||
For example, if you have this data:
|
||||
|
||||
#### Data Set Example
|
||||
|
||||
| Location | Values |
|
||||
| --------- | ------ |
|
||||
| AL | 0 |
|
||||
@ -277,6 +330,8 @@ With this configuration:
|
||||
|
||||
You'll get the following output:
|
||||
|
||||
#### Transformed Data
|
||||
|
||||
| Location | ID | Name | Lng | Lat | Values |
|
||||
| --------- | --- | -------- | ----------- | --------- | ------ |
|
||||
| AL | AL | Alabama | -80.891064 | 12.448457 | 0 |
|
||||
@ -285,7 +340,84 @@ You'll get the following output:
|
||||
| Arkansas | | | | | 1 |
|
||||
| Somewhere | | | | | 5 |
|
||||
|
||||
### Filter by name
|
||||
### Filter data by query refId
|
||||
|
||||
Use this transformation in panels that have multiple queries, if you want to hide one or more of the queries.
|
||||
|
||||
Grafana displays the query identification letters in dark gray text. Click a query identifier to toggle filtering. If the query letter is white, then the results are displayed. If the query letter is dark, then the results are hidden.
|
||||
|
||||
> **Note:** This transformation is not available for Graphite because this data source does not support correlating returned data with queries.
|
||||
|
||||
In the example below, the panel has three queries (A, B, C). We removed the B query from the visualization.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/filter-by-query-stat-example-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
### Filter data by values
|
||||
|
||||
Use this transformation 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.
|
||||
|
||||
The available conditions for all fields are:
|
||||
|
||||
- **Regex:** Match a regex expression
|
||||
- **Is Null:** Match if the value is null
|
||||
- **Is Not Null:** Match if the value is not null
|
||||
- **Equal:** Match if the value is equal to the specified value
|
||||
- **Different:** Match if the value is different than the specified value
|
||||
|
||||
The available conditions for number fields are:
|
||||
|
||||
- **Greater:** Match if the value is greater than the specified value
|
||||
- **Lower:** Match if the value is lower than the specified value
|
||||
- **Greater or equal:** Match if the value is greater or equal
|
||||
- **Lower or equal:** Match if the value is lower or equal
|
||||
- **Range:** Match a range between a specified minimum and maximum, min and max included
|
||||
|
||||
Consider the following data set:
|
||||
|
||||
#### Data Set Example
|
||||
|
||||
| Time | Temperature | Altitude |
|
||||
| ------------------- | ----------- | -------- |
|
||||
| 2020-07-07 11:34:23 | 32 | 101 |
|
||||
| 2020-07-07 11:34:22 | 28 | 125 |
|
||||
| 2020-07-07 11:34:21 | 26 | 110 |
|
||||
| 2020-07-07 11:34:20 | 23 | 98 |
|
||||
| 2020-07-07 10:32:24 | 31 | 95 |
|
||||
| 2020-07-07 10:31:22 | 20 | 85 |
|
||||
| 2020-07-07 09:30:57 | 19 | 101 |
|
||||
|
||||
If you **Include** the data points that have a temperature below 30°C, the configuration will look as follows:
|
||||
|
||||
- Filter Type: 'Include'
|
||||
- Condition: Rows where 'Temperature' matches 'Lower Than' '30'
|
||||
|
||||
And you will get the following result, where only the temperatures below 30°C are included:
|
||||
|
||||
#### Transformed Data
|
||||
|
||||
| Time | Temperature | Altitude |
|
||||
| ------------------- | ----------- | -------- |
|
||||
| 2020-07-07 11:34:22 | 28 | 125 |
|
||||
| 2020-07-07 11:34:21 | 26 | 110 |
|
||||
| 2020-07-07 11:34:20 | 23 | 98 |
|
||||
| 2020-07-07 10:31:22 | 20 | 85 |
|
||||
| 2020-07-07 09:30:57 | 19 | 101 |
|
||||
|
||||
You can add more than one condition to the filter. For example, you might want to include the data only if the altitude is greater than 100. To do so, add that condition to the following configuration:
|
||||
|
||||
- Filter type: 'Include' rows that 'Match All' conditions
|
||||
- Condition 1: Rows where 'Temperature' matches 'Lower' than '30'
|
||||
- Condition 2: Rows where 'Altitude' matches 'Greater' than '100'
|
||||
|
||||
When you have more than one condition, you can choose if you want the action (include / exclude) to be applied on rows that **Match all** conditions or **Match any** of the conditions you added.
|
||||
|
||||
In the example above, we chose **Match all** because we wanted to include the rows that have a temperature lower than 30°C _AND_ an altitude higher than 100. If we wanted to include the rows that have a temperature lower than 30°C _OR_ an altitude higher than 100 instead, then we would select **Match any**. This would include the first row in the original data, which has a temperature of 32°C (does not match the first condition) but an altitude of 101 (which matches the second condition), so it is included.
|
||||
|
||||
Conditions that are invalid or incompletely configured are ignored.
|
||||
|
||||
### Filter fields by name
|
||||
|
||||
Use this transformation to remove parts of the query results.
|
||||
|
||||
@ -306,14 +438,14 @@ From the input data:
|
||||
| 2023-03-04 23:56:23 | 23.5 | 24.5 | 22.2 | 20.2 |
|
||||
| 2023-03-04 23:56:23 | 23.6 | 24.4 | 22.1 | 20.1 |
|
||||
|
||||
The result from using the regular expression `prod.*` would be:
|
||||
The result from using the regular expression 'prod.\*' would be:
|
||||
|
||||
| Time | prod-eu-west | prod-eu-north |
|
||||
| ------------------- | ------------ | ------------- |
|
||||
| 2023-03-04 23:56:23 | 22.2 | 20.2 |
|
||||
| 2023-03-04 23:56:23 | 22.1 | 20.1 |
|
||||
|
||||
The regular expression can include an interpolated dashboard variable by using the `${[variable name]}` syntax.
|
||||
The regular expression can include an interpolated dashboard variable by using the ${$variableName} syntax.
|
||||
|
||||
#### Manually select included fields
|
||||
|
||||
@ -321,86 +453,44 @@ Click and uncheck the field names to remove them from the result. Fields that ar
|
||||
|
||||
#### Use a dashboard variable
|
||||
|
||||
Enable `From variable` to let you select a dashboard variable that's used to include fields. By setting up a [dashboard variable][] with multiple choices, the same fields can be displayed across multiple visualizations.
|
||||
Enable 'From variable' to let you select a dashboard variable that's used to include fields. By setting up a [dashboard variable][] with multiple choices, the same fields can be displayed across multiple visualizations.
|
||||
|
||||
### Filter data by query
|
||||
{{< figure src="/static/img/docs/transformations/filter-name-table-before-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
Use this transformation in panels that have multiple queries, if you want to hide one or more of the queries.
|
||||
Here's the table after we applied the transformation to remove the Min field.
|
||||
|
||||
Grafana displays the query identification letters in dark gray text. Click a query identifier to toggle filtering. If the query letter is white, then the results are displayed. If the query letter is dark, then the results are hidden.
|
||||
{{< figure src="/static/img/docs/transformations/filter-name-table-after-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
In the example below, the panel has three queries (A, B, C). I removed the B query from the visualization.
|
||||
Here is the same query using a Stat visualization.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/filter-by-query-stat-example-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
{{< figure src="/static/img/docs/transformations/filter-name-stat-after-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This transformation is not available for Graphite because this data source does not support correlating returned data with queries.
|
||||
{{% /admonition %}}
|
||||
### Format string
|
||||
|
||||
### Filter data by value
|
||||
> **Note:** This transformation is an experimental feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. Enable the 'formatString' in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
|
||||
|
||||
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.
|
||||
Use this transformation to format the output of a string field. You can format output in the following ways:
|
||||
|
||||
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.
|
||||
- Upper case - Formats the entire string in upper case characters.
|
||||
- Lower case - Formats the entire string in lower case characters.
|
||||
- Sentence case - Formats the the first character of the string in upper case.
|
||||
- Title case - Formats the first character of each word in the string in upper case.
|
||||
- Pascal case - Formats the first character of each word in the string in upper case and doesn't include spaces between words.
|
||||
- Camel case - Formats the first character of each word in the string in upper case, except the first word, and doesn't include spaces between words.
|
||||
- Snake case - Formats all characters in the string in lower case and uses underscores instead of spaces between words.
|
||||
- Kebab case - Formats all characters in the string in lower case and uses dashes instead of spaces between words.
|
||||
- Trim - Removes all leading and trailing spaces from the string.
|
||||
- Substring - Returns a substring of the string, using the specified start and end positions.
|
||||
|
||||
The available conditions for all fields are:
|
||||
### Format time
|
||||
|
||||
- **Regex:** Match a regex expression
|
||||
- **Is Null:** Match if the value is null
|
||||
- **Is Not Null:** Match if the value is not null
|
||||
- **Equal:** Match if the value is equal to the specified value
|
||||
- **Different:** match if the value is different than the specified value
|
||||
Use this transformation to format the output of a time field. Output can be formatted using [Moment.js format strings](https://momentjs.com/docs/#/displaying/). For instance, if you would like to display only the year of a time field the format string 'YYYY' can be used to show the calendar year (e.g. 1999, 2012, etc.).
|
||||
|
||||
The available conditions for number fields are:
|
||||
|
||||
- **Greater:** Match if the value is greater than the specified value
|
||||
- **Lower:** Match if the value is lower than the specified value
|
||||
- **Greater or equal:** Match if the value is greater or equal
|
||||
- **Lower or equal:** Match if the value is lower or equal
|
||||
- **Range:** Match a range between a specified minimum and maximum, min and max included
|
||||
|
||||
Consider the following data set:
|
||||
|
||||
| Time | Temperature | Altitude |
|
||||
| ------------------- | ----------- | -------- |
|
||||
| 2020-07-07 11:34:23 | 32 | 101 |
|
||||
| 2020-07-07 11:34:22 | 28 | 125 |
|
||||
| 2020-07-07 11:34:21 | 26 | 110 |
|
||||
| 2020-07-07 11:34:20 | 23 | 98 |
|
||||
| 2020-07-07 10:32:24 | 31 | 95 |
|
||||
| 2020-07-07 10:31:22 | 20 | 85 |
|
||||
| 2020-07-07 09:30:57 | 19 | 101 |
|
||||
|
||||
If you **Include** the data points that have a temperature below 30°C, the configuration will look as follows:
|
||||
|
||||
- Filter Type: `Include`
|
||||
- Condition: Rows where `Temperature` matches `Lower Than` `30`
|
||||
|
||||
And you will get the following result, where only the temperatures below 30°C are included:
|
||||
|
||||
| Time | Temperature | Altitude |
|
||||
| ------------------- | ----------- | -------- |
|
||||
| 2020-07-07 11:34:22 | 28 | 125 |
|
||||
| 2020-07-07 11:34:21 | 26 | 110 |
|
||||
| 2020-07-07 11:34:20 | 23 | 98 |
|
||||
| 2020-07-07 10:31:22 | 20 | 85 |
|
||||
| 2020-07-07 09:30:57 | 19 | 101 |
|
||||
|
||||
You can add more than one condition to the filter. For example, you might want to include the data only if the altitude is greater than 100. To do so, add that condition to the following configuration:
|
||||
|
||||
- Filter type: `Include` rows that `Match All` conditions
|
||||
- Condition 1: Rows where `Temperature` matches `Lower` than `30`
|
||||
- Condition 2: Rows where `Altitude` matches `Greater` than `100`
|
||||
|
||||
When you have more than one condition, you can choose if you want the action (include / exclude) to be applied on rows that **Match all** conditions or **Match any** of the conditions you added.
|
||||
|
||||
In the example above we chose **Match all** because we wanted to include the rows that have a temperature lower than 30 _AND_ an altitude higher than 100. If we wanted to include the rows that have a temperature lower than 30 _OR_ an altitude higher than 100 instead, then we would select **Match any**. This would include the first row in the original data, which has a temperature of 32°C (does not match the first condition) but an altitude of 101 (which matches the second condition), so it is included.
|
||||
|
||||
Conditions that are invalid or incompletely configured are ignored.
|
||||
> **Note:** This transformation is available in Grafana 10.1+ as an alpha feature.
|
||||
|
||||
### Group by
|
||||
|
||||
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 [Calculation types][].
|
||||
Use this transformation to group the data by a specified field (column) value and process calculations on each group. Click to see a list of calculation choices. For information about available calculations, refer to [Calculation types][].
|
||||
|
||||
Here's an example of original data.
|
||||
|
||||
@ -468,15 +558,34 @@ Use this transformation to combine three fields-that will be used as input for t
|
||||
| server 2 | 88.6 | OK |
|
||||
| server 3 | 59.6 | Shutdown |
|
||||
|
||||
We can generate a matrix using the values of `Server Status` as column names, the `Server ID` values as row names, and the `CPU Temperature` as content of each cell. The content of each cell will appear for the existing column (`Server Status`) and row combination (`Server ID`). For the rest of the cells, you can select which value to display between: **Null**, **True**, **False**, or **Empty**.
|
||||
We can generate a matrix using the values of 'Server Status' as column names, the 'Server ID' values as row names, and the 'CPU Temperature' as content of each cell. The content of each cell will appear for the existing column ('Server Status') and row combination ('Server ID'). For the rest of the cells, you can select which value to display between: **Null**, **True**, **False**, or **Empty**.
|
||||
|
||||
**Output**
|
||||
|
||||
| Server ID\Server Status | OK | Shutdown |
|
||||
| ----------------------- | ---- | -------- |
|
||||
| server 1 | 82 | |
|
||||
| server 2 | 88.6 | |
|
||||
| server 3 | | 59.6 |
|
||||
| Server IDServer Status | OK | Shutdown |
|
||||
| ---------------------- | ---- | -------- |
|
||||
| server 1 | 82 | |
|
||||
| server 2 | 88.6 | |
|
||||
| server 3 | | 59.6 |
|
||||
|
||||
### Create heatmap
|
||||
|
||||
Use this transformation to prepare histogram data to be visualized over time. Similar to the Heatmap panel, this transformation allows you to convert histogram metrics to buckets over time.
|
||||
|
||||
#### X Bucket
|
||||
|
||||
This setting determines how the x-axis is split into buckets.
|
||||
|
||||
- **Size** - Specify a time interval in the input field. For example, a time range of '1h' makes the cells one hour wide on the x-axis.
|
||||
- **Count** - For non-time related series, use this option to define the number of elements in a bucket.
|
||||
|
||||
#### Y Bucket
|
||||
|
||||
This setting determines how the y-axis is split into buckets.
|
||||
|
||||
- **Linear**
|
||||
- **Logarithmic** - Use a base 2 or base 10.
|
||||
- **Symlog** - A symmetrical logarithmic scale. Use a base 2 or base 10; allows negative values.
|
||||
|
||||
### Histogram
|
||||
|
||||
@ -561,7 +670,7 @@ The result after applying the inner join transformation looks like the following
|
||||
|
||||
#### Outer join
|
||||
|
||||
An outer join includes all data from an inner join and rows where values do not match in every input. While the inner join joins Query A and Query B on the time field, the outer join includes all rows that don’t match on the time field.
|
||||
An outer join includes all data from an inner join and rows where values do not match in every input. While the inner join joins Query A and Query B on the time field, the outer join includes all rows that don't match on the time field.
|
||||
|
||||
In the following example, two queries return table data. It is visualized as two tables before applying the outer join transformation.
|
||||
|
||||
@ -610,21 +719,21 @@ time series results into a single wide table with a shared **Label** field.
|
||||
|
||||
##### Input
|
||||
|
||||
serie1{what="Temp", cluster="A", job="J1"}
|
||||
series1{what="Temp", cluster="A", job="J1"}
|
||||
|
||||
| Time | Value |
|
||||
| ---- | ----- |
|
||||
| 1 | 10 |
|
||||
| 2 | 200 |
|
||||
|
||||
serie2{what="Temp", cluster="B", job="J1"}
|
||||
series2{what="Temp", cluster="B", job="J1"}
|
||||
|
||||
| Time | Value |
|
||||
| ---- | ----- |
|
||||
| 1 | 10 |
|
||||
| 2 | 200 |
|
||||
|
||||
serie3{what="Speed", cluster="B", job="J1"}
|
||||
series3{what="Speed", cluster="B", job="J1"}
|
||||
|
||||
| Time | Value |
|
||||
| ---- | ----- |
|
||||
@ -646,7 +755,7 @@ value: "what"
|
||||
|
||||
### Labels to fields
|
||||
|
||||
This transformation changes time series results that include labels or tags into a table where each label keys and values are included in the table result. The labels can be displayed either as columns or as row values.
|
||||
Use this transformation to change time series results that include labels or tags into a table where each label's keys and values are included in the table result. The labels can be displayed as either columns or row values.
|
||||
|
||||
Given a query result of two time series:
|
||||
|
||||
@ -706,6 +815,29 @@ After merge:
|
||||
| 2020-07-07 11:34:20 | ServerA | 10 | |
|
||||
| 2020-07-07 11:34:20 | | 20 | EU |
|
||||
|
||||
### Limit
|
||||
|
||||
Use this transformation to limit the number of rows displayed.
|
||||
|
||||
In the example below, we have the following response from the data source:
|
||||
|
||||
| Time | Metric | Value |
|
||||
| ------------------- | ----------- | ----- |
|
||||
| 2020-07-07 11:34:20 | Temperature | 25 |
|
||||
| 2020-07-07 11:34:20 | Humidity | 22 |
|
||||
| 2020-07-07 10:32:20 | Humidity | 29 |
|
||||
| 2020-07-07 10:31:22 | Temperature | 22 |
|
||||
| 2020-07-07 09:30:57 | Humidity | 33 |
|
||||
| 2020-07-07 09:30:05 | Temperature | 19 |
|
||||
|
||||
Here is the result after adding a Limit transformation with a value of '3':
|
||||
|
||||
| Time | Metric | Value |
|
||||
| ------------------- | ----------- | ----- |
|
||||
| 2020-07-07 11:34:20 | Temperature | 25 |
|
||||
| 2020-07-07 11:34:20 | Humidity | 22 |
|
||||
| 2020-07-07 10:32:20 | Humidity | 29 |
|
||||
|
||||
### Merge
|
||||
|
||||
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][].
|
||||
@ -733,13 +865,11 @@ Here is the result after applying the Merge transformation.
|
||||
| 2020-07-07 11:34:20 | node | 15 | 25260122 |
|
||||
| 2020-07-07 11:24:20 | postgre | 5 | 123001233 |
|
||||
|
||||
### Organize fields
|
||||
### Oraganize fields
|
||||
|
||||
Use this transformation to rename, reorder, or hide fields returned by the query.
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This transformation only works in panels with a single query. If your panel has multiple queries, then you must either apply an Outer join transformation or remove the extra queries.
|
||||
{{% /admonition %}}
|
||||
> **Note:** This transformation only works in panels with a single query. If your panel has multiple queries, then you must either apply an Outer join transformation or remove the extra queries.
|
||||
|
||||
Grafana displays a list of fields returned by the query. You can:
|
||||
|
||||
@ -747,13 +877,9 @@ Grafana displays a list of fields returned by the query. You can:
|
||||
- Hide or show a field by clicking the eye icon next to the field name.
|
||||
- Rename fields by typing a new name in the **Rename <field>** box.
|
||||
|
||||
In the example below, I hid the value field and renamed Max and Min.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/organize-fields-stat-example-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
### Partition by values
|
||||
|
||||
This transformation can help eliminate the need for multiple queries to the same datasource with different `WHERE` clauses when graphing multiple series. Consider a metrics SQL table with the following data:
|
||||
Use this transformation to eliminate the need for multiple queries to the same data source with different 'WHERE' clauses when graphing multiple series. Consider a metrics SQL table with the following data:
|
||||
|
||||
| Time | Region | Value |
|
||||
| ------------------- | ------ | ----- |
|
||||
@ -764,14 +890,14 @@ This transformation can help eliminate the need for multiple queries to the same
|
||||
|
||||
Prior to v9.3, if you wanted to plot a red trendline for US and a blue one for EU in the same TimeSeries panel, you would likely have to split this into two queries:
|
||||
|
||||
`SELECT Time, Value FROM metrics WHERE Time > '2022-10-20' AND Region='US'`<br>
|
||||
`SELECT Time, Value FROM metrics WHERE Time > '2022-10-20' AND Region='EU'`
|
||||
'SELECT Time, Value FROM metrics WHERE Time > "2022-10-20" AND Region="US"'<br>
|
||||
'SELECT Time, Value FROM metrics WHERE Time > "2022-10-20" AND Region="EU"'
|
||||
|
||||
This also requires you to know ahead of time which regions actually exist in the metrics table.
|
||||
|
||||
With the _Partition by values_ transformer, you can now issue a single query and split the results by unique values in one or more columns (`fields`) of your choosing. The following example uses `Region`.
|
||||
With the _Partition by values_ transformer, you can now issue a single query and split the results by unique values in one or more columns ('fields') of your choosing. The following example uses 'Region'.
|
||||
|
||||
`SELECT Time, Region, Value FROM metrics WHERE Time > '2022-10-20'`
|
||||
'SELECT Time, Region, Value FROM metrics WHERE Time > "2022-10-20"'
|
||||
|
||||
| Time | Region | Value |
|
||||
| ------------------- | ------ | ----- |
|
||||
@ -783,14 +909,21 @@ With the _Partition by values_ transformer, you can now issue a single query and
|
||||
| 2022-10-20 12:00:00 | EU | 2936 |
|
||||
| 2022-10-20 01:00:00 | EU | 912 |
|
||||
|
||||
There are two naming modes:
|
||||
### Prepare time series
|
||||
|
||||
- **As labels** - The value that results are partitioned by is set as a label.
|
||||
- **As frame name** - The value is used to set the frame name. This is useful if the data will be visualized in a table.
|
||||
Use this transformation when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames][].
|
||||
|
||||
This transformation helps you resolve this issue by converting the time series data from either the wide format to the long format or the other way around.
|
||||
|
||||
Select the 'Multi-frame time series' option to transform the time series data frame from the wide to the long format.
|
||||
|
||||
Select the 'Wide time series' option to transform the time series data frame from the long to the wide format.
|
||||
|
||||
> **Note:** This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
|
||||
|
||||
### Reduce
|
||||
|
||||
The _Reduce_ transformation applies a calculation to each field in the frame and return a single value. Time fields are removed when applying this transformation.
|
||||
Use this transformation to apply a calculation to each field in the frame and return a single value. Time fields are removed when applying this transformation.
|
||||
|
||||
Consider the input:
|
||||
|
||||
@ -842,9 +975,9 @@ Query B:
|
||||
|
||||
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`.
|
||||
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'.
|
||||
|
||||
In the following example, we are stripping the prefix from event types. In the before image, you can see everything is prefixed with `system.`
|
||||
In the following example, we are stripping the prefix from event types. In the before image, you can see everything is prefixed with 'system.'
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/rename-by-regex-before-7-3.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
@ -854,7 +987,7 @@ With the transformation applied, you can see we are left with just the remainder
|
||||
|
||||
### Rows to fields
|
||||
|
||||
The rows to fields transformation converts rows into separate fields. This can be useful as fields can be styled and configured individually. 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.
|
||||
Use this transformation to convert rows into separate fields. This can be useful because fields can be styled and configured individually. 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.
|
||||
|
||||
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.
|
||||
|
||||
@ -913,26 +1046,8 @@ Output:
|
||||
|
||||
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.
|
||||
|
||||
### Prepare time series
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This transformation is available in Grafana 7.5.10+ and Grafana 8.0.6+.
|
||||
{{% /admonition %}}
|
||||
|
||||
Prepare time series transformation is useful when a data source returns time series data in a format that isn't supported by the panel you want to use. For more information about data frame formats, refer to [Data frames](https://grafana.com/developers/plugin-tools/introduction/data-frames).
|
||||
|
||||
This transformation helps you resolve this issue by converting the time series data from either the wide format to the long format or the other way around.
|
||||
|
||||
Select the `Multi-frame time series` option to transform the time series data frame from the wide to the long format.
|
||||
|
||||
Select the `Wide time series` option to transform the time series data frame from the long to the wide format.
|
||||
|
||||
### Series to rows
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This transformation is available in Grafana 7.1+.
|
||||
{{% /admonition %}}
|
||||
|
||||
Use this transformation to combine the result from multiple time series data queries into one single result. This is helpful when using the table panel visualization.
|
||||
|
||||
The result from this transformation will contain three columns: Time, Metric, and Value. The Metric column is added so you easily can see from which query the metric originates from. Customize this value by defining Label on the source query.
|
||||
@ -966,32 +1081,15 @@ Here is the result after applying the Series to rows transformation.
|
||||
| 2020-07-07 09:30:57 | Humidity | 33 |
|
||||
| 2020-07-07 09:30:05 | Temperature | 19 |
|
||||
|
||||
> **Note:** This transformation is available in Grafana 7.1+.
|
||||
|
||||
### Sort by
|
||||
|
||||
This transformation will sort each frame by the configured field, When `reverse` is checked, the values will return in the opposite order.
|
||||
Use this transformation to sort each frame by the configured field. When the **Reverse** switch is on, the values will return in the opposite order.
|
||||
|
||||
### Limit
|
||||
### Spatial
|
||||
|
||||
Use this transformation to limit the number of rows displayed.
|
||||
|
||||
In the example below, we have the following response from the data source:
|
||||
|
||||
| Time | Metric | Value |
|
||||
| ------------------- | ----------- | ----- |
|
||||
| 2020-07-07 11:34:20 | Temperature | 25 |
|
||||
| 2020-07-07 11:34:20 | Humidity | 22 |
|
||||
| 2020-07-07 10:32:20 | Humidity | 29 |
|
||||
| 2020-07-07 10:31:22 | Temperature | 22 |
|
||||
| 2020-07-07 09:30:57 | Humidity | 33 |
|
||||
| 2020-07-07 09:30:05 | Temperature | 19 |
|
||||
|
||||
Here is the result after adding a Limit transformation with a value of '3':
|
||||
|
||||
| Time | Metric | Value |
|
||||
| ------------------- | ----------- | ----- |
|
||||
| 2020-07-07 11:34:20 | Temperature | 25 |
|
||||
| 2020-07-07 11:34:20 | Humidity | 22 |
|
||||
| 2020-07-07 10:32:20 | Humidity | 29 |
|
||||
Use this transformation to apply spatial operations to query results
|
||||
|
||||
### Time series to table transform
|
||||
|
||||
@ -999,35 +1097,15 @@ Use this transformation to convert time series result into a table, converting t
|
||||
|
||||
For each generated "Trend" field value calculation function can be selected. Default is "last non null value". This value will be displayed next to the sparkline and used for sorting table rows.
|
||||
|
||||
### Format Time
|
||||
|
||||
{{% admonition type="note" %}}
|
||||
This transformation is available in Grafana 10.1+ as an alpha feature.
|
||||
{{% /admonition %}}
|
||||
|
||||
Use this transformation to format the output of a time field. Output can be formatted using (Moment.js format strings)[https://momentjs.com/docs/#/displaying/]. For instance, if you would like to display only the year of a time field the format string `YYYY` can be used to show the calendar year (e.g. 1999, 2012, etc.).
|
||||
|
||||
### Format string
|
||||
|
||||
> **Note:** This transformation is an experimental feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. Enable the `formatString` in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
|
||||
|
||||
Use this transformation to format the output of a string field. You can format output in the following ways:
|
||||
|
||||
- Upper case - Formats the entire string in upper case characters.
|
||||
- Lower case - Formats the entire string in lower case characters.
|
||||
- Sentence case - Formats the the first character of the string in upper case.
|
||||
- Title case - Formats the first character of each word in the string in upper case.
|
||||
- Pascal case - Formats the first character of each word in the string in upper case and doesn't include spaces between words.
|
||||
- Camel case - Formats the first character of each word in the string in upper case, except the first word, and doesn't include spaces between words.
|
||||
- Snake case - Formats all characters in the string in lower case and uses underscores instead of spaces between words.
|
||||
- Kebab case - Formats all characters in the string in lower case and uses dashes instead of spaces between words.
|
||||
- Trim - Removes all leading and trailing spaces from the string.
|
||||
- Substring - Returns a substring of the string, using the specified start and end positions.
|
||||
> **Note:** This transformation is available in Grafana 9.5+ as an opt-in beta feature. Modify Grafana [configuration file][] to use it.
|
||||
|
||||
{{% docs/reference %}}
|
||||
[Table panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
|
||||
[Table panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
|
||||
|
||||
[Data frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
|
||||
[Data frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
|
||||
|
||||
[Calculation types]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
|
||||
[Calculation types]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
|
||||
|
||||
|
||||
1224
public/app/features/transformers/docs/content.ts
Normal file
1224
public/app/features/transformers/docs/content.ts
Normal file
File diff suppressed because it is too large
Load Diff
177
scripts/docs/generate-transformations.ts
Normal file
177
scripts/docs/generate-transformations.ts
Normal file
@ -0,0 +1,177 @@
|
||||
import {
|
||||
transformationDocsContent,
|
||||
TransformationDocsContentType,
|
||||
ImageRenderType,
|
||||
} from '../../public/app/features/transformers/docs/content';
|
||||
|
||||
const template = `---
|
||||
comments: |
|
||||
This Markdown file is auto-generated. Do not edit this file directly.
|
||||
To build this Markdown, do the following:
|
||||
|
||||
$ cd /docs (from the root of the repository)
|
||||
$ make sources/panels-visualizations/query-transform-data/transform-data/index.md
|
||||
$ make docs
|
||||
|
||||
Browse to http://localhost:3003/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/
|
||||
|
||||
Refer to ./docs/README.md "Content guidelines" for more information about editing and building these docs.
|
||||
|
||||
aliases:
|
||||
- ../../panels/reference-transformation-functions/
|
||||
- ../../panels/transform-data/
|
||||
- ../../panels/transform-data/about-transformation/
|
||||
- ../../panels/transform-data/add-transformation-to-data/
|
||||
- ../../panels/transform-data/apply-transformation-to-data/
|
||||
- ../../panels/transform-data/debug-transformation/
|
||||
- ../../panels/transform-data/delete-transformation/
|
||||
- ../../panels/transform-data/transformation-functions/
|
||||
- ../../panels/transformations/
|
||||
- ../../panels/transformations/apply-transformations/
|
||||
- ../../panels/transformations/config-from-query/
|
||||
- ../../panels/transformations/rows-to-fields/
|
||||
- ../../panels/transformations/types-options/
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: Transform data
|
||||
weight: 100
|
||||
---
|
||||
|
||||
# Transform data
|
||||
|
||||
Transformations are a powerful way to manipulate data returned by a query before the system applies a visualization. Using transformations, you can:
|
||||
|
||||
- Rename fields
|
||||
- Join time series data
|
||||
- Perform mathematical operations across queries
|
||||
- Use the output of one transformation as the input to another transformation
|
||||
|
||||
For users that rely on multiple views of the same dataset, transformations offer an efficient method of creating and maintaining numerous dashboards.
|
||||
|
||||
You can also use the output of one transformation as the input to another transformation, which results in a performance gain.
|
||||
|
||||
> Sometimes the system cannot graph transformed data. 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.
|
||||
|
||||
## Transformation types
|
||||
|
||||
Grafana provides a number of ways that you can transform data. For a complete list of transformations, refer to [Transformation functions](#transformation-functions).
|
||||
|
||||
## Order of transformations
|
||||
|
||||
When there are multiple transformations, Grafana applies them in the order they are listed. Each transformation creates a result set that then passes on to the next transformation in the processing pipeline.
|
||||
|
||||
The order in which Grafana applies transformations directly impacts the results. For example, if you use a Reduce transformation to condense all the results of one column into a single value, then you can only apply transformations to that single value.
|
||||
|
||||
## Add a transformation function to data
|
||||
|
||||
The following steps guide you in adding a transformation to data. This documentation does not include steps for each type of transformation. For a complete list of transformations, refer to [Transformation functions](#transformation-functions).
|
||||
|
||||
1. Navigate to the panel where you want to add one or more transformations.
|
||||
1. Hover over any part of the panel to display the actions menu on the top right corner.
|
||||
1. Click the menu and select **Edit**.
|
||||
1. Click the **Transform** tab.
|
||||
1. Click a transformation.
|
||||
A transformation row appears where you configure the transformation options. For more information about how to configure a transformation, refer to [Transformation functions](#transformation-functions).
|
||||
For information about available calculations, refer to [Calculation types][].
|
||||
1. To apply another transformation, click **Add transformation**.
|
||||
This transformation acts on the result set returned by the previous transformation.
|
||||
{{< figure src="/static/img/docs/transformations/transformations-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
## Debug a transformation
|
||||
|
||||
To see the input and the output result sets of the transformation, click the bug icon on the right side of the transformation row.
|
||||
|
||||
The input and output results sets can help you debug a transformation.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/debug-transformations-7-0.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
## Disable a transformation
|
||||
|
||||
You can disable or hide one or more transformations by clicking on the eye icon on the top right side of the transformation row. This disables the applied actions of that specific transformation and can help to identify issues when you change several transformations one after another.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/screenshot-example-disable-transformation.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
## Filter a transformation
|
||||
|
||||
If your panel uses more than one query, you can filter these and apply the selected transformation to only one of the queries. To do this, click the filter icon on the top right of the transformation row. This opens a drop-down with a list of queries used on the panel. From here, you can select the query you want to transform.
|
||||
|
||||
Note that the filter icon is always displayed if your panel has more than one query, but it may not work if previous transformations for merging the queries' outputs are applied. This is because one transformation takes the output of the previous one.
|
||||
|
||||
## Delete a transformation
|
||||
|
||||
We recommend that you remove transformations that you don't need. When you delete a transformation, you remove the data from the visualization.
|
||||
|
||||
**Before you begin:**
|
||||
|
||||
- Identify all dashboards that rely on the transformation and inform impacted dashboard users.
|
||||
|
||||
**To delete a transformation**:
|
||||
|
||||
1. Open a panel for editing.
|
||||
1. Click the **Transform** tab.
|
||||
1. Click the trash icon next to the transformation you want to delete.
|
||||
|
||||
{{< figure src="/static/img/docs/transformations/screenshot-example-remove-transformation.png" class="docs-image--no-shadow" max-width= "1100px" >}}
|
||||
|
||||
## Transformation functions
|
||||
|
||||
You can perform the following transformations on your data.
|
||||
|
||||
${buildTransformationDocsContent(transformationDocsContent)}
|
||||
|
||||
{{% docs/reference %}}
|
||||
[Table panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
|
||||
[Table panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
|
||||
|
||||
[Data frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
|
||||
[Data frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
|
||||
|
||||
[Calculation types]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
|
||||
[Calculation types]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
|
||||
|
||||
[sparkline cell type]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table#sparkline"
|
||||
[sparkline cell type]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table#sparkline"
|
||||
|
||||
[Heatmap panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/heatmap"
|
||||
[Heatmap panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/heatmap"
|
||||
|
||||
[configuration file]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#configuration-file-location"
|
||||
[configuration file]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#configuration-file-location"
|
||||
|
||||
[Time series panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/time-series"
|
||||
[Time series panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/time-series"
|
||||
|
||||
[feature toggle]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#feature_toggles"
|
||||
[feature toggle]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/setup-grafana/configure-grafana#feature_toggles"
|
||||
|
||||
[dashboard variable]: "/docs/grafana/ -> docs/grafana/<GRAFANA VERSION>/dashboards/variables"
|
||||
[dashboard variable]: "/docs/grafana-cloud/ -> docs/grafana/<GRAFANA VERSION>/dashboards/variables"
|
||||
|
||||
{{% /docs/reference %}}
|
||||
`;
|
||||
|
||||
function buildTransformationDocsContent(transformationDocsContent: TransformationDocsContentType) {
|
||||
const transformationsList = Object.keys(transformationDocsContent);
|
||||
|
||||
const content = transformationsList
|
||||
.map((transformationName) => {
|
||||
return `
|
||||
### ${transformationDocsContent[transformationName].name}
|
||||
${transformationDocsContent[transformationName].getHelperDocs(ImageRenderType.ShortcodeFigure)}
|
||||
`;
|
||||
})
|
||||
// Remove the superfluous commas.
|
||||
.join('');
|
||||
|
||||
return content;
|
||||
}
|
||||
|
||||
/*
|
||||
`process.stdout.write(template + '\n')` was not functioning as expected.
|
||||
Neither the tsc nor ts-node compiler could identify the node `process` object.
|
||||
Fortunately, `console.log` also writes to the standard output.
|
||||
*/
|
||||
console.log(template);
|
||||
Loading…
Reference in New Issue
Block a user