Query - Amazon Timestream
请求语法请求参数响应语法响应元素错误另请参阅
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

要获得与亚马逊 Timestream 类似的功能 LiveAnalytics，可以考虑适用于 InfluxDB 的亚马逊 Timestream。它为实时分析提供了简化的数据摄取和个位数毫秒的查询响应时间。点击此处了解更多。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Query

Query是一种同步操作，可让您对自己的 Amazon Timestream 数据运行查询。

如果您启用QueryInsights，此 API 还会返回与您执行的查询相关的见解和指标。 QueryInsights有助于调整查询的性能。有关更多信息QueryInsights，请参阅使用查询见解来优化 Amazon Timestream 中的查询。

注意

QueryInsights启用后，允许您发出的最大 Query API 请求数为每秒 1 个查询 (QPS)。如果超过此查询速率，则可能会导致限制。

Query将在 60 秒后超时。您必须更新 SDK 中的默认超时以支持 60 秒的超时。有关详细信息，请参阅代码示例。

在以下情况下，您的查询请求将失败：

  • 如果您在 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"
}

请求参数

有关所有操作的通用参数的信息，请参阅常用参数。

请求接受采用 JSON 格式的以下数据。

ClientToken

Query发出请求时指定的、区分大小写的唯一字符串，最多 64 个 ASCII 字符。提供 a ClientToken 会使调用Query等性。这意味着重复运行相同的查询将产生相同的结果。换句话说，发出多个相同的Query请求与发出单个请求的效果相同。在查询ClientToken中使用时，请注意以下几点：

  • 如果查询 API 的实例化时没有ClientToken，则查询 SDK 会ClientToken代表您生成。

  • 如果Query调用仅包含ClientToken但不包含NextToken，则假定该调用Query是新运行的查询。

  • 如果调用包含NextToken，则假定该特定调用是先前对 Query API 的调用的后续调用，并返回结果集。

  • 4 小时后，任何具有相同请求的请求ClientToken都将被视为新请求。

类型：字符串

长度限制：最小长度为 32。最大长度为 128。

必需：否

MaxRows

要在Query输出中返回的总行数。在两种情况下，Query使用指定MaxRows值的初始运行将返回查询的结果集：

  • 结果的大小小于1MB。

  • 结果集中的行数小于的值maxRows。

否则，的初始调用Query只会返回 aNextToken，然后可以在后续调用中使用它来获取结果集。要恢复分页，请在后续命令中提供该NextToken值。

如果行大小很大（例如，一行有许多列），Timestream 可能会返回更少的行，以防止响应大小超过 1 MB 的限制。如果MaxRows未提供，Timestream 将发送必要的行数以满足 1 MB 的限制。

类型：整数

有效范围：最小值为 1。最大值为 1000。

必需：否

NextToken

用于返回一组结果的分页标记。当使用调用 Query API 时NextToken，假定该特定调用是对先前调用的后续调用Query，并返回结果集。但是，如果Query调用仅包含ClientToken，则假定该调用Query是新运行的查询。

在查询 NextToken 中使用时，请注意以下几点：

  • 分页令牌最多可用于五Query次调用，或者持续时间长达 1 小时（以先到者为准）。

  • 使用相同NextToken值将返回相同的记录集。要继续对结果集进行分页，必须使用最新nextToken的。

  • 假设Query调用返回两个NextToken值，TokenA和。TokenB如果TokenB在后续Query调用中使用，TokenA则失效且无法重复使用。

  • 要在分页开始后从查询中请求先前的结果集，必须重新调用 Query API。

  • 在返回之前null，NextToken应使用最新的分页，此时NextToken应使用新的分页。

  • 如果查询发起者和结果读取器的 IAM 委托人不一样和/或查询发起者和结果读取器在查询请求中没有相同的查询字符串，则查询将失败并出现错误。Invalid pagination token

类型：字符串

长度限制：最小长度为 0。最大长度为 2048。

必需：否

QueryInsights

封装用于启用的设置。QueryInsights

启用后，除了您执行的查询的查询结果外，还会QueryInsights返回见解和指标。您可以使用QueryInsights来调整查询性能。

类型：QueryInsights 对象

必需：否

QueryString

将由 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

返回的结果集的列数据类型。

类型：ColumnInfo 对象数组

NextToken

一种分页令牌，可以在Query调用时再次使用以获取下一组结果。

类型：字符串

长度限制：最小长度为 0。最大长度为 2048。

QueryId

给定查询的唯一 ID。

类型：字符串

长度限制：长度下限为 1。长度上限为 64。

模式：[a-zA-Z0-9]+

QueryInsightsResponse

封装QueryInsights包含与您执行的查询相关的见解和指标。

类型：QueryInsightsResponse 对象

QueryStatus

有关查询状态的信息，包括进度和扫描的字节。

类型：QueryStatus 对象

Rows

查询返回的结果集行。

类型：Row 对象数组

错误

有关所有操作的常见错误的信息，请参阅常见错误。

AccessDeniedException

您没有访问账户设置所需的权限。

HTTP 状态代码：400

ConflictException

无法对已取消的查询进行轮询结果。

HTTP 状态代码：400

InternalServerException

处理请求时出现内部服务器错误。

HTTP 状态代码：400

InvalidEndpointException

请求的端点无效。

HTTP 状态代码：400

QueryExecutionException

Timestream 无法成功运行查询。

HTTP 状态代码：400

ThrottlingException

由于请求过多，请求受到限制。

HTTP 状态代码：400

ValidationException

请求无效或格式错误。

HTTP 状态代码：400

另请参阅

有关以特定语言之一使用此 API 的更多信息 Amazon SDKs，请参阅以下内容：