リクエストの構文リクエストパラメータレスポンスの構文レスポンス要素エラー以下の資料も参照してください。

Query

Query は、Amazon Timestream データに対してクエリを実行できるようにする同期オペレーションです。

を有効にした場合QueryInsights、このAPIは実行したクエリに関連するインサイトとメトリクスも返します。 QueryInsightsはクエリのパフォーマンスチューニングに役立ちます。の詳細についてはQueryInsights、「クエリインサイトを使用して Amazon Timestream でクエリを最適化する」を参照してください。

注記

QueryInsights を有効にして実行できる API リクエストの最大数は、1 Query 秒あたり 1 クエリ (QPS) です。このクエリレートを超えると、スロットリングが発生する可能性があります。

Query は 60 秒後にタイムアウトします。60 秒のタイムアウトをサポートするには、SDK のデフォルトのタイムアウトを更新する必要があります。詳細については、コードサンプルを参照してください。

次の場合、クエリリクエストは失敗します。

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の一意の大文字と小文字を区別する文字列。ClientToken を指定すると、べき等Queryが呼び出されます。つまり、同じクエリを繰り返し実行すると、同じ結果が生成されます。つまり、複数の同一のQueryリクエストを行うと、1 つのリクエストを行うのと同じ効果が得られます。クエリClientTokenでを使用する場合は、次の点に注意してください。

クエリAPIがなしでインスタンス化されている場合ClientToken、クエリSDKはClientTokenユーザーに代わってを生成します。
Query 呼び出しにのみが含まれClientToken、が含まれていない場合NextToken、の呼び出しQueryは新しいクエリ実行と見なされます。
呼び出しにが含まれている場合NextToken、その特定の呼び出しはクエリAPIへの以前の呼び出しの後続の呼び出しと見なされ、結果セットが返されます。
4 時間後、同じを持つすべてのリクエストClientTokenは新しいリクエストとして扱われます。

タイプ: 文字列

長さの制限: 最小長 32。最大長は 128 です。

必須: いいえ

MaxRows

Query 出力で返される行の合計数。Query MaxRows 値が指定されたの初回実行では、次の 2 つの場合にクエリの結果セットが返されます。

結果のサイズが未満です1MB。
結果セットの行数がの値より少なくなりますmaxRows。

それ以外の場合、の最初の呼び出しは Queryのみを返します。これはNextToken、結果セットを取得するために後続の呼び出しで使用できます。ページ分割を再開するには、後続のコマンドで NextToken値を指定します。

行サイズが大きい場合 (行に多数の列がある場合など）、Timestream はレスポンスサイズが 1 MB の制限を超えないように、返される行数を減らす場合があります。が指定されMaxRowsていない場合、Timestream は 1 MB の制限を満たすために必要な行数を送信します。

タイプ: 整数

有効範囲: 最小値は 1 です。最大値は 1000 です。

必須: いいえ

NextToken

結果のセットを返すために使用されるページ割りトークン。を使用して QueryAPI が呼び出されるとNextToken、その特定の呼び出しはへの以前の呼び出しの後続の呼び出しと見なされQuery、結果セットが返されます。ただし、Query呼び出しにのみが含まれている場合ClientToken、の呼び出しQueryは新しいクエリ実行と見なされます。

クエリで NextToken を使用する場合は、次の点に注意してください。

ページ割りトークンは、最大 5 Query 回の呼び出し、または最大 1 時間のいずれか早い方に使用できます。
同じを使用するとNextToken、同じレコードセットが返されます。結果セットをページ分割し続けるには、最新のを使用する必要がありますnextToken。
Query 呼び出しが TokenAとの 2 つのNextToken値を返すとしますTokenB。TokenB が後続のQuery呼び出しで使用されている場合、 TokenAは無効になり、再利用できません。
ページ分割の開始後にクエリから以前の結果セットをリクエストするには、クエリAPIを再呼び出す必要があります。
null が返るまでページ分割には最新の NextTokenを使用する必要があります。返された時点で、新しい NextTokenを使用する必要があります。
クエリイニシエータと結果リーダーの IAM プリンシパルが同じでない場合、および/またはクエリイニシエータと結果リーダーのクエリリクエストに同じクエリ文字列がない場合、クエリはInvalid pagination tokenエラーで失敗します。

タイプ: 文字列

長さの制約: 最小長は 1 です。最大長は 2,048 です。

必須: いいえ

QueryInsights

を有効にするための設定をカプセル化しますQueryInsights。

を有効にすると、実行したクエリのクエリ結果に加えて、インサイトとメトリクスQueryInsightsが返されます。を使用してQueryInsightsクエリのパフォーマンスを調整できます。

型: QueryInsights オブジェクト

必須: いいえ

QueryString

Timestream によって実行されるクエリ。

タイプ: 文字列

長さの制約: 最小長は 1 です。最大長は 262,144 です。

必須: はい

レスポンスの構文


{
   "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 呼び出しで再度使用して次の結果セットを取得できるページ割りトークン。

タイプ: 文字列

長さの制約: 最小長は 1 です。最大長は 2,048 です。

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 でこの AWS SDKsを使用する方法の詳細については、以下を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

PrepareQuery

TagResource