StartQuery
Starts a CloudTrail Lake query. Use the QueryStatement
parameter to provide your SQL query, enclosed in single quotation marks. Use the optional
DeliveryS3Uri parameter to deliver the query results to an S3
bucket.
StartQuery requires you specify either the QueryStatement parameter, or a QueryAlias and any QueryParameters. In the current release,
the QueryAlias and QueryParameters parameters are used only for the queries that populate the CloudTrail Lake dashboards.
Request Syntax
{
"DeliveryS3Uri": "string",
"QueryAlias": "string",
"QueryParameters": [ "string" ],
"QueryStatement": "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.
- DeliveryS3Uri
-
The URI for the S3 bucket where CloudTrail delivers the query results.
Type: String
Length Constraints: Maximum length of 1024.
Pattern:
s3://[a-z0-9][\.\-a-z0-9]{1,61}[a-z0-9](/.*)?Required: No
- QueryAlias
-
The alias that identifies a query template.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern:
^[a-zA-Z][a-zA-Z0-9._\-]*$Required: No
- QueryParameters
-
The query parameters for the specified
QueryAlias.Type: Array of strings
Array Members: Minimum number of 1 item. Maximum number of 10 items.
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern:
.*Required: No
- QueryStatement
-
The SQL code of your query.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 10000.
Pattern:
(?s).*Required: No
Response Syntax
{
"QueryId": "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.
- QueryId
-
The ID of the started query.
Type: String
Length Constraints: Fixed length of 36.
Pattern:
^[a-f0-9\-]+$
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
- InactiveEventDataStoreException
-
The event data store is inactive.
HTTP Status Code: 400
- InsufficientEncryptionPolicyException
-
This exception is thrown when the policy on the S3 bucket or AWS KMS key does not have sufficient permissions for the operation.
HTTP Status Code: 400
- InsufficientS3BucketPolicyException
-
This exception is thrown when the policy on the S3 bucket is not sufficient.
HTTP Status Code: 400
- InvalidParameterException
-
The request includes a parameter that is not valid.
HTTP Status Code: 400
- InvalidQueryStatementException
-
The query that was submitted has validation errors, or uses incorrect syntax or unsupported keywords. For more information about writing a query, see Create or edit a query in the AWS CloudTrail User Guide.
HTTP Status Code: 400
- InvalidS3BucketNameException
-
This exception is thrown when the provided S3 bucket name is not valid.
HTTP Status Code: 400
- InvalidS3PrefixException
-
This exception is thrown when the provided S3 prefix is not valid.
HTTP Status Code: 400
- MaxConcurrentQueriesException
-
You are already running the maximum number of concurrent queries. The maximum number of concurrent queries is 10. Wait a minute for some queries to finish, and then run the query again.
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
- S3BucketDoesNotExistException
-
This exception is thrown when the specified S3 bucket does not exist.
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 uses the QueryStatement parameter with the optional
DeliveryS3Uri parameter to deliver the query results to an S3
bucket.
{ "DeliveryS3Uri": "s3://aws-cloudtrail-lake-query-results-123456789012-us-east-1", "QueryStatement": "SELECT eventID, eventTime FROM EXAMPLE-f852-4e8f-8bd1-bcf6cEXAMPLE LIMIT 10" }
Example
The following example uses the QueryAlias and QueryParameters parameters.
{ "QueryAlias": "query-alias", "QueryParameters": [ "EXAMPLE-b8e1-4e93-848f-573b9bfEXAMPLE","2023-05-26T17:47:22.541Z","2023-05-27T17:47:22.541Z" ] }
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
