CloudWatch / Client / put_metric_data_query_definition
put_metric_data_query_definition¶
- CloudWatch.Client.put_metric_data_query_definition(**kwargs)¶
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 itsId. 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:PutMetricDataQueryDefinitionpermission on the metric data query definition resource. The resource ARN has the formatarn:aws:cloudwatch:Region:account-id:metric-query-definition/Id.To add tags when you create a definition, you also need the
cloudwatch:TagResourcepermission. You can use theaws:RequestTag/${TagKey}andaws:TagKeyscondition keys to control which tags can be added.See also: AWS API Documentation
Request Syntax
response = client.put_metric_data_query_definition( Id='string', Path='string', Expression='string', Type='PROMQL'|'SQL'|'METRIC_MATH', Tags=[ { 'Key': 'string', 'Value': 'string' }, ] )
- Parameters:
Id (string) – 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.
Path (string) –
[REQUIRED]
The name of the metric data query definition. Use slashes (
/) to organize definitions into folders, for exampleteam/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.
Expression (string) –
[REQUIRED]
The query expression, in the language that
Typespecifies. CloudWatch doesn’t validate or run the expression when you save it.Type (string) –
[REQUIRED]
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.
Tags (list) –
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, useTagResourceandUntagResource.(dict) –
A key-value pair associated with a CloudWatch resource.
Key (string) – [REQUIRED]
A string that you can use to assign a value. The combination of tag keys and values can help you organize and categorize your resources.
Value (string) – [REQUIRED]
The value for the specified tag key.
- Return type:
dict
- Returns:
Response Syntax
{ 'Id': 'string', 'Arn': 'string', 'Path': 'string', 'Expression': 'string', 'Type': 'PROMQL'|'SQL'|'METRIC_MATH', 'CreatedAt': datetime(2015, 1, 1), 'UpdatedAt': datetime(2015, 1, 1) }
Response Structure
(dict) –
Id (string) –
The ID of the metric data query definition.
Arn (string) –
The Amazon Resource Name (ARN) of the metric data query definition.
Path (string) –
The path of the metric data query definition.
Expression (string) –
The query expression.
Type (string) –
The language of the expression.
CreatedAt (datetime) –
The date and time when you created the metric data query definition.
UpdatedAt (datetime) –
The date and time when you last updated the metric data query definition.
Exceptions