# SearchExpressionProps

Properties for a SearchExpression.

Extends: [SearchExpressionOptions](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.SearchExpressionOptions.html)
Used as props by: [SearchExpression](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.SearchExpression.html)

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

## Example

TypeScript:

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

Python:

```python
search_expression = cloudwatch.SearchExpression(
    expression="SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)",
    label="EC2 CPU Utilization",
    period=Duration.minutes(5)
)
```

Java:

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

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
var searchExpression = new SearchExpression(new SearchExpressionProps {
    Expression = "SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)",
    Label = "EC2 CPU Utilization",
    Period = Duration.Minutes(5)
});
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
searchExpression := cloudwatch.NewSearchExpression(&SearchExpressionProps{
	Expression: jsii.String("SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)"),
	Label: jsii.String("EC2 CPU Utilization"),
	Period: awscdk.Duration_Minutes(jsii.Number(5)),
})
```

## Properties

- `color`: string — Color for the metric produced by the search expression.

  **Default:** Automatically assigned.

  If the search expression produces more than one time series, the color is assigned to the first one.
  Other metrics are assigned colors automatically.

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

  A search expression cannot be used within an Alarm.

  A search expression allows you to retrieve and graph multiple related metrics in a single statement.
  It can return up to 500 time series.

  Examples:
  - `SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)`
  - `SEARCH('{AWS/ApplicationELB,LoadBalancer} RequestCount', 'Sum', 60)`
  - `SEARCH('{MyNamespace,ServiceName} Errors', 'Sum')`

  For more information about search expression syntax, see:
  https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/search-expression-syntax.html

- `label`: string — Label for this search expression when added to a Graph in a Dashboard.

  **Default:** No label.

  If this expression evaluates to more than one time series,
  each time series will appear in the graph using a combination of the
  expression label and the individual metric label. Specify the empty
  string (`''`) to suppress the expression label and only keep the
  metric label.

  You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
  to show summary information about the displayed time series
  in the legend. For example, if you use:

  ```
  [max: ${MAX}] MyMetric
  ```

  As the metric label, the maximum value in the visible range will
  be shown next to the time series name in the graph's legend. If the
  search expression produces more than one time series, the maximum
  will be shown for each individual time series produce by this
  search expression.

- `period`: [Duration](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.minutes(5) — The period over which the search expression's statistics are applied.

  This period overrides the period defined within the search expression.

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

  **Default:** Deployment account.

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

  **Default:** Deployment region.

- `visible`: boolean = true — Whether the time series produced by this search expression should be visible in dashboard graphs.

  Setting this to false keeps the time series on the widget without rendering
  them, so they can still be toggled on in the CloudWatch console.
