Query

Query는 Amazon Timestream 데이터에 대해 쿼리를 실행할 수 있는 동기식 작업입니다.

를 활성화한 경우 QueryInsights이 API는 실행한 쿼리와 관련된 인사이트 및 지표도 반환합니다.는 쿼리의 성능 튜닝에 QueryInsights 도움이 됩니다. 에 대한 자세한 내용은 쿼리 인사이트를 사용하여 Amazon Timestream에서 쿼리 최적화를 QueryInsights참조하세요.

참고

QueryInsights 활성화된 상태에서 수행할 수 있는 최대 Query API 요청 수는 초당 쿼리 1개(QPS)입니다. 이 쿼리 속도를 초과하면 제한이 발생할 수 있습니다.

Query는 60초 후에 시간 초과됩니다. 60초의 제한 시간을 지원하도록 SDK의 기본 제한 시간을 업데이트해야 합니다. 자세한 내용은 코드 샘플을 참조하세요.

다음과 같은 경우 쿼리 요청이 실패합니다.

5분 멱등성 기간을 벗어나 동일한 클라이언트 토큰으로 Query 요청을 제출하는 경우.
동일한 클라이언트 토큰으로 Query 요청을 제출하지만 다른 파라미터를 변경하는 경우 5분 멱등성 기간 내에.
행 크기(쿼리 메타데이터 포함)가 1MB를 초과하면 쿼리가 실패하고 다음 오류 메시지가 표시됩니다.

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 요청을 여러 번 하면 단일 요청을 하는 것과 동일한 효과가 있습니다. 쿼리ClientToken에서를 사용할 때는 다음 사항에 유의하세요.

쿼리 API가 없이 인스턴스화되면 ClientToken쿼리 SDK가 사용자를 ClientToken 대신하여를 생성합니다.
Query 호출에 만 포함되지ClientToken만는 포함되지 않는 경우 NextToken의 호출Query은 새 쿼리 실행으로 간주됩니다.
호출에가 포함된 경우 NextToken해당 특정 호출은 쿼리 API에 대한 이전 호출의 후속 호출로 간주되고 결과 집합이 반환됩니다.
4시간 후 동일한가 있는 모든 요청은 새 요청으로 ClientToken 처리됩니다.

유형: 문자열

길이 제약: 최소 길이는 32입니다. 최대 길이 128.

필수 여부: 아니요

MaxRows

Query 출력에 반환될 총 행 수입니다. Query MaxRows 값이 지정된의 초기 실행은 두 가지 경우에 쿼리의 결과 집합을 반환합니다.

결과의 크기가 보다 작습니다1MB.
결과 집합의 행 수가 값보다 작습니다maxRows.

그렇지 않으면의 초기 호출은 Query만 반환하며NextToken, 이후 호출에서 결과 세트를 가져오는 데 사용할 수 있습니다. 페이지 매김을 재개하려면 후속 명령에 NextToken 값을 입력합니다.

행 크기가 큰 경우(예: 행에 열이 많은 경우) Timestream은 응답 크기가 1MB 제한을 초과하지 않도록 더 적은 수의 행을 반환할 수 있습니다. MaxRows이 제공되지 않으면 Timestream은 1MB 제한을 충족하는 데 필요한 수의 행을 전송합니다.

타입: 정수

유효한 범위: 최소값은 1입니다. 최대값은 1000입니다.

필수 여부: 아니요

NextToken

결과 집합을 반환하는 데 사용되는 페이지 매김 토큰입니다. 를 사용하여 Query API를 호출하면 NextToken해당 특정 호출이에 대한 이전 호출의 후속 호출로 간주Query되고 결과 집합이 반환됩니다. 그러나 Query 호출에 만 포함된 경우 ClientToken의 호출Query은 새 쿼리 실행으로 간주됩니다.

쿼리에서 NextToken을 사용할 때는 다음 사항에 유의하세요.

페이지 매김 토큰은 최대 5개의 Query 간접 호출에 사용하거나 최대 1시간 중 먼저 도래하는 기간 동안 사용할 수 있습니다.
동일한를 사용하면 동일한 레코드 세트가 반환NextToken됩니다. 결과 집합을 계속 페이지 매김하려면 최신를 사용해야 합니다nextToken.
Query 호출이 TokenA 및 라는 두 개의 NextToken 값을 반환한다고 가정해 보겠습니다TokenB. 후속 Query 호출에서를 TokenB 사용하는 경우 TokenA는 무효화되며 재사용할 수 없습니다.
페이지 매김이 시작된 후 쿼리에서 이전 결과 세트를 요청하려면 쿼리 API를 다시 호출해야 합니다.
가 null 반환될 때까지 최신를 사용하여 페이지를 매겨야 NextToken 합니다. 이때 새를 사용해야 NextToken 합니다.
쿼리 이니시에이터와 결과 리더의 IAM 보안 주체가 동일하지 않거나 쿼리 이니시에이터와 결과 리더의 쿼리 요청에 동일한 쿼리 문자열이 없는 경우 쿼리가 실패하고 Invalid pagination token 오류가 발생합니다.

유형: 문자열

길이 제약: 최소 길이는 1. 최대 길이는 2,048.

필수 여부: 아니요

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