Query - Amazon Timestream


Query is a synchronous operation that enables you to execute a query. Query will timeout after 60 seconds. You must update the default timeout in the SDK to support a timeout of 60 seconds. The result set will be truncated to 1MB. Service quotas apply. For more information, see Quotas in the Timestream Developer Guide.

Request Syntax

{ "ClientToken": "string", "MaxRows": number, "NextToken": "string", "QueryString": "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.


Unique, case-sensitive string of up to 64 ASCII characters that you specify when you make a Query request. Providing a ClientToken makes the call to Query idempotent, meaning that multiple identical calls have the same effect as one single call.

Your query request will fail in the following cases:

  • If you submit a request with the same client token outside the 5-minute idepotency window.

  • If you submit a request with the same client token but a change in other parameters within the 5-minute idempotency window.

After 4 hours, any request with the same client token is treated as a new request.

Type: String

Length Constraints: Minimum length of 32. Maximum length of 128.

Required: No


The total number of rows to return in the output. If the total number of rows available is more than the value specified, a NextToken is provided in the command's output. To resume pagination, provide the NextToken value in the starting-token argument of a subsequent command.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: No


A pagination token passed to get a set of results.

Type: String

Required: No


The query to be executed by Timestream.

Type: String

Required: Yes

Response Syntax

{ "ColumnInfo": [ { "Name": "string", "Type": { "ArrayColumnInfo": "ColumnInfo", "RowColumnInfo": [ "ColumnInfo" ], "ScalarType": "string", "TimeSeriesMeasureValueColumnInfo": "ColumnInfo" } } ], "NextToken": "string", "QueryId": "string", "QueryStatus": { "CumulativeBytesMetered": number, "CumulativeBytesScanned": number, "ProgressPercentage": number }, "Rows": [ { "Data": [ { "ArrayValue": [ "Datum" ], "NullValue": boolean, "RowValue": "Row", "ScalarValue": "string", "TimeSeriesValue": [ { "Time": "string", "Value": "Datum" } ] } ] } ] }

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.


The column data types of the returned result set.

Type: Array of ColumnInfo objects


A pagination token that can be used again on a Query call to get the next set of results.

Type: String


A unique ID for the given query.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: [a-zA-Z0-9]+


Information about the status of the query, including progress and bytes scannned.

Type: QueryStatus object


The result set rows returned by the query.

Type: Array of Row objects


For information about the errors that are common to all actions, see Common Errors.


You are not authorized to perform this action.

HTTP Status Code: 400


Unable to poll results for a cancelled query.

HTTP Status Code: 400


Timestream was unable to fully process this request because of an internal server error.

HTTP Status Code: 400


The requested endpoint was invalid.

HTTP Status Code: 400


Timestream was unable to run the query successfully.

HTTP Status Code: 400


The request was denied due to request throttling.

HTTP Status Code: 400


Invalid or malformed request.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: