Query

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

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

注意

QueryInsights 启用后，允许发出的最大 Query API 请求数为每秒 1 次查询（QPS）。如果超过此查询速率，可能会导致节流。

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

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

如果在 5 分钟的幂等性时段之外使用相同的客户端令牌提交 Query 请求。
如果在 5 分钟的幂等性时段内使用相同的客户端令牌提交 Query 请求，但更改其他参数。
如果行的大小（包括查询元数据）超过 1MB，则查询将失败并显示以下错误消息：

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 字符的唯一且区分大小写的字符串。提供 ClientToken 使对 Query 的调用具有幂等性。这意味着重复运行相同的查询将产生相同的结果。换言之，发出多个相同的 Query 请求与发出单个请求具有相同的效果。在查询中使用 ClientToken 时，请注意以下事项：

如果在没有 ClientToken 的情况下实例化查询 API，则查询 SDK 将为您自动生成 ClientToken。
如果 Query 调用仅包含 ClientToken 但不包含 NextToken，则对 Query 的调用视作新运行的查询。
如果调用包含 NextToken，则该特定调用视作对查询 API 先前调用的后续调用，并返回结果集。
4 小时后，具有相同 ClientToken 的任何请求都将视为新请求。

类型：字符串

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

必需：否

MaxRows

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

结果的大小小于 1MB。
结果集中的行数小于 maxRows 的值。

否则，对 Query 的初始调用仅返回 NextToken，随后可用于后续调用以获取结果集。要恢复分页，请在后续命令中提供 NextToken 值。

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

类型：整数

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

必需：否

NextToken

用于检索结果集的分页令牌。当使用 Query 调用 NextToken API 时，该特定调用视作对 Query 先前调用的后续调用，并返回结果集。然而，如果 Query 调用仅包含 ClientToken，则对 Query 的调用视作新运行的查询。

在查询中使用 NextToken 时，请注意以下事项：

分页令牌最多可用于五次 Query 调用，或持续使用长达 1 小时（以先到者为准）。
使用相同的 NextToken 将返回相同的记录集。要继续对结果集进行分页，则必须使用最新的 nextToken。
假设 Query 调用返回两个 NextToken 值，TokenA 和 TokenB。如果在后续 Query 调用中使用 TokenB，则 TokenA 会失效且无法重复使用。
在分页开始后，如需请求查询的先前结果集，则必须重新调用查询 API。
应使用最新的 NextToken 进行分页，直至返回 null，此时应使用新的 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"
                  }
               ]
            }
         ]
      }
   ]
}