Package software.amazon.awscdk.services.cloudwatch

Class SearchExpression

java.lang.Object
software.amazon.jsii.JsiiObject
software.amazon.awscdk.services.cloudwatch.SearchExpression
All Implemented Interfaces:
IMetric, software.amazon.jsii.JsiiSerializable
@Generated(value="jsii-pacmak/1.112.0 (build de1bc80)", date="2025-07-29T17:50:57.116Z") @Stability(Stable) public class SearchExpression extends software.amazon.jsii.JsiiObject implements IMetric
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: 

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

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.

Example: 

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

  • Constructor Details

    • SearchExpression

      protected SearchExpression(software.amazon.jsii.JsiiObjectRef objRef)

    • SearchExpression

      protected SearchExpression(software.amazon.jsii.JsiiObject.InitializationMode initializationMode)

    • SearchExpression

      @Stability(Stable) public SearchExpression(@NotNull SearchExpressionProps props)
      Parameters:
      props - This parameter is required.

  • Method Details

    • toMetricConfig

      @Stability(Stable) @NotNull public MetricConfig toMetricConfig()
      Inspect the details of the metric object.
      Specified by:
      toMetricConfig in interface IMetric

    • toString

      @Stability(Stable) @NotNull public String toString()
      Returns a string representation of an object.
      Overrides:
      toString in class Object

    • with

      @Stability(Stable) @NotNull public SearchExpression with(@NotNull SearchExpressionOptions props)
      Return a copy of SearchExpression with properties changed.

      All properties except expression can be changed.

      Parameters:
      props - The set of properties to change. This parameter is required.

    • getExpression

      @Stability(Stable) @NotNull public String getExpression()
      The search expression defining the metrics to be retrieved.

    • getPeriod

      @Stability(Stable) @NotNull public Duration getPeriod()
      The aggregation period for the metrics produced by the Search Expression.

    • getColor

      @Stability(Stable) @Nullable public String getColor()
      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.

    • getLabel

      @Stability(Stable) @Nullable public String getLabel()
      The label is used as a prefix for the title of each metric returned by the search expression.

    • getSearchAccount

      @Stability(Stable) @Nullable public String getSearchAccount()
      Account to evaluate search expressions within.

    • getSearchRegion

      @Stability(Stable) @Nullable public String getSearchRegion()
      Region to evaluate search expressions within.

    • getWarnings

      @Stability(Deprecated) @Deprecated @Nullable public List<String> getWarnings()
      Deprecated.
      • use warningsV2
      (deprecated) Warnings generated by this search expression.

      Specified by:
      getWarnings in interface IMetric

    • getWarningsV2

      @Stability(Stable) @Nullable public Map<String,String> getWarningsV2()
      Warnings generated by this search expression.
      Specified by:
      getWarningsV2 in interface IMetric