2024-02-28 01:41:55 +08:00
import { writeFileSync , readFileSync , read } from 'fs' ;
import { resolve } from 'path' ;
2023-10-25 00:30:10 +08:00
import {
transformationDocsContent ,
TransformationDocsContentType ,
ImageRenderType ,
} from '../../public/app/features/transformers/docs/content' ;
2024-02-28 01:41:55 +08:00
const WRITE_PATH = 'docs/sources/panels-visualizations/query-transform-data/transform-data/index.md' ;
2023-10-26 02:09:33 +08:00
2024-02-28 01:41:55 +08:00
export const readMeContent = `
2023-10-26 02:09:33 +08:00
To update this Markdown , navigate to the following Typescript files and edit them based on what you need to update :
scripts / docs / generate - transformations . ts - Includes all content not specific to a transformation .
public / app / features / transformers / docs / content . ts - Transformation - specific content .
Only use reference style links in the 'content.ts' file or else link text will be visible in the UI .
2023-10-25 00:30:10 +08:00
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 .
2024-02-28 01:41:55 +08:00
` ;
export const templateMetaContent = ` ---
comments : |
This Markdown file is auto - generated . DO NOT EDIT THIS FILE DIRECTLY .
$ { readMeContent }
2023-10-25 00:30:10 +08:00
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
2024-05-10 01:00:59 +08:00
description : Use transformations to rename fields , join time series / SQL - like data , apply mathematical operations , and more
2023-10-25 00:30:10 +08:00
weight : 100
2024-06-14 22:44:29 +08:00
refs :
sparkline - cell - type :
- pattern : / d o c s / g r a f a n a /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / p a n e l s - v i s u a l i z a t i o n s / v i s u a l i z a t i o n s / t a b l e / # s p a r k l i n e
- pattern : / d o c s / g r a f a n a - c l o u d /
2024-06-15 00:27:22 +08:00
destination : / d o c s / g r a f a n a - c l o u d / v i s u a l i z a t i o n s / p a n e l s - v i s u a l i z a t i o n s / v i s u a l i z a t i o n s / t a b l e / # s p a r k l i n e
2024-06-14 22:44:29 +08:00
calculation - types :
- pattern : / d o c s / g r a f a n a /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / p a n e l s - v i s u a l i z a t i o n s / q u e r y - t r a n s f o r m - d a t a / c a l c u l a t i o n - t y p e s /
- pattern : / d o c s / g r a f a n a - c l o u d /
destination : / d o c s / g r a f a n a - c l o u d / v i s u a l i z a t i o n s / p a n e l s - v i s u a l i z a t i o n s / q u e r y - t r a n s f o r m - d a t a / c a l c u l a t i o n - t y p e s /
configuration - file :
- pattern : / d o c s / g r a f a n a /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / s e t u p - g r a f a n a / c o n f i g u r e - g r a f a n a / # c o n f i g u r a t i o n - f i l e - l o c a t i o n
- pattern : / d o c s / g r a f a n a - c l o u d /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / s e t u p - g r a f a n a / c o n f i g u r e - g r a f a n a / # c o n f i g u r a t i o n - f i l e - l o c a t i o n
dashboard - variable :
- pattern : / d o c s / g r a f a n a /
2024-06-15 00:27:22 +08:00
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / d a s h b o a r d s / v a r i a b l e s /
2024-06-14 22:44:29 +08:00
- pattern : / d o c s / g r a f a n a - c l o u d /
2024-06-15 00:27:22 +08:00
destination : / d o c s / g r a f a n a - c l o u d / v i s u a l i z a t i o n s / d a s h b o a r d s / v a r i a b l e s /
2024-06-14 22:44:29 +08:00
feature - toggle :
- pattern : / d o c s / g r a f a n a /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / s e t u p - g r a f a n a / c o n f i g u r e - g r a f a n a / # f e a t u r e _ t o g g l e s
- pattern : / d o c s / g r a f a n a - c l o u d /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / s e t u p - g r a f a n a / c o n f i g u r e - g r a f a n a / # f e a t u r e _ t o g g l e s
table - panel :
- pattern : / d o c s / g r a f a n a /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / p a n e l s - v i s u a l i z a t i o n s / v i s u a l i z a t i o n s / t a b l e /
- pattern : / d o c s / g r a f a n a - c l o u d /
2024-06-15 00:27:22 +08:00
destination : / d o c s / g r a f a n a - c l o u d / v i s u a l i z a t i o n s / p a n e l s - v i s u a l i z a t i o n s / v i s u a l i z a t i o n s / t a b l e /
2024-06-14 22:44:29 +08:00
time - series - panel :
- pattern : / d o c s / g r a f a n a /
destination : / d o c s / g r a f a n a / < G R A F A N A _ V E R S I O N > / p a n e l s - v i s u a l i z a t i o n s / v i s u a l i z a t i o n s / t i m e - s e r i e s /
- pattern : / d o c s / g r a f a n a - c l o u d /
2024-06-15 00:27:22 +08:00
destination : / d o c s / g r a f a n a - c l o u d / v i s u a l i z a t i o n s / p a n e l s - v i s u a l i z a t i o n s / v i s u a l i z a t i o n s / t i m e - s e r i e s /
2024-02-28 01:41:55 +08:00
-- - ` ;
2023-10-25 00:30:10 +08:00
2024-02-28 01:41:55 +08:00
const templateIntroContent = ` # Transform data
2023-10-25 00:30:10 +08:00
Transformations are a powerful way to manipulate data returned by a query before the system applies a visualization . Using transformations , you can :
- Rename fields
2024-05-10 01:00:59 +08:00
- Join time series / SQL - like data
2023-10-25 00:30:10 +08:00
- Perform mathematical operations across queries
- Use the output of one transformation as the input to another transformation
2025-07-21 20:43:33 +08:00
{ { < docs / learning - journeys title = "Transform data in a Grafana Cloud dashboard" url = "https://grafana.com/docs/learning-journeys/data-transformation/" > } }
2023-10-25 00:30:10 +08:00
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 .
2025-03-07 22:55:39 +08:00
# # Dashboard variables in transformations
All text input fields in transformations accept [ variable syntax ] ( ref :dashboard - variable ) :
{ { < figure src = "/media/docs/grafana/panels-visualizations/screenshot-transformation-variables-v11.6.png" alt = "Transformation with a mock variable in a text field" > } }
When you use dashboard variables in transformations , the variables are automatically interpolated before the transformations are applied to the data .
For an example , refer to [ Use a dashboard variable ] ( # use - a - dashboard - variable ) in the * * Filter fields by name * * transformation .
2023-10-25 00:30:10 +08:00
# # 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 .
2023-12-13 01:07:52 +08:00
{ { < figure src = "/static/img/docs/transformations/transformations-7-0.png" class = "docs-image--no-shadow" max - width = "1100px" alt = "Transform tab in the panel editor" > } }
2023-10-25 00:30:10 +08:00
# # 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 .
2023-12-13 01:07:52 +08:00
{ { < figure src = "/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" > } }
2023-10-25 00:30:10 +08:00
# # 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 .
2023-12-13 01:07:52 +08:00
{ { < figure src = "/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" > } }
2023-10-25 00:30:10 +08:00
# # 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 .
2024-02-20 21:46:38 +08:00
You can also filter by annotations ( which includes exemplars ) to apply transformations to them . When you do so , the list of fields changes to reflect those in the annotation or exemplar tooltip .
The filter icon is always displayed if your panel has more than one query or source of data ( that is , panel or annotation data ) 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 .
2023-10-25 00:30:10 +08:00
# # 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 .
2023-12-15 04:18:16 +08:00
{ { < figure src = "/static/img/docs/transformations/screenshot-example-remove-transformation.png" class = "docs-image--no-shadow" max - width = "1100px" alt = "A transformation row with the remove transformation icon highlighted" > } }
2024-02-28 01:41:55 +08:00
` ;
export const completeTemplate = ` ${ templateMetaContent }
2023-10-25 00:30:10 +08:00
2024-02-28 01:41:55 +08:00
$ { templateIntroContent }
2023-10-25 00:30:10 +08:00
# # Transformation functions
You can perform the following transformations on your data .
$ { buildTransformationDocsContent ( transformationDocsContent ) }
2024-06-14 22:44:29 +08:00
[ Table panel ] : ref :table - panel
[ Calculation types ] : ref :calculation - types
[ sparkline cell type ] : ref :sparkline - cell - type
[ configuration file ] : ref :configuration - file
[ Time series panel ] : ref :time - series - panel
[ feature toggle ] : ref :feature - toggle
[ dashboard variable ] : ref :dashboard - variable
2023-10-25 00:30:10 +08:00
` ;
function buildTransformationDocsContent ( transformationDocsContent : TransformationDocsContentType ) {
const transformationsList = Object . keys ( transformationDocsContent ) ;
const content = transformationsList
. map ( ( transformationName ) = > {
return `
2024-02-28 01:41:55 +08:00
# # # $ { transformationDocsContent [ transformationName ] . name }
$ { transformationDocsContent [ transformationName ] . getHelperDocs ( ImageRenderType . ShortcodeFigure ) } ` ;
2023-10-25 00:30:10 +08:00
} )
// Remove the superfluous commas.
. join ( '' ) ;
return content ;
}
2024-02-28 01:41:55 +08:00
export function getMarkdownContent ( ) : string {
const rootDir = resolve ( __dirname , '../../' ) ;
const pathToMarkdown = resolve ( rootDir , WRITE_PATH ) ;
return readFileSync ( pathToMarkdown , 'utf-8' ) ;
}
export function getJavaScriptContent ( ) : string {
return completeTemplate ;
}
2025-03-07 22:55:39 +08:00
// Build the path to the Markdown file.
const indexPath = resolve ( __dirname , '../../' + WRITE_PATH ) ;
// Write content to the Markdown file.
writeFileSync ( indexPath , completeTemplate , 'utf-8' ) ;
