要获得与亚马逊 Timestream 类似的功能 LiveAnalytics，可以考虑适用于 InfluxDB 的亚马逊 Timestream。适用于 InfluxDB 的 Amazon Timestream 提供简化的数据摄取和个位数毫秒级的查询响应时间，以实现实时分析。点击[此处](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` 请求。 + 如果在 5 分钟的幂等性时段内使用相同的客户端令牌提交 `Query` 请求，但更改其他参数。 + 如果行的大小（包括查询元数据）超过 1MB，则查询将失败并显示以下错误消息： `Query aborted as max page response size has been exceeded by the output result row` + 如果查询发起者和结果读取器的 IAM 委托人不相同 and/or ，查询发起者和结果读取器在查询请求中没有相同的查询字符串，则查询将失败并出现错误。`Invalid pagination token` ## 请求语法 ``` { "ClientToken": "string", "MaxRows": number, "NextToken": "string", "QueryInsights": { "Mode": "string" }, "QueryString": "string" } ``` ## 请求参数 有关所有操作的通用参数的信息，请参阅[常用参数](CommonParameters.md)。 请求接受采用 JSON 格式的以下数据。 ** [ClientToken](#API_query_Query_RequestSyntax) ** 发送 `Query` 请求时指定、最多包含 64 个 ASCII 字符的唯一且区分大小写的字符串。提供 `ClientToken` 使对 `Query` 的调用具有*幂等性*。这意味着重复运行相同的查询将产生相同的结果。换言之，发出多个相同的 `Query` 请求与发出单个请求具有相同的效果。在查询中使用 `ClientToken` 时，请注意以下事项： + 如果在没有 `ClientToken` 的情况下实例化查询 API，则查询 SDK 将为您自动生成 `ClientToken`。 + 如果 `Query` 调用仅包含 `ClientToken` 但不包含 `NextToken`，则对 `Query` 的调用视作新运行的查询。 + 如果调用包含 `NextToken`，则该特定调用视作对查询 API 先前调用的后续调用，并返回结果集。 + 4 小时后，任何具有相同请求的请求`ClientToken`都将被视为新请求。 类型：字符串 长度限制：最小长度为 32。最大长度为 128。 必需：否 ** [MaxRows](#API_query_Query_RequestSyntax) ** `Query` 输出中要返回的行总数。使用指定的 `MaxRows` 值初始运行 `Query` 将返回查询结果集，具体分为两种情况： + 结果的大小小于 `1MB`。 + 结果集中的行数小于 `maxRows` 的值。 否则，对 `Query` 的初始调用仅返回 `NextToken`，随后可用于后续调用以获取结果集。要恢复分页，请在后续命令中提供 `NextToken` 值。 如果行大小较大（例如，行包含许多列），Timestream 可能会返回较少行数，以防响应大小超过 1MB 的限制。如果未提供 `MaxRows`，Timestream 将发送必要的行数，以满足 1MB 的限制。 类型：整数 有效范围：最小值为 1。最大值为 1000。 必需：否 ** [NextToken](#API_query_Query_RequestSyntax) ** 用于检索结果集的分页令牌。当使用 `Query` 调用 `NextToken` API 时，该特定调用视作对 `Query` 先前调用的后续调用，并返回结果集。然而，如果 `Query` 调用仅包含 `ClientToken`，则对 `Query` 的调用视作新运行的查询。 在查询 NextToken 中使用时，请注意以下几点： + 分页令牌最多可用于五次 `Query` 调用，或持续使用长达 1 小时（以先到者为准）。 + 使用相同的 `NextToken` 将返回相同的记录集。要继续对结果集进行分页，则必须使用最新的 `nextToken`。 + 假设 `Query` 调用返回两个 `NextToken` 值，`TokenA` 和 `TokenB`。如果在后续 `Query` 调用中使用 `TokenB`，则 `TokenA` 会失效且无法重复使用。 + 在分页开始后，如需请求查询的先前结果集，则必须重新调用查询 API。 + 应使用最新的 `NextToken` 进行分页，直至返回 `null`，此时应使用新的 `NextToken`。 + 如果查询发起者和结果读取器的 IAM 委托人不相同 and/or ，查询发起者和结果读取器在查询请求中没有相同的查询字符串，则查询将失败并出现错误。`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 ## 另请参阅 有关以特定语言之一使用此 API 的更多信息 AWS SDKs，请参阅以下内容： + [AWS 命令行界面 V2](https://docs.aws.amazon.com/goto/cli2/timestream-query-2018-11-01/Query) + [AWS 适用于.NET 的 SDK V4](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 v2 的 SDK](https://docs.aws.amazon.com/goto/SdkForGoV2/timestream-query-2018-11-01/Query) + [AWS 适用于 Java 的 SDK V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/timestream-query-2018-11-01/Query) + [AWS JavaScript V3 版软件开发工具包](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 的 SDK V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/timestream-query-2018-11-01/Query) + [AWS Python 软件开发工具包](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)