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"
                  }
               ]
            }
         ]
      }
   ]
}