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

Amazon Timestream for LiveAnalytics に類似した機能をご希望の場合は Amazon Timestream for InfluxDB をご検討ください。リアルタイム分析に適した、シンプルなデータインジェストと 1 桁ミリ秒のクエリ応答時間を特徴としています。詳細については、こちらを参照してください。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Query

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

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

注記

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

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

以下のケースでは、クエリリクエストが失敗します。

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

リクエストパラメータ

すべてのアクションに共通のパラメータの詳細については、「共通パラメータ」を参照してください。

リクエストは以下のデータを JSON 形式で受け入れます。

ClientToken

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

Query 出力で返される行の総数。MaxRows 値が指定された Query の最初の実行では、次の 2 つのケースでクエリの結果セットが返されます。

  • 結果のサイズが 1MB 未満である。

  • 結果セットの行数が maxRows の値未満である。

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

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

タイプ: 整数

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

必須: いいえ

NextToken

結果セットを返すために使用されるページ分割トークン。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

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

以下の資料も参照してください。

言語固有の AWS SDK のいずれかでこの API を使用する方法の詳細については、以下を参照してください。