Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、[こちら](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)を参照してください。 翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Query `Query` は、Amazon Timestream データに対してクエリを実行できる同期オペレーションです。 `QueryInsights` を有効にした場合、この API は実行したクエリに関連するインサイトとメトリクスも返します。`QueryInsights` はクエリのパフォーマンスチューニングに役立ちます。`QueryInsights` の詳細については、「[クエリインサイトを使用して Amazon Timestream のクエリを最適化する](https://docs.aws.amazon.com/timestream/latest/developerguide/using-query-insights.html)」を参照してください。 **注記** `QueryInsights` が有効な状態で実行できる `Query` API リクエストの最大数は、1 クエリ/秒 (QPS) です。このクエリレートを超えると、スロットリングが発生する可能性があります。 `Query` は 60 秒後にタイムアウトします。60 秒のタイムアウトをサポートするには、SDK のデフォルトタイムアウトを更新する必要があります。詳細については、[コードサンプル](https://docs.aws.amazon.com/timestream/latest/developerguide/code-samples.run-query.html)を参照してください。 以下のケースでは、クエリリクエストが失敗します。 + 5 分間のべき等性期間外に同じクライアントトークンを使用して `Query` リクエストを送信する場合。 + 5 分間のべき等性期間内に同じクライアントトークンを使用し、その他のパラメータは変更して `Query` リクエストを送信する場合。 + 行のサイズ (クエリメタデータを含む) が 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" } ``` ## リクエストパラメーター すべてのアクションに共通のパラメータの詳細については、「[共通パラメータ](CommonParameters.md)」を参照してください。 リクエストは以下のデータを JSON 形式で受け入れます。 ** [ClientToken](#API_query_Query_RequestSyntax) ** `Query` リクエストの実行時に指定される、最大 64 ASCII 文字の、大文字と小文字を区別する一意の文字列。`ClientToken` を指定すると、`Query` への呼び出しが*べき等*になります。これは、同じクエリを繰り返し実行すると、同じ結果が生成されることを意味します。つまり、同じ `Query` リクエストを複数作成しても、効果は 1 つのリクエストを作成する場合と同じです。クエリで `ClientToken` を使用する場合は、次の点に注意してください。 + Query API が `ClientToken` なしでインスタンス化される場合、Query SDK がユーザーに代わって `ClientToken` を生成します。 + `Query` 呼び出しに `ClientToken` のみが含まれ、`NextToken` が含まれていない場合、`Query` の呼び出しは新しいクエリ実行とみなされます。 + 呼び出しに `NextToken` が含まれている場合、その呼び出しは Query API に対する以前の呼び出しの後続呼び出しとみなされ、結果セットが返されます。 + 4 時間後、同じ を持つすべてのリクエスト`ClientToken`は新しいリクエストとして扱われます。 タイプ: 文字列 長さの制限: 最小長 32。最大長は 128 です。 必須: いいえ ** [MaxRows](#API_query_Query_RequestSyntax) ** `Query` 出力で返される行の総数。`MaxRows` 値が指定された `Query` の最初の実行では、次の 2 つのケースでクエリの結果セットが返されます。 + 結果のサイズが `1MB` 未満である。 + 結果セットの行数が `maxRows` の値未満である。 上記に該当しない場合、`Query` の最初の呼び出しは `NextToken` のみを返します。これは、結果セットを取得するために後続の呼び出しで使用できます。ページ分割を再開するには、後続コマンドで `NextToken` 値を指定します。 行サイズが大きい場合 (例: 行に列が多数ある場合)、Timestream はレスポンスサイズが 1 MB の上限を超えないように、返す行数を減らすことがあります。`MaxRows` が指定されていない場合、Timestream は 1 MB の上限を満たす必要な行数を送信します。 タイプ: 整数 有効範囲: 最小値 は 1 です。最大値は 1000 です。 必須: いいえ ** [NextToken](#API_query_Query_RequestSyntax) ** 結果セットを返すために使用されるページ分割トークン。`Query` API が `NextToken` を使用して呼び出されると、その呼び出しは `Query` に対する以前の呼び出しの後続呼び出しとみなされ、結果セットが返されます。ただし、`Query` 呼び出しに `ClientToken` のみが含まれる場合、`Query` の呼び出しは新しいクエリ実行とみなされます。 クエリで NextToken を使用する場合は、次の点に注意してください。 + ページ分割トークンは、最大 5 回の `Query` 呼び出しと、最大 1 時間のどちらか早い方に使用できます。 + 同じ `NextToken` を使用すると、同じレコードセットが返されます。結果セットをページ分割し続けるには、最新の `nextToken` を使用する必要があります。 + `Query` 呼び出しが `TokenA` と `TokenB` の 2 つの `NextToken` 値を返すとします。`TokenB` が後続の `Query` 呼び出しで使用される場合、`TokenA` は無効になり、再利用できません。 + ページ分割の開始後にクエリから以前の結果セットをリクエストするには、Query API を再度呼び出す必要があります。 + `null` が返されるまでは最新の `NextToken` を使用してページ分割し、これが返された時点で新しい `NextToken` を使用する必要があります。 + クエリ発行元と結果読み取り先の IAM プリンシパルが同じでない場合や、クエリ発行元と結果読み取り先のクエリリクエストに同じクエリ文字列がない場合、クエリは `Invalid pagination token` エラーで失敗します。 タイプ: 文字列 長さの制約: 最小長は 1 です。最大長は 2,048 です。 必須: いいえ ** [QueryInsights](#API_query_Query_RequestSyntax) ** `QueryInsights` を有効にするための設定をカプセル化します。 `QueryInsights` を有効にすると、実行したクエリのクエリ結果に加えて、インサイトとメトリクスが返されます。`QueryInsights` を使用して、クエリのパフォーマンスをチューニングできます。 型: [QueryInsights](API_query_QueryInsights.md) オブジェクト 必須: いいえ ** [QueryString](#API_query_Query_RequestSyntax) ** 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](#API_query_Query_ResponseSyntax) ** 返された結果セットの列データ型。 型: [ColumnInfo](API_query_ColumnInfo.md) オブジェクトの配列 ** [NextToken](#API_query_Query_ResponseSyntax) ** `Query` 呼び出しで再度使用して次の結果セットを取得できるページ分割トークン。 タイプ: 文字列 長さの制約: 最小長は 1 です。最大長は 2,048 です。 ** [QueryId](#API_query_Query_ResponseSyntax) ** 指定されたクエリの一意の ID。 タイプ: 文字列 長さの制約: 最小長は 1 です。最大長 64 パターン: `[a-zA-Z0-9]+` ** [QueryInsightsResponse](#API_query_Query_ResponseSyntax) ** 実行したクエリに関連するインサイトとメトリクスを含む `QueryInsights` をカプセル化します。 型: [QueryInsightsResponse](API_query_QueryInsightsResponse.md) オブジェクト ** [QueryStatus](#API_query_Query_ResponseSyntax) ** 進行状況やスキャンされたバイト数など、クエリのステータスに関する情報。 型: [QueryStatus](API_query_QueryStatus.md) オブジェクト ** [Rows](#API_query_Query_ResponseSyntax) ** クエリによって返される結果セット行。 型: [Row](API_query_Row.md) オブジェクトの配列 ## エラー すべてのアクションに共通のエラーについては、「[共通エラー](CommonErrors.md)」を参照してください。 ** AccessDeniedException ** アカウント設定にアクセスするために必要なアクセス許可がありません。 HTTP ステータスコード: 400 ** ConflictException ** キャンセルされたクエリの結果をポーリングできません。 HTTP ステータスコード: 400 ** InternalServerException ** リクエストの処理中に内部サーバーエラーが発生しました。 HTTP ステータスコード: 400 ** InvalidEndpointException ** リクエストされたエンドポイントが無効です。 HTTP ステータスコード: 400 ** QueryExecutionException ** Timestream がクエリを正常に実行できませんでした。 HTTP ステータスコード: 400 ** ThrottlingException ** リクエストが多すぎるため、リクエストがスロットリングされました。 HTTP ステータスコード: 400 ** ValidationException ** リクエストが無効であるか、形式が正しくありません。 HTTP ステータスコード: 400 ## 以下の資料も参照してください。 言語固有の AWS SDKs のいずれかでこの API を使用する方法の詳細については、以下を参照してください。 + [AWS コマンドラインインターフェイス V2](https://docs.aws.amazon.com/goto/cli2/timestream-query-2018-11-01/Query) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/timestream-query-2018-11-01/Query) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/timestream-query-2018-11-01/Query) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/timestream-query-2018-11-01/Query) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/timestream-query-2018-11-01/Query) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/timestream-query-2018-11-01/Query) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/timestream-query-2018-11-01/Query) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/timestream-query-2018-11-01/Query) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/timestream-query-2018-11-01/Query) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/timestream-query-2018-11-01/Query)