aws-cdk-lib.aws_cloudwatch.SearchExpression

SearchExpression Class

A CloudWatch search expression for dynamically finding and graphing multiple related metrics.

Search expressions allow you to search for and graph multiple related metrics from a single expression. This is particularly useful in dynamic environments where the exact metric names or dimensions may not be known at deployment time.

Example:

const searchExpression = new cloudwatch.SearchExpression({
  expression: "SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)",
  label: 'EC2 CPU Utilization',
  period: Duration.minutes(5),
});

This class does not represent a resource, so hence is not a construct. Instead, SearchExpression is an abstraction that makes it easy to specify metrics for use in graphs.

SearchExpression

implements

• IMetric

Source

aws-cloudwatch/lib/metric.ts

Type last changed

v2.207.0 · 24 Jul 2025

Example

const cpuUtilization = new cloudwatch.SearchExpression({
  expression: "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 900)",
  label: 'EC2 CPU Utilization',
  color: '#ff7f0e',
});

cpu_utilization = cloudwatch.SearchExpression(
    expression="SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 900)",
    label="EC2 CPU Utilization",
    color="#ff7f0e"
)

SearchExpression cpuUtilization = SearchExpression.Builder.create()
        .expression("SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 900)")
        .label("EC2 CPU Utilization")
        .color("#ff7f0e")
        .build();

// Install: dotnet add package Amazon.CDK.Lib
var cpuUtilization = new SearchExpression(new SearchExpressionProps {
    Expression = "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 900)",
    Label = "EC2 CPU Utilization",
    Color = "#ff7f0e"
});

// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
cpuUtilization := cloudwatch.NewSearchExpression(&SearchExpressionProps{
	Expression: jsii.String("SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 900)"),
	Label: jsii.String("EC2 CPU Utilization"),
	Color: jsii.String("#ff7f0e"),
})

Initializer

new SearchExpression(props: SearchExpressionProps)

SearchExpression(props: SearchExpressionProps)

new SearchExpression(SearchExpressionProps props)

new SearchExpression(SearchExpressionProps props)

NewSearchExpression(Props SearchExpressionProps)

Properties

color?may be undefinedstringcolor?may be undefinedstrcolor?may be undefinedStringColor?may be undefinedstringColor?may be undefined*string#

Hex color code (e.g. '#00ff00'), to use when rendering the resulting metrics in a graph. If multiple time series are returned, color is assigned to the first metric, color for the other metrics is automatically assigned.

expressionstringexpressionstrexpressionStringExpressionstringExpression*stringrequired#

The search expression defining the metrics to be retrieved.

label?may be undefinedstringlabel?may be undefinedstrlabel?may be undefinedStringLabel?may be undefinedstringLabel?may be undefined*string#

The label is used as a prefix for the title of each metric returned by the search expression.

periodDurationperiodDurationperiodDurationPeriodDurationPeriodDurationrequired#

The aggregation period for the metrics produced by the Search Expression.

searchAccount?may be undefinedstringsearch_account?may be undefinedstrsearchAccount?may be undefinedStringSearchAccount?may be undefinedstringSearchAccount?may be undefined*string#

Account to evaluate search expressions within.

searchRegion?may be undefinedstringsearch_region?may be undefinedstrsearchRegion?may be undefinedStringSearchRegion?may be undefinedstringSearchRegion?may be undefined*string#

Region to evaluate search expressions within.

warnings?may be undefinedstring[]warnings?may be undefinedtyping.List[str]warnings?may be undefinedList<String>Warnings?may be undefinedstring[]Warnings?may be undefined*[]*stringdeprecated#

- use warningsV2

warningsV2?may be undefined{ [key: string]: string }warnings_v2?may be undefinedtyping.Mapping[str, str]warningsV2?may be undefinedMap<String, String>WarningsV2?may be undefinedIDictionary<string, string>WarningsV2?may be undefined*map[string]*string#

Warnings generated by this search expression.

Methods

toMetricConfig(): MetricConfigdef to_metric_config(self, ) -> MetricConfigpublic MetricConfig toMetricConfig()public MetricConfig ToMetricConfig()func ToMetricConfig() MetricConfig#

Inspect the details of the metric object.

toString(): stringdef to_string(self, ) -> strpublic String toString()public string ToString()func ToString() *string#

Returns a string representation of an object.

with(props: SearchExpressionOptions): SearchExpression // chainabledef with(self, props: SearchExpressionOptions) -> SearchExpressionpublic SearchExpression with(SearchExpressionOptions props)public SearchExpression With(SearchExpressionOptions props)func With(Props SearchExpressionOptions) SearchExpression#

Return a copy of SearchExpression with properties changed.

All properties except expression can be changed.

1 parameter

Parameters

• propspropspropspropsProps — The set of properties to change.