# Use natural language to generate and update CloudWatch Logs Insights queries


CloudWatch Logs supports a natural language query capability to help you generate and update queries for [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html), [OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html), [OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html), and [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html).

 With this capability, you can ask questions about or describe the CloudWatch Logs data you're looking for in plain English. The natural language capability generates a query based on a prompt that you enter and provides a line-by-line explanation of how the query works. You can also update your query to further investigate your data. 

 Depending on your environment, you can enter prompts like "What are the top 100 source IP addresses by bytes transferred?" and "Find the 10 slowest Lambda function requests." 

**Note**  
The natural-language query feature is a Regional service. For some Regions, the feature makes cross-Region calls to Regions in the United States to process the query prompts. For more information, see [Amazon CloudWatch expands region support for natural language query result summarization and query generation](https://aws.amazon.com/about-aws/whats-new/2025/08/amazon-cloudwatch-region-support-query-result-summarization-query-generation/) . 

 To generate a CloudWatch Logs Insights query with this capability, open the CloudWatch Logs Insights query editor, select the log group you want to query, and choose **Generate query**. 

**Important**  
 To use the natural language query capability, you must be signed in with the [CloudWatchLogsFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsFullAccess.html), [CloudWatchLogsReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsReadOnlyAccess.html), [AdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html), or [ReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html) IAM policies, or have the `cloudwatch:GenerateQuery` permission. 

## Example queries


 The examples in this section describe how to generate and update queries using the natural language capability. 

**Note**  
 For more information on the CloudWatch Logs Insights query editor and syntax, see [CloudWatch Logs Insights query syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html). 

### Examples: Generate a natural language query


 To generate a query using natural language, enter a prompt and choose **Generate new query**. These example shows queries that perform a basic search. 

**Prompt**  
 The following is an example of a prompt that directs the capability to search for the 10 slowest Lambda function invocations. 

```
Find the 10 slowest requests
```

**Query**  
 The following is the query using the CloudWatch Logs Insights query language that the natural language capability generated based on the prompt. Notice how the prompt appears in a comment before the query. After the query, you can read an explanation that describes how the query works. 

```
# Find the 10 slowest requests
fields @timestamp, @message, @duration 
| sort @duration desc 
| limit 10
# This query retrieves the timestamp, message and duration fields from the logs and sorts them in descending order by duration to find the 10 slowest requests.
```

**Note**  
 To turn off the appearance of your prompt and the explanation of how the query works, use the gear icon in your editor. 

**Prompt**  
To generate an OpenSearch SQL query, select the OpenSearch SQL tab, then open the query generator prompt box to enter your natural language prompt. The following is an example of a prompt that uses the natural language capability to generate an OpenSearch SQL query. 

```
Give me the number of errors and exceptions per hour
```

**Query**  
The following is the SQL query generated by that prompt that you can use to find the number of errors and exceptions aggregated per hour:

```
SELECT DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH') AS hour,
       COUNT(*) AS error_count
FROM `/aws/lambda/CloudWatchOdysseyQueryGen`
WHERE `@message` LIKE '%error%'
  OR `@message` LIKE '%exception%'
GROUP BY DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH')
ORDER BY hour
```

**Prompt**  
To generate an OpenSearch PPL query, select the OpenSearch PPL tab, then open the query generator prompt box to enter your natural language prompt. The following is an example of a prompt that uses the natural language capability to generate an OpenSearch PPL query. 

```
Give me all unique exception messages
```

**Query**  
The following is the PPL query generated by that prompt that you can use to find the unique exception messages in your logs:

```
dedup @message 
| fields @message
```

### Example: Update a natural language query


 You can update a query by editing the initial prompt and then choosing **Update query**. 

**Updated prompt**  
 The following example shows an updated version of the previous prompt. Instead of a prompt that searches for the 10 slowest Lambda function invocations, this prompt now directs the capability to search for the 20 slowest Lambda function invocations and include another column for additional log events. 

```
Show top 20 slowest requests instead and display requestId as a column
```

**Updated query**  
 The following is an example of the updated query using the CloudWatch Logs Insights query language. Notice how the updated prompt appears in a comment before the updated query. After the query, you can read an explanation that describes how the original query has been updated. 

```
# Show top 20 slowest requests instead and display requestId as a column
fields @timestamp, @message, @requestId, @duration 
| sort @duration desc 
| limit 20
# This query modifies the original query by replacing the @message field with the @requestId field and changing the limit from 10 to 20 to return the top 20 log events by duration instead of the top 10.
```

## Opting out of using your data for service improvement


 The natural language prompt data you provide to train the AI model and generate relevant queries is used solely to provide and maintain your service. This data might be used to improve the quality of CloudWatch Logs Insights. Your trust and privacy, as well as the security of your content, is our highest priority. For more information, see [AWS Service Terms](https://aws.amazon.com/service-terms/) and [AWS responsible AI policy](https://aws.amazon.com/machine-learning/responsible-ai/policy/). 

 You can opt out of having your content used to develop or improve the quality of natural language queries by creating an AI service opt-out policy. To opt-out of data collection for all CloudWatch Logs AI features, including the query generation capability, you must create an opt-out policy for CloudWatch Logs. For more information, see [AI services opt-out policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html) in the *AWS Organizations User Guide*.