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

請求參數

如需所有動作的一般參數資訊，請參閱《Common Parameters》。

請求接受採用 JSON 格式的下列資料。

ClientToken

提出Query請求時，最多指定 64 個 ASCII 字元的唯一區分大小寫字串。提供 Query ClientToken會呼叫等冪。這表示重複執行相同的查詢會產生相同的結果。換句話說，提出多個相同的Query請求與提出單一請求的效果相同。在查詢ClientToken中使用時，請注意下列事項：

如果在沒有的情況下執行個體化查詢 APIClientToken，則查詢 SDK ClientToken會代表您產生。
如果Query調用僅包含 ClientToken但不包含 NextToken，則的調用Query會假設為新的查詢執行。
如果調用包含 NextToken，則會假設該特定調用是先前呼叫查詢 API 的後續調用，並傳回結果集。
4 小時後，任何具有相同的請求ClientToken都會視為新的請求。

類型：字串

長度限制：長度下限為 32。長度上限為 128。

必要：否

MaxRows

要在Query輸出中傳回的資料列總數。Query 具有指定MaxRows值的初始執行會在兩種情況下傳回查詢的結果集：

結果的大小小於 1MB。
結果集中的資料列數小於的值maxRows。

否則，的初始調用Query只會傳回 NextToken，然後可用於後續呼叫以擷取結果集。若要繼續分頁，請在後續命令中提供 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 會失效且無法重複使用。
若要在分頁開始後從查詢請求先前的結果集，您必須重新叫用查詢 API。
NextToken 應該使用最新的分頁，直到傳回null為止，此時NextToken應使用新的。
如果查詢啟動器的 IAM 主體和結果讀取器不同和/或查詢啟動器，且結果讀取器在查詢請求中沒有相同的查詢字串，則查詢會失敗並顯示Invalid pagination token錯誤。

類型：字串

長度限制：長度下限為 1。長度上限為 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"
                  }
               ]
            }
         ]
      }
   ]
}