View a markdown version of this page

AWS::CloudWatch::MetricDataQueryDefinition - AWS CloudFormation

This is the new CloudFormation Template Reference Guide. Please update your bookmarks and links. For help getting started with CloudFormation, see the AWS CloudFormation User Guide.

AWS::CloudWatch::MetricDataQueryDefinition

Creates or updates a metric data query definition.

A metric data query definition saves a metric query so that you can reuse it later. It includes the query expression, the query language, and a path that names the definition and can organize it into folders. When you save a definition, CloudWatch doesn't validate or run its expression.

To create a definition, omit Id. CloudWatch generates the ID and returns it. To update a definition, specify its Id. An update replaces the path, expression, and type, and keeps the creation time.

The path must be unique in your account and Region. If another definition already uses the path, the request fails with a ConflictException.

You can have up to 1,000 metric data query definitions in each Region of your account. A request that would create more fails with a LimitExceededException.

Permissions

To create or update a definition, you need the cloudwatch:PutMetricDataQueryDefinition permission on the metric data query definition resource. The resource ARN has the format arn:aws:cloudwatch:Region:account-id:metric-query-definition/Id.

To add tags when you create a definition, you also need the cloudwatch:TagResource permission. You can use the aws:RequestTag/${TagKey} and aws:TagKeys condition keys to control which tags can be added.

Syntax

To declare this entity in your CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::CloudWatch::MetricDataQueryDefinition", "Properties" : { "Expression" : String, "Path" : String, "Tags" : [ Tag, ... ], "Type" : String } }

YAML

Type: AWS::CloudWatch::MetricDataQueryDefinition Properties: Expression: String Path: String Tags: - Tag Type: String

Properties

Expression

The metric query. It is stored as-is and is not validated.

Required: Yes

Type: String

Minimum: 1

Maximum: 65536

Update requires: No interruption

Path

The path of the metric data query definition.

Required: Yes

Type: String

Minimum: 1

Maximum: 1024

Update requires: No interruption

Tags

An array of key-value pairs to apply to the metric data query definition.

Required: No

Type: Array of Tag

Maximum: 50

Update requires: No interruption

Type

The language of the expression. Valid values are the following:

  • PROMQL – A PromQL query.

  • SQL – A CloudWatch Metrics Insights query.

  • METRIC_MATH – A metric math expression.

Required: Yes

Type: String

Allowed values: PROMQL | SQL | METRIC_MATH

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the value of the Arn property.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn

The Amazon Resource Name (ARN) of the metric data query definition.

CreatedAt

The timestamp when the metric data query definition was created.

Id

The ID of the metric data query definition.

UpdatedAt

The date and time when you last updated the metric data query definition.