Query

Query 是一項同步操作，可讓您針對 Amazon Timestream 資料執行查詢。

如果您啟用 QueryInsights，這API也會傳回與您執行的查詢相關的洞察和指標。 QueryInsights 可協助您調校查詢的效能。如需的詳細資訊QueryInsights，請參閱使用查詢洞察來最佳化 Amazon Timestream 中的查詢。

注意

您允許在QueryInsights啟用的情況下執行的QueryAPI請求數目上限為每秒 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 個字元的唯一區分大小寫字串。提供會ClientToken呼叫 Query 具意向性 。這表示重複執行相同的查詢會產生相同的結果。換句話說，發出多個相同的Query請求與發出單一請求具有相同的效果。在查詢ClientToken中使用時，請注意下列事項：

如果查詢API是在沒有的情況下現化ClientToken，則查詢ClientToken會代表您SDK產生。
如果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

用於傳回一組結果的分頁權杖。使用 QueryAPI叫用時NextToken，會假設該特定叫用是先前呼叫的後續叫用Query，並傳回結果集。不過，如果Query調用僅包含 ClientToken，則的調用Query會被視為新的查詢執行。

在查詢 NextToken 中使用時，請注意下列事項：

分頁權杖最多可用於五個Query調用，或最長 1 小時的持續時間 – 以先發生者為準。
使用相同的 NextToken會傳回相同的記錄集。若要繼續瀏覽結果集，您必須使用最新的 nextToken。
假設Query調用會傳回兩個NextToken值，TokenA以及 TokenB。如果 TokenB 用於後續Query調用，則 TokenA 會失效，且無法重複使用。
若要在分頁開始後，從查詢請求上一個結果集，您必須重新叫用查詢 API。
在null傳回前，NextToken應使用最新的分頁，此時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"
                  }
               ]
            }
         ]
      }
   ]
}