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.
Grafana provides a number of ways that you can transform data. For a complete list of transformations, refer to [Transformation functions](#transformation-functions).
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.
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).
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][].
{{<figuresrc="/static/img/docs/transformations/transformations-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="Transform tab in the panel editor">}}
{{<figuresrc="/static/img/docs/transformations/debug-transformations-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="The debug transformation screen with the debug icon highlighted">}}
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.
{{<figuresrc="/static/img/docs/transformations/screenshot-example-disable-transformation.png"class="docs-image--no-shadow"max-width="1100px"alt="A transformation row with the disable transformation icon highlighted">}}
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.
- **Row index** - Insert a field with the row index.
- **Field name** - Select the names of fields you want to use in the calculation for the new field.
- **Calculation** - If you select **Reduce row** mode, then the **Calculation** field appears. Click in the field to see a list of calculation choices you can use to create the new field. For information about available calculations, refer to [Calculation types][].
- **Operation** - If you select **Binary operation** or **Unary operation** mode, then the **Operation** fields appear. These fields allow you to apply basic math operations on values in a single row from selected fields. You can also use numerical values for binary operations.
- **As percentile** - If you select **Row index** mode, then the **As percentile** switch appears. This switch allows you to transform the row index as a percentage of the total number of rows.
- **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.
> **Note:** **Cumulative functions** and **Window functions** modes are experimental features. 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 **addFieldFromCalculationStatFunctions** feature toggle in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
{{<figuresrc="/static/img/docs/transformations/add-field-from-calc-stat-example-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="A stat visualization including one field called Sum">}}
Use this transformation to combine all fields from all frames into one result.
For example, if you have separate queries retrieving temperature and uptime data (Query A) and air quality index and error information (Query B), applying the concatenate transformation yields a consolidated data frame with all relevant information in one view.
Use this transformation to select a query and extract standard options, such as **Min**, **Max**, **Unit**, and **Thresholds**, and apply them to other query results. This feature enables dynamic visualization configuration based on the data returned by a specific query.
Below the configuration options, you'll find the field mapping table. This table lists all fields found in the data returned by the config query, along with **Use as** and **Select** options. It provides control over mapping fields to config properties, and for multiple rows, it allows you to choose which value to select.
Each row in the source data becomes a separate field. Each field now has a maximum configuration option set. Options such as **Min**, **Max**, **Unit**, and **Thresholds** are part of the field configuration. If set, they are used by the visualization instead of any options manually configured in the panel editor options pane.
You can also transform a query result into value mappings. With this option, every row in the configuration query result defines a single value mapping row. See the following example.
Grafana builds value mappings from your query result and applies them to the real data query results. You should see values being mapped and colored according to the config query results.
This transformation lets you augment your data by fetching additional information from external sources, providing a more comprehensive dataset for analysis and visualization.
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.
{{<figuresrc="/static/img/docs/transformations/filter-by-query-stat-example-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="A stat visualization with results from two queries, A and C">}}
Use this transformation to selectively filter data points directly within your visualization. This transformation provides options to include or exclude data based on one or more conditions applied to 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.
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:
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.
This versatile data filtering transformation lets you to selectively include or exclude data points based on specific conditions. Customize the criteria to tailor your data presentation to meet your unique analytical needs.
Click and uncheck the field names to remove them from the result. Fields that are matched by the regular expression are still included, even if they're unchecked.
#### 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.
{{<figuresrc="/static/img/docs/transformations/filter-name-table-before-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="A table visualization with time, value, Min, and Max columns">}}
{{<figuresrc="/static/img/docs/transformations/filter-name-table-after-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="A table visualization with time, value, and Max columns">}}
{{<figuresrc="/static/img/docs/transformations/filter-name-stat-after-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="A stat visualization with value and Max fields">}}
This transformation provides flexibility in tailoring your query results to focus on the specific fields you need for effective analysis and visualization.
Use this transformation to customize the output of a string field. This transformation has the following fields:
- **Upper case** - Formats the entire string in uppercase characters.
- **Lower case** - Formats the entire string in lowercase characters.
- **Sentence case** - Formats the first character of the string in uppercase.
- **Title case** - Formats the first character of each word in the string in uppercase.
- **Pascal case** - Formats the first character of each word in the string in uppercase and doesn't include spaces between words.
- **Camel case** - Formats the first character of each word in the string in uppercase, except the first word, and doesn't include spaces between words.
- **Snake case** - Formats all characters in the string in lowercase and uses underscores instead of spaces between words.
- **Kebab case** - Formats all characters in the string in lowercase 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 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** feature toggle in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
Use this transformation to customize the output of a time field. Output can be formatted using [Moment.js format strings](https://momentjs.com/docs/#/displaying/). For example, if you want to display only the year of a time field, the format string 'YYYY' can be used to show the calendar year (for example, 1999 or 2012).
**Before Transformation:**
| Timestamp | Event |
| ------------------- | ------------ |
| 1636678740000000000 | System Start |
| 1636678680000000000 | User Login |
| 1636678620000000000 | Data Updated |
**After applying 'YYYY-MM-DD HH:mm:ss':**
| Timestamp | Event |
| ------------------- | ------------ |
| 2021-11-12 14:25:40 | System Start |
| 2021-11-12 14:24:40 | User Login |
| 2021-11-12 14:23:40 | Data Updated |
This transformation lets you tailor the time representation in your visualizations, providing flexibility and precision in displaying temporal data.
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][].
This transformation goes in two steps. First you specify one or multiple fields to group the data by. This will group all the same values of those fields together, as if you sorted them. For instance if we group by the Server ID field, then it would group the data this way:
| Time | Server ID | CPU Temperature | Server Status |
All rows with the same value of Server ID are grouped together.
After choosing which field you want to group your data by, you can add various calculations on the other fields, and apply the calculation to each group of rows. For instance, we could want to calculate the average CPU temperature for each of those servers. So we can add the _mean_ calculation applied on the CPU Temperature field to get the following:
| Server ID | CPU Temperature (mean) |
| --------- | ---------------------- |
| server 1 | 82 |
| server 2 | 88.6 |
| server 3 | 59.6 |
And we can add more than one calculation. For instance:
- For field Time, we can calculate the _Last_ value, to know when the last data point was received for each server
- For field Server Status, we can calculate the _Last_ value to know what is the last state value for each server
- For field Temperature, we can also calculate the _Last_ value to know what is the latest monitored temperature for each server
Use this transformation to combine three fields—which are used as input for the **Column**, **Row**, and **Cell value** fields from the query output—and generate a matrix. The matrix is calculated as follows:
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**.
Use this transformation to construct a matrix by specifying fields from your query results. The matrix output reflects the relationships between the unique values in these fields. This helps you present complex relationships in a clear and structured matrix format.
Use this transformation to prepare histogram data for visualizing trends over time. Similar to the heatmap visualization, this transformation converts histogram metrics into temporal buckets.
- **Logarithmic** - Choose between log base 2 or log base 10.
- **Symlog** - Uses a symmetrical logarithmic scale. Choose between log base 2 or log base 10, allowing for negative values.
Assume you have the following dataset:
| Timestamp | Value |
| ------------------- | ----- |
| 2023-01-01 12:00:00 | 5 |
| 2023-01-01 12:15:00 | 10 |
| 2023-01-01 12:30:00 | 15 |
| 2023-01-01 12:45:00 | 8 |
- With X Bucket set to 'Size: 15m' and Y Bucket as 'Linear', the histogram organizes values into time intervals of 15 minutes on the x-axis and linearly on the y-axis.
- For X Bucket as 'Count: 2' and Y Bucket as 'Logarithmic (base 10)', the histogram groups values into buckets of two on the x-axis and use a logarithmic scale on the y-axis.
An inner join merges data from multiple tables where all tables share the same value from the selected field. This type of join excludes data where values do not match in every result.
Use this transformation to combine the results from multiple queries (combining on a passed join field or the first time column) into one result, and drop rows where a successful join cannot occur.
In the following example, two queries return table data. It is visualized as two separate tables before applying the inner join transformation.
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, a template query displays time series data from multiple servers in a table visualization. The results of only one query can be viewed at a time.
{{<figuresrc="/static/img/docs/transformations/join-fields-before-7-0.png"class="docs-image--no-shadow"max-width="1100px"alt="A table visualization showing results for one server">}}
I applied a transformation to join the query results using the time field. Now I can run calculations, combine, and organize the results in this new table.
Use this transformation to convert time series results with labels or tags into a table, including each label's keys and values in the result. Display labels as either columns or row values for enhanced data visualization.
The labels to fields transformer is internally two separate transformations. The first acts on single series and extracts labels to fields. The second is the [merge](#merge) transformation that joins all the results into a single table. The merge transformation tries to join on all matching fields. This merge step is required and cannot be turned off.
To illustrate this, here is an example where you have two queries that return time series with no overlapping labels.
Use this transformation to restrict the number of rows displayed, providing a more focused view of your data. This is particularly useful when dealing with large datasets.
Use this transformation to combine the results from multiple queries into a single result, which is particularly useful when using the table panel visualization. This transformation merges values into the same row if the shared fields contain the same data.
This transformation combines values from Query A and Query B into a unified table, enhancing the presentation of data for better insights.
### Organize fields by name
Use this transformation to provide the flexibility to rename, reorder, or hide fields returned by a single query in your panel. This transformation is applicable only to panels with a single query. If your panel has multiple queries, consider using an "Outer join" transformation or removing extra queries.
#### Transforming fields
Grafana displays a list of fields returned by the query, allowing you to perform the following actions:
With the **Partition by values** transformation, you can 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':
Use this transformation to address issues when a data source returns time series data in a format that isn't compatible with the desired visualization. This transformation allows you to convert time series data between wide and long formats, providing flexibility in data frame structures.
Use this option to transform the time series data frame from the wide format to the long format. This is particularly helpful when your data source delivers time series information in a format that needs to be reshaped for optimal compatibility with your visualization.
Select this option to transform the time series data frame from the long format to the wide format. If your data source returns time series data in a long format and your visualization requires a wide format, this transformation simplifies the process.
Use this transformation to apply a calculation to each field in the data frame and return a single value. This transformation is particularly useful for consolidating multiple time series data into a more compact, summarized format. Time fields are removed when applying this transformation.
This flexible transformation simplifies the process of consolidating and summarizing data from multiple time series into a more manageable and organized format.
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'.
{{<figuresrc="/static/img/docs/transformations/rename-by-regex-before-7-3.png"class="docs-image--no-shadow"max-width="1100px"alt="A bar chart with long series names">}}
{{<figuresrc="/static/img/docs/transformations/rename-by-regex-after-7-3.png"class="docs-image--no-shadow"max-width="1100px"alt="A bar chart with shortened series names">}}
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 configuration query. This table gives you control over what field should be mapped to each configuration property (the **Use as** option). You can also choose which value to select if there are multiple rows in the returned data.
By default, the transform uses the first string field as the source. You can override this default setting by selecting **Field name** in the **Use as** column for the field you want to use instead.
By default, the transform uses the first number field as the source. But you can override this default setting by selecting **Field value** in the **Use as** column for the field you want to use instead.
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.
This transformation enables the conversion of rows into individual fields, facilitates dynamic field configuration, and maps additional fields to labels.
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.
This transformation facilitates the consolidation of results from multiple time series queries, providing a streamlined and unified dataset for efficient analysis and visualization in a tabular format.
Use this transformation to sort each frame within a query result based on a specified field, making your data easier to understand and analyze. By configuring the desired field for sorting, you can control the order in which the data is presented in the table or visualization.
Use the **Reverse** switch to inversely order the values within the specified field. This functionality is particularly useful when you want to quickly toggle between ascending and descending order to suit your analytical needs.
For example, in a scenario where time-series data is retrieved from a data source, the **Sort by** transformation can be applied to arrange the data frames based on the timestamp, either in ascending or descending order, depending on the analytical requirements. This capability ensures that you can easily navigate and interpret time-series data, gaining valuable insights from the organized and visually coherent presentation.
Use this transformation to apply spatial operations to query results.
- **Action** - Select an action:
- **Prepare spatial field** - Set a geometry field based on the results of other fields.
- **Location mode** - Select a location mode (these options are shared by the **Calculate value** and **Transform** modes):
- **Auto** - Automatically identify location data based on default field names.
- **Coords** - Specify latitude and longitude fields.
- **Geohash** - Specify a geohash field.
- **Lookup** - Specify Gazetteer location fields.
- **Calculate value** - Use the geometry to define a new field (heading/distance/area).
- **Function** - Choose a mathematical operation to apply to the geometry:
- **Heading** - Calculate the heading (direction) between two points.
- **Area** - Calculate the area enclosed by a polygon defined by the geometry.
- **Distance** - Calculate the distance between two points.
- **Transform** - Apply spatial operations to the geometry.
- **Operation** - Choose an operation to apply to the geometry:
- **As line** - Create a single line feature with a vertex at each row.
- **Line builder** - Create a line between two points.
This transformation allows you to manipulate and analyze geospatial data, enabling operations such as creating lines between points, calculating spatial properties, and more.
Use this transformation to convert time series results into a table, transforming a time series data frame into a **Trend** field. The **Trend** field can then be rendered using the [sparkline cell type][], generating an inline sparkline for each table row. If there are multiple time series queries, each will result in a separate table data frame. These can be joined using join or merge transforms to produce a single table with multiple sparklines per row.
For each generated **Trend** field value, a calculation function can be selected. The default is **Last non-null value**. This value is displayed next to the sparkline and used for sorting table rows.
Use this transformation to create a new data frame containing values predicted by a statistical model. This is useful for finding a trend in chaotic data. It works by fitting a mathematical function to the data, using either linear or polynomial regression. The data frame can then be used in a visualization to display a trendline.
There are two different models:
- **Linear regression** - Fits a linear function to the data.
{{<figuresrc="/static/img/docs/transformations/linear-regression.png"class="docs-image--no-shadow"max-width="1100px"alt="A time series visualization with a straight line representing the linear function">}}
{{<figuresrc="/static/img/docs/transformations/polynomial-regression.png"class="docs-image--no-shadow"max-width="1100px"alt="A time series visualization with a curved line representing the polynomial function">}}
> **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 `regressionTransformation` feature toggle in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
