GenerateQuery
Generates a query from a natural language prompt. This operation uses generative artificial intelligence (generative AI) to produce a ready-to-use SQL query from the prompt.
The prompt can be a question or a statement about the event data in your event data store. For example, you can enter prompts like "What are my top errors in the past month?" and “Give me a list of users that used SNS.”
The prompt must be in English. For information about limitations, permissions, and supported Regions, see Create CloudTrail Lake queries from natural language prompts in the AWS CloudTrail user guide.
Note
Do not include any personally identifying, confidential, or sensitive information in your prompts.
This feature uses generative AI large language models (LLMs); we recommend double-checking the LLM response.
Request Syntax
{
"EventDataStores": [ "string" ],
"Prompt": "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.
- EventDataStores
-
The ARN (or ID suffix of the ARN) of the event data store that you want to query. You can only specify one event data store.
Type: Array of strings
Array Members: Fixed number of 1 item.
Length Constraints: Minimum length of 3. Maximum length of 256.
Pattern:
^[a-zA-Z0-9._/\-:]+$Required: Yes
- Prompt
-
The prompt that you want to use to generate the query. The prompt must be in English. For example prompts, see Example prompts in the AWS CloudTrail user guide.
Type: String
Length Constraints: Minimum length of 3. Maximum length of 500.
Pattern:
^[ -~\n]*$Required: Yes
Response Syntax
{
"EventDataStoreOwnerAccountId": "string",
"QueryAlias": "string",
"QueryStatement": "string"
}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.
- EventDataStoreOwnerAccountId
-
The account ID of the event data store owner.
Type: String
Length Constraints: Minimum length of 12. Maximum length of 16.
Pattern:
\d+ - QueryAlias
-
An alias that identifies the prompt. When you run the
StartQueryoperation, you can pass in either theQueryAliasorQueryStatementparameter.Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern:
^[a-zA-Z][a-zA-Z0-9._\-]*$ - QueryStatement
-
The SQL query statement generated from the prompt.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 10000.
Pattern:
(?s).*
Errors
For information about the errors that are common to all actions, see Common Errors.
- EventDataStoreARNInvalidException
-
The specified event data store ARN is not valid or does not map to an event data store in your account.
HTTP Status Code: 400
- EventDataStoreNotFoundException
-
The specified event data store was not found.
HTTP Status Code: 400
- GenerateResponseException
-
This exception is thrown when a valid query could not be generated for the provided prompt.
HTTP Status Code: 400
- InactiveEventDataStoreException
-
The event data store is inactive.
HTTP Status Code: 400
- InvalidParameterException
-
The request includes a parameter that is not valid.
HTTP Status Code: 400
- NoManagementAccountSLRExistsException
-
This exception is thrown when the management account does not have a service-linked role.
HTTP Status Code: 400
- OperationNotPermittedException
-
This exception is thrown when the requested operation is not permitted.
HTTP Status Code: 400
- UnsupportedOperationException
-
This exception is thrown when the requested operation is not supported.
HTTP Status Code: 400
Examples
Example
The following example provides the prompt "Show me all console login events for the past week" to generate a query for the specified event data store.
{
"EventDataStores": [ "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLE-ee54-4813-92d5-999aeEXAMPLE" ],
"Prompt": "Show me all console login events for the past week"
}See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
