Reference to the retainDimension() and removeDimension() functions

Summary

retainDimension(<tsExpression>, <pointTag1>, <pointTag2>,...<pointTagN>)

removeDimension(<tsExpression>, <pointTag1>, <pointTag2>,...<pointTagN>)

Functions that let you retain or remove dimensions from the query results.

  • retainDimension() allows to explicitly state which dimensions you want to see in the query output.
  • removeDimension() allows to explicitly state which dimensions you want to remove from the query output.

For each function, you have to specify at least one ts() expression and at least one point tag value as a dimension. If dropping the dimension is impossible, you will see an error message, such as Data not unique after dropping dimension.

Parameters

ParameterDescription
tsExpression A query expression.
pointTag1, pointTag2 Point tag values to use as dimensions.

Description

Functions that let you retain or remove dimensions (point tags) from the query results.

Examples

You can remove the env dimension from a query of the type:

ts(~sample.cpu.usage.*)

This sample query has 4 dimensions, such as source, metric, availability zone (az), and environment (env).

A chart created with the sample query with 4 dimensions shown in the pinned legend - source, metric, availability zone and environment.

To remove the env dimension, use the removeDimension() function and include the env tag:

removeDimension(ts(~sample.cpu.usage.*), env)

A chart created with the above query after applying the removeDimension function with the environment dimension removed from the pinned legend.

To retain only the source and metrics dimensions in the query, and remove the env and az dimensions, use the retainDimension() function and include the hosts and metrics tags, which are the dimensions that will be explicitly kept:

retainDimension(ts(~sample.cpu.usage.*), hosts, metrics)

A chart created with the above query after applying the retainDimension function with the environment and availability zone dimensions removed from the pinned legend.