Amazon Timestream for LiveAnalytics와 유사한 기능을 원하는 경우 Amazon Timestream for InfluxDB를 고려해 보세요. 간소화된 데이터 수집과 실시간 분석을 위한 10밀리초 미만의 쿼리 응답 시간을 제공합니다. [여기](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 요청 수는 초당 쿼리(QPS) 1개입니다. 이 쿼리 속도를 초과하면 스로틀링이 발생할 수 있습니다. `Query`는 60초 후에 시간 초과됩니다. 60초의 제한 시간을 지원하도록 SDK의 기본 제한 시간을 업데이트해야 합니다. 자세한 내용은 [코드 샘플](https://docs.aws.amazon.com/timestream/latest/developerguide/code-samples.run-query.html)을 참조하세요. 다음과 같은 경우 쿼리 요청이 실패합니다. + 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" } ``` ## 요청 파라미터 모든 작업에 공통되는 파라미터에 대한 자세한 설명은 [공통 파라미터](CommonParameters.md)를 참조하세요. 요청은 JSON 형식으로 다음 데이터를 받습니다. ** [ClientToken](#API_query_Query_RequestSyntax) ** `Query` 요청 시 지정된 최대 64개의 ASCII 문자로 구성된 고유한 대소문자 구분 문자열입니다. `ClientToken`을 제공하면 `Query` *멱등성*이 직접적으로 호출됩니다. 즉, 동일한 쿼리를 반복적으로 실행하면 동일한 결과가 생성됩니다. 즉, 동일한 `Query` 요청을 여러 개 생성하는 것은 단일 요청을 생성하는 것과 같은 효과를 냅니다. 쿼리에서 `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`를 처음 실행하면 두 가지 경우에 쿼리의 결과 세트가 반환됩니다. + 결과의 크기가 `1MB`보다 작습니다. + 결과 세트의 행 수가 `maxRows` 값보다 작습니다. 그렇지 않으면 `Query`의 초기 간접 호출은 `NextToken`만 반환하며, 이후 직접 호출에서 결과 세트를 가져오는 데 사용할 수 있습니다. 페이지 매김을 재개하려면 후속 명령에 `NextToken` 값을 제공합니다. 행 크기가 큰 경우(예: 행에 열이 많은 경우) Timestream은 응답 크기가 1MB 제한을 초과하지 않도록 더 적은 수의 행을 반환할 수 있습니다. `MaxRows`가 제공되지 않으면 Timestream은 1MB 제한을 충족하는 데 필요한 수의 행을 전송합니다. 타입: 정수 유효한 범위: 최소값은 1입니다. 최대값은 1000입니다. 필수 여부: 아니요 ** [NextToken](#API_query_Query_RequestSyntax) ** 결과 세트를 반환하는 데 사용되는 페이지 매김 토큰입니다. `NextToken`을 사용하여 `Query` API를 간접적으로 호출하면 해당 특정 간접 호출은 `Query`에 대한 이전 직접 호출의 후속 간접 호출로 간주되고 결과 세트가 반환됩니다. 그러나 `Query` 간접 호출에 `ClientToken`만 포함된 경우 `Query`의 간접 호출은 새 쿼리 실행으로 간주됩니다. 쿼리에서 NextToken을 사용할 때 다음 사항에 유의하세요. + 페이지 매김 토큰은 최대 5개의 `Query` 간접 호출 또는 최대 1시간 중 먼저 도래하는 기간에 사용할 수 있습니다. + 동일한 `NextToken`을 사용하면 동일한 레코드 세트가 반환됩니다. 결과 세트를 계속 페이지 매김하려면 최신 `nextToken`을 사용해야 합니다. + `Query` 간접 호출이 `TokenA` 및 `TokenB`라는 두 `NextToken` 값을 반환한다고 가정해 보겠습니다. 후속 `Query` 간접 호출에서 `TokenB`를 사용하는 경우 `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. 최대 길이는 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" } ] } ] } ] } ``` ## 응답 요소 작업이 성공하면 서비스가 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 + [AWS 명령줄 인터페이스 V2](https://docs.aws.amazon.com/goto/cli2/timestream-query-2018-11-01/Query) + [AWS .NET V4용 SDK](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 Go용 SDK v2](https://docs.aws.amazon.com/goto/SdkForGoV2/timestream-query-2018-11-01/Query) + [AWS Java V2용 SDK](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 PHP V3용 SDK](https://docs.aws.amazon.com/goto/SdkForPHPV3/timestream-query-2018-11-01/Query) + [AWS Python용 SDK](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)