# SearchExpression

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:
```ts
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.

Extends: SearchExpression
Implements: IMetric

- Source: [`aws-cloudwatch/lib/metric.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts#L999)
- Type last changed: v2.207.0 · 24 Jul 2025

## Example

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

## Initializer

```ts
new SearchExpression(props: SearchExpressionProps)
```

## Properties

- `color`: 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.

- `expression`: string — The search expression defining the metrics to be retrieved.

- `label`: string — The label is used as a prefix for the title of each metric returned by the search expression.

- `period`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — The aggregation period for the metrics produced by the Search Expression.

- `searchAccount`: string — Account to evaluate search expressions within.

- `searchRegion`: string — Region to evaluate search expressions within.

- `warnings`: string[] — - use warningsV2

- `warningsV2`: { [key: string]: string } — Warnings generated by this search expression.

## Methods

- `toMetricConfig(): MetricConfig` — Inspect the details of the metric object.

- `toString(): string` — Returns a string representation of an object.

- `with(props: SearchExpressionOptions): SearchExpression // chainable` — Return a copy of SearchExpression with properties changed.

  All properties except expression can be changed.

  **Parameters**

  - `props` — The set of properties to change.