Amazon CloudWatch

Lists the metric data query definitions in your account and Region.

The results are summaries that don't include the expression. To get the full definition, call GetMetricDataQueryDefinition with its ID.

This operation supports pagination. Use the MaxResults and NextToken parameters to retrieve results in multiple calls.

Permissions

To list definitions, you need the cloudwatch:ListMetricDataQueryDefinitions permission. This permission applies to all definitions in the account and Region. The results aren't filtered by tags.

See also: AWS API Documentation

Request Syntax

client.list_metric_data_query_definitions(
    MaxResults=123,
    NextToken='string'
)

type MaxResults:

integer

param MaxResults:

The maximum number of metric data query definitions to return in one call. The default is 100.

type NextToken:

string

param NextToken:

The token returned by a previous call to indicate where to continue retrieving results.

rtype:

dict

returns:

Response Syntax

{
    'Items': [
        {
            'Id': 'string',
            'Path': 'string',
            'Type': 'PROMQL'|'SQL'|'METRIC_MATH',
            'UpdatedAt': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

• (dict) --

  • Items (list) --

    A list of metric data query definition summaries.

    • (dict) --

      Summary information about a metric data query definition. To get the expression, call GetMetricDataQueryDefinition.

      • Id (string) --

        The ID of the metric data query definition.

      • Path (string) --

        The path of the metric data query definition.

      • Type (string) --

        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.

      • UpdatedAt (datetime) --

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

  • NextToken (string) --

    The token to use when requesting the next set of results. If this field is absent, there are no more results to retrieve.

Deletes a metric data query definition.

This operation is idempotent. If the definition doesn't exist, the operation succeeds without returning an error.

Permissions

To delete a definition, you need the cloudwatch:DeleteMetricDataQueryDefinition permission on the metric data query definition resource. You can use the aws:ResourceTag/${TagKey} condition key to control access based on the tags of the definition.

See also: AWS API Documentation

Request Syntax

client.delete_metric_data_query_definition(
    Id='string'
)

type Id:

string

param Id:

[REQUIRED]

The ID of the metric data query definition to delete.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

Returns a metric data query definition, including its expression.

Permissions

To get a definition, you need the cloudwatch:GetMetricDataQueryDefinition permission on the metric data query definition resource. You can use the aws:ResourceTag/${TagKey} condition key to control access based on the tags of the definition.

See also: AWS API Documentation

Request Syntax

client.get_metric_data_query_definition(
    Id='string'
)

type Id:

string

param Id:

[REQUIRED]

The ID of the metric data query definition to retrieve.

rtype:

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. Valid values are the following:

    • PROMQL – A PromQL query.

    • SQL – A CloudWatch Metrics Insights query.

    • METRIC_MATH – A metric math 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.

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.

See also: AWS API Documentation

Request Syntax

client.put_metric_data_query_definition(
    Id='string',
    Path='string',
    Expression='string',
    Type='PROMQL'|'SQL'|'METRIC_MATH',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)

type Id:

string

param 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 Path:

string

param Path:

[REQUIRED]

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 Expression:

string

param Expression:

[REQUIRED]

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

type Type:

string

param Type:

[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.

type Tags:

list

param 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.

• (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.

rtype:

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.