Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

PutMetricDataQueryDefinition

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.

Request Syntax


{
   "Expression": "string",
   "Id": "string",
   "Path": "string",
   "Tags": [ 
      { 
         "Key": "string",
         "Value": "string"
      }
   ],
   "Type": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Expression

The query expression, in the language that Type specifies. CloudWatch doesn't validate or run the expression when you save it.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 65536.

Required: Yes

Id

The ID of the metric data query definition to update. Omit this parameter to create a definition. CloudWatch then generates the ID and returns it in the response.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9-]{1,64}

Required: No

Path

The name of the metric data query definition. Use slashes (/) to organize definitions into folders, for example team/web/latency. The path must meet the following requirements:

It must be unique in your account and Region.
It can't start or end with a slash.
It can't contain an empty folder name (//).
It can be at most 1,015 bytes when encoded as UTF-8.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: [\p{L}\p{M}\p{N}\p{P}\p{S}\p{Zs}]+

Required: Yes

Tags

A list of key-value pairs to associate with the metric data query definition. You can use tags to categorize definitions and to control access to them. Tags are applied only when the request creates a definition, that is, when you omit Id. To change the tags of an existing definition, use TagResource and UntagResource.

Type: Array of Tag objects

Required: No

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.

Type: String

Valid Values: PROMQL | SQL | METRIC_MATH

Required: Yes

Response Syntax


{
   "Arn": "string",
   "CreatedAt": number,
   "Expression": "string",
   "Id": "string",
   "Path": "string",
   "Type": "string",
   "UpdatedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Arn

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

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

CreatedAt

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

Type: Timestamp

Expression

The query expression.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 65536.

Id

The ID of the metric data query definition.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9-]{1,64}

Path

The path of the metric data query definition.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Pattern: [\p{L}\p{M}\p{N}\p{P}\p{S}\p{Zs}]+

Type

The language of the expression.

Type: String

Valid Values: PROMQL | SQL | METRIC_MATH

UpdatedAt

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

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Error Types.

ConflictException

This operation attempted to create a resource that already exists.

HTTP Status Code: 409

LimitExceededException

The operation exceeded one or more limits.

HTTP Status Code: 400

ResourceNotFoundException

The named resource does not exist.

HTTP Status Code: 404

Examples

Example – Create a metric data query definition

The following AWS CLI command saves a CloudWatch Metrics Insights query that finds the 10 EC2 instances with the highest average CPU utilization. Replace the path and the expression with your own values. The JSON response follows the command.

Sample Request



PROMPT> aws cloudwatch put-metric-data-query-definition \
    --path "ec2/top-cpu-instances" \
    --type SQL \
    --expression 'SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) GROUP BY InstanceId ORDER BY AVG() DESC LIMIT 10'

Sample Response



{
    "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Arn": "arn:aws:cloudwatch:us-east-1:111122223333:metric-query-definition/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Path": "ec2/top-cpu-instances",
    "Expression": "SELECT AVG(CPUUtilization) FROM SCHEMA(\"AWS/EC2\", InstanceId) GROUP BY InstanceId ORDER BY AVG() DESC LIMIT 10",
    "Type": "SQL",
    "CreatedAt": "2026-11-09T10:30:00Z",
    "UpdatedAt": "2026-11-09T10:30:00Z"
}

Example – Create a metric data query definition with tags

The following AWS CLI command saves a metric math expression that finds the CPU utilization of every EC2 instance, and tags the new definition. Replace the path, the expression, and the tag with your own values. The JSON response follows the command.

Sample Request



PROMPT> aws cloudwatch put-metric-data-query-definition \
    --path "ec2/cpu-all-instances" \
    --type METRIC_MATH \
    --expression "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)" \
    --tags Key=Team,Value=Platform

Sample Response



{
    "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "Arn": "arn:aws:cloudwatch:us-east-1:111122223333:metric-query-definition/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "Path": "ec2/cpu-all-instances",
    "Expression": "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)",
    "Type": "METRIC_MATH",
    "CreatedAt": "2026-11-08T16:45:00Z",
    "UpdatedAt": "2026-11-08T16:45:00Z"
}

Example – Update a metric data query definition

The following AWS CLI command replaces the expression of an existing definition. Replace the ID, the path, and the expression with your own values. The JSON response follows the command.

Sample Request



PROMPT> aws cloudwatch put-metric-data-query-definition \
    --id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
    --path "ec2/top-cpu-instances" \
    --type SQL \
    --expression 'SELECT MAX(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) GROUP BY InstanceId ORDER BY MAX() DESC LIMIT 10'

Sample Response



{
    "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Arn": "arn:aws:cloudwatch:us-east-1:111122223333:metric-query-definition/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Path": "ec2/top-cpu-instances",
    "Expression": "SELECT MAX(CPUUtilization) FROM SCHEMA(\"AWS/EC2\", InstanceId) GROUP BY InstanceId ORDER BY MAX() DESC LIMIT 10",
    "Type": "SQL",
    "CreatedAt": "2026-11-09T10:30:00Z",
    "UpdatedAt": "2026-11-10T08:15:00Z"
}