如需與 Amazon Timestream for LiveAnalytics 類似的功能，請考慮使用 Amazon Timestream for InfluxDB。它提供簡化的資料擷取和單一位數毫秒查詢回應時間，以進行即時分析。[在這裡](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)進一步了解。 本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Query `Query` 是一種同步操作，可讓您針對 Amazon Timestream 資料執行查詢。 如果您啟用 `QueryInsights`，此 API 也會傳回與您執行之查詢相關的洞見和指標。 `QueryInsights` 可協助您調校查詢的效能。如需 的詳細資訊`QueryInsights`，請參閱[使用查詢洞見來最佳化 Amazon Timestream 中的查詢](https://docs.aws.amazon.com/timestream/latest/developerguide/using-query-insights.html)。 **注意** 在`QueryInsights`啟用的情況下，您允許的 `Query` API 請求數目上限為每秒 1 個查詢 (QPS)。如果您超過此查詢速率，可能會導致限流。 `Query` 會在 60 秒後逾時。您必須更新 SDK 中的預設逾時，以支援 60 秒的逾時。如需詳細資訊，請參閱[程式碼範例](https://docs.aws.amazon.com/timestream/latest/developerguide/code-samples.run-query.html)。 在下列情況下，您的查詢請求將會失敗： + 如果您在 5 分鐘等冪時段之外使用相同的用戶端字符提交`Query`請求。 + 如果您使用相同的用戶端字符提交`Query`請求，但在 5 分鐘等冪時段內變更其他參數。 + 如果資料列的大小 （包括查詢中繼資料） 超過 1 MB，則查詢會失敗，並顯示下列錯誤訊息： `Query aborted as max page response size has been exceeded by the output result row` + 如果查詢啟動器和結果讀取器的 IAM 主體不同和/或查詢啟動器，且結果讀取器在查詢請求中沒有相同的查詢字串，則查詢會失敗並顯示`Invalid pagination token`錯誤。 ## 請求語法 ``` { "ClientToken": "string", "MaxRows": number, "NextToken": "string", "QueryInsights": { "Mode": "string" }, "QueryString": "string" } ``` ## 請求參數 如需所有動作的一般參數資訊，請參閱《[Common Parameters](CommonParameters.md)》。 請求接受採用 JSON 格式的下列資料。 ** [ClientToken](#API_query_Query_RequestSyntax) ** 提出`Query`請求時，最多指定 64 個 ASCII 字元的唯一區分大小寫字串。提供 `ClientToken`會呼叫`Query`*等*冪。這表示重複執行相同的查詢會產生相同的結果。換句話說，提出多個相同的`Query`請求與提出單一請求的效果相同。在查詢`ClientToken`中使用 時，請注意下列事項： + 如果在沒有 的情況下執行個體化查詢 API`ClientToken`，則查詢 SDK `ClientToken`會代表您產生 。 + 如果`Query`調用僅包含 `ClientToken`但不包含 `NextToken`，則 的調用`Query`會假設為新的查詢執行。 + 如果調用包含 `NextToken`，則會假設該特定調用是先前呼叫查詢 API 的後續調用，並傳回結果集。 + 4 小時後，任何具有相同 的請求`ClientToken`都會視為新的請求。 類型：字串 長度限制：長度下限為 32。長度上限為 128。 必要：否 ** [MaxRows](#API_query_Query_RequestSyntax) ** 要在`Query`輸出中傳回的資料列總數。`Query` 具有指定`MaxRows`值的 初始執行會在兩種情況下傳回查詢的結果集： + 結果的大小小於 `1MB`。 + 結果集中的資料列數小於 的值`maxRows`。 否則， 的初始調用`Query`只會傳回 `NextToken`，然後可用於後續呼叫以擷取結果集。若要繼續分頁，請在後續命令中提供 `NextToken`值。 如果資料列大小很大 （例如資料列有許多資料欄），Timestream 可能會傳回較少的資料列，以避免回應大小超過 1 MB 的限制。如果`MaxRows`未提供 ，Timestream 會傳送必要的資料列數，以符合 1 MB 的限制。 類型：整數 有效範圍：最小值為 1。最大值為 1000。 必要：否 ** [NextToken](#API_query_Query_RequestSyntax) ** 用於傳回一組結果的分頁字符。使用 叫用 `Query` API 時`NextToken`，會假設該特定叫用是先前呼叫 的後續叫用`Query`，並傳回結果集。不過，如果`Query`調用僅包含 `ClientToken`，則 的調用`Query`會假設為新的查詢執行。 在查詢中使用 NextToken 時，請注意下列事項： + 分頁字符最多可用於五個`Query`叫用，或長達 1 小時，以先發生者為準。 + 使用相同的 `NextToken`會傳回相同的記錄集。若要繼續分頁結果集，您必須使用最新的 `nextToken`。 + 假設`Query`調用會傳回兩個`NextToken`值 `TokenA`和 `TokenB`。如果 `TokenB` 在後續`Query`調用中使用 ，則 `TokenA` 會失效且無法重複使用。 + 若要在分頁開始後從查詢請求先前的結果集，您必須重新叫用查詢 API。 + `NextToken` 應該使用最新的 進行分頁，直到傳回`null`為止，此時`NextToken`應使用新的 。 + 如果查詢啟動器和結果讀取器的 IAM 主體不同和/或查詢啟動器，且結果讀取器在查詢請求中沒有相同的查詢字串，則查詢會失敗並顯示`Invalid pagination token`錯誤。 類型：字串 長度限制：長度下限為 1。長度上限為 2048。 必要：否 ** [QueryInsights](#API_query_Query_RequestSyntax) ** 封裝啟用 的設定`QueryInsights`。 啟用 會`QueryInsights`傳回洞見和指標，以及您所執行查詢的查詢結果。您可以使用 `QueryInsights`來調整查詢效能。 類型：[QueryInsights](API_query_QueryInsights.md) 物件 必要：否 ** [QueryString](#API_query_Query_RequestSyntax) ** Timestream 要執行的查詢。 類型：字串 長度限制：長度下限為 1。長度上限為 262144。 必要：是 ## 回應語法 ``` { "ColumnInfo": [ { "Name": "string", "Type": { "ArrayColumnInfo": "ColumnInfo", "RowColumnInfo": [ "ColumnInfo" ], "ScalarType": "string", "TimeSeriesMeasureValueColumnInfo": "ColumnInfo" } } ], "NextToken": "string", "QueryId": "string", "QueryInsightsResponse": { "OutputBytes": number, "OutputRows": number, "QuerySpatialCoverage": { "Max": { "PartitionKey": [ "string" ], "TableArn": "string", "Value": number } }, "QueryTableCount": number, "QueryTemporalRange": { "Max": { "TableArn": "string", "Value": number } }, "UnloadPartitionCount": number, "UnloadWrittenBytes": number, "UnloadWrittenRows": number }, "QueryStatus": { "CumulativeBytesMetered": number, "CumulativeBytesScanned": number, "ProgressPercentage": number }, "Rows": [ { "Data": [ { "ArrayValue": [ "Datum" ], "NullValue": boolean, "RowValue": "Row", "ScalarValue": "string", "TimeSeriesValue": [ { "Time": "string", "Value": "Datum" } ] } ] } ] } ``` ## 回應元素 如果動作成功，則服務傳回 HTTP 200 回應。 服務會傳回下列 JSON 格式的資料。 ** [ColumnInfo](#API_query_Query_ResponseSyntax) ** 傳回結果集的資料欄資料類型。 類型：[ColumnInfo](API_query_ColumnInfo.md) 物件陣列 ** [NextToken](#API_query_Query_ResponseSyntax) ** 可在`Query`呼叫中再次使用的分頁字符，以取得下一組結果。 類型：字串 長度限制：長度下限為 1。長度上限為 2048。 ** [QueryId](#API_query_Query_ResponseSyntax) ** 指定查詢的唯一 ID。 類型：字串 長度限制：長度下限為 1。長度上限為 64。 模式：`[a-zA-Z0-9]+` ** [QueryInsightsResponse](#API_query_Query_ResponseSyntax) ** 封裝`QueryInsights`包含與您執行之查詢相關的洞見和指標。 類型：[QueryInsightsResponse](API_query_QueryInsightsResponse.md) 物件 ** [QueryStatus](#API_query_Query_ResponseSyntax) ** 查詢狀態的相關資訊，包括掃描的進度和位元組。 類型：[QueryStatus](API_query_QueryStatus.md) 物件 ** [Rows](#API_query_Query_ResponseSyntax) ** 查詢傳回的結果集資料列。 類型：[Row](API_query_Row.md) 物件陣列 ## 錯誤 如需所有動作常見錯誤的資訊，請參閱[常見錯誤](CommonErrors.md)。 ** AccessDeniedException ** 您沒有存取帳戶設定的必要許可。 HTTP 狀態碼：400 ** ConflictException ** 無法輪詢已取消查詢的結果。 HTTP 狀態碼：400 ** InternalServerException ** 處理請求時發生內部伺服器錯誤。 HTTP 狀態碼：400 ** InvalidEndpointException ** 請求的端點無效。 HTTP 狀態碼：400 ** QueryExecutionException ** Timestream 無法成功執行查詢。 HTTP 狀態碼：400 ** ThrottlingException ** 請求因請求過多而受到限流。 HTTP 狀態碼：400 ** ValidationException ** 無效或格式不正確的請求。 HTTP 狀態碼：400 ## 另請參閱 如需在其中一種語言特定 AWS SDKs中使用此 API 的詳細資訊，請參閱下列內容： + [AWS 命令列界面 V2](https://docs.aws.amazon.com/goto/cli2/timestream-query-2018-11-01/Query) + [AWS 適用於 .NET V4 的 SDK](https://docs.aws.amazon.com/goto/DotNetSDKV4/timestream-query-2018-11-01/Query) + [AWS 適用於 C\$1\$1 的 SDK](https://docs.aws.amazon.com/goto/SdkForCpp/timestream-query-2018-11-01/Query) + [AWS 適用於 Go 的 SDK v2](https://docs.aws.amazon.com/goto/SdkForGoV2/timestream-query-2018-11-01/Query) + [AWS 適用於 Java V2 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaV2/timestream-query-2018-11-01/Query) + [AWS 適用於 JavaScript V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/timestream-query-2018-11-01/Query) + [AWS 適用於 Kotlin 的 SDK](https://docs.aws.amazon.com/goto/SdkForKotlin/timestream-query-2018-11-01/Query) + [AWS 適用於 PHP V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForPHPV3/timestream-query-2018-11-01/Query) + [AWS 適用於 Python 的 SDK](https://docs.aws.amazon.com/goto/boto3/timestream-query-2018-11-01/Query) + [AWS 適用於 Ruby V3 的 SDK](https://docs.aws.amazon.com/goto/SdkForRubyV3/timestream-query-2018-11-01/Query)