Amazon Redshift는 패치 198부터 새 Python UDF 생성을 더 이상 지원하지 않습니다. 기존 Python UDF는 2026년 6월 30일까지 계속 작동합니다. 자세한 내용은 [블로그 게시물](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)을 참조하세요.
# Amazon Redshift Spectrum의 쿼리 문제 해결
이 주제는 Amazon Redshift Spectrum 쿼리에서 발생할 수 있는 일반적인 문제에 대한 참조입니다.
Redshift Spectrum 쿼리에서 생성된 오류를 보려면 [SVL\$1S3LOG](r_SVL_S3LOG.md) 시스템 테이블에 대해 쿼리를 실행하십시오.
**Topics**
+ [재시도 횟수 초과](#spectrum-troubleshooting-retries-exceeded)
+ [액세스 조절됨](#spectrum-troubleshooting-access-throttled)
+ [리소스 제한 초과됨](#spectrum-troubleshooting-resource-limit-exceeded)
+ [파티셔닝된 테이블에 대해 반환된 행 없음](#spectrum-troubleshooting-no-rows-partitioned-table)
+ [권한 없음 오류](#spectrum-troubleshooting-not-authorized-error)
+ [호환되지 않는 데이터 형식](#spectrum-troubleshooting-incompatible-data-format)
+ [Amazon Redshift에서 Hive DDL을 사용할 때 구문 오류](#spectrum-troubleshooting-syntax-error-using-hive-ddl)
+ [임시 테이블을 생성할 수 있는 권한](#spectrum-troubleshooting-permission-to-create-temp-tables)
+ [잘못된 범위](#spectrum-troubleshooting-invalid-range)
+ [잘못된 Parquet 버전 번호](#spectrum-troubleshooting-invalid-parquet-version)
+ [외부 파티션 정보에서 필수 필드 누락](#spectrum-troubleshooting-required-field-missing)
## 재시도 횟수 초과
Amazon Redshift Spectrum 요청이 시간 초과되면 요청이 취소되고 다시 제출됩니다. 재시도가 5회 실패하면 다음 오류가 표시되면서 쿼리가 실패합니다.
```
error: Spectrum Scan Error: Retries exceeded
```
가능한 값은 다음을 포함합니다.
+ 큰 파일 사이즈(1GB 이상). Amazon S3의 파일 크기를 확인하고 큰 파일과 파일 크기 스큐를 찾습니다. 큰 파일은 100MB\$11GB의 작은 파일로 나눕니다. 파일의 크기를 거의 비슷하게 만드십시오.
+ 느린 네트워크 처리량. 쿼리를 나중에 시도하십시오.
## 액세스 조절됨
Amazon Redshift Spectrum은 다른 AWS 서비스의 서비스 할당량에 따라 달라질 수 있습니다. 사용량이 많으면 Redshift Spectrum 요청 속도가 느려져서 다음과 같은 오류가 발생할 수 있습니다.
```
error: Spectrum Scan Error: Access throttled
```
두 가지 유형의 조절이 발생할 수 있습니다.
+ Amazon S3에 의해 액세스가 제한됩니다.
+ AWS KMS에 의해 액세스 조절됨
오류 컨텍스트는 조절 유형에 대한 세부 정보를 제공합니다. 이를 통해 해당 조절에 대한 원인과 가능한 해결 방법을 찾을 수 있습니다.
### Amazon S3에 의해 액세스가 제한됨
Amazon S3는 [접두사](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#keyprefix)에 대한 읽기 요청 비율이 너무 높은 경우 Redshift Spectrum 요청을 제한할 수 있습니다. Amazon S3에서 달성할 수 있는 GET/HEAD 요청 속도에 대한 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*의 [Amazon S3 성능 최적화](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)를 참조하세요. Amazon S3 GET/HEAD 요청 빈도는 접두사의 모든 GET/HEAD 요청을 고려하므로 동일한 접두사에 액세스하는 다른 애플리케이션이 총 요청 빈도를 공유합니다.
Redshift Spectrum 요청이 Amazon S3에 의해 자주 제한되는 경우 Redshift Spectrum이 Amazon S3에 하는 Amazon S3 GET/HEAD 요청 수를 줄입니다. 이렇게 하려면 작은 파일을 큰 파일로 병합합니다. 64MB보다 큰 파일 크기를 사용하는 것이 좋습니다.
또한 초기 필터링의 이점을 활용하고 Amazon S3에서 액세스되는 파일 수를 줄이기 위해 Redshift Spectrum 테이블 분할을 고려합니다. 자세한 내용은 [Redshift Spectrum 외부 테이블 파티셔닝](c-spectrum-external-tables.md#c-spectrum-external-tables-partitioning) 섹션을 참조하세요.
### AWS KMS에서 액세스 조절됨
서버 측 암호화(SSE-S3 또는 SSE-KMS)를 사용하여 Amazon S3에 데이터를 저장하는 경우 Amazon S3에서는 Redshift Spectrum이 액세스하는 각 파일에 대해 AWS KMS에 API 작업을 호출합니다. 이러한 요청은 암호화 작업 할당량에 포함됩니다. 자세한 내용은 [AWS KMS 요청 할당량](https://docs.aws.amazon.com/kms/latest/developerguide/requests-per-second.html)을 참조하십시오. SSE-S3 및 SSE-KMS에 대한 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*의 [서버 측 암호화를 사용하여 데이터 보호](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html)와 [AWS KMS에 저장된 키를 사용하는 서버 측 암호화로 데이터 보호](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html)을 참조하세요.
Redshift Spectrum이 AWS KMS에 하는 요청 수를 줄이는 첫 번째 단계는 액세스되는 파일 수를 줄이는 것입니다. 이렇게 하려면 작은 파일을 큰 파일로 병합합니다. 64MB보다 큰 파일 크기를 사용하는 것이 좋습니다.
Redshift Spectrum 요청이 AWS KMS에 의해 자주 제한되는 경우 암호화 작업에 대한 AWS KMS 요청 빈도의 할당량 증가 요청을 고려합니다. 할당량 증가를 요청하려면 *Amazon Web Services 일반 참조*의 [AWS 서비스 제한](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html)을 참조하세요.
## 리소스 제한 초과됨
Redshift Spectrum은 요청이 사용할 수 있는 메모리 양에 상한을 적용합니다. 더 많은 메모리가 필요한 Redshift Spectrum 요청은 실패하고 결과적으로 다음 오류가 발생합니다.
```
error: Spectrum Scan Error: Resource limit exceeded
```
Redshift Spectrum 요청이 허용되는 메모리를 초과하여 실행할 수 있는 두 가지 일반적인 이유가 있습니다.
+ Redshift Spectrum은 더 작은 청크로 분할할 수 없는 큰 데이터 청크를 처리합니다.
+ 대규모 집계 단계가 Redshift Spectrum에 의해 처리됩니다.
분할 크기가 128MB 이하인 병렬 읽기를 지원하는 파일 형식을 사용하는 것이 좋습니다. 지원되는 파일 형식 및 데이터 파일 생성에 대한 일반 지침은 [Amazon Redshift Spectrum의 쿼리용 데이터 파일](c-spectrum-data-files.md) 섹션을 참조하세요. 병렬 읽기를 지원하지 않는 파일 형식이나 압축 알고리즘을 사용하는 경우 파일 크기를 64MB에서 128MB 사이로 유지하는 것이 좋습니다.
## 파티셔닝된 테이블에 대해 반환된 행 없음
파티셔닝된 외부 테이블에서 쿼리가 반환하는 행이 없다면 이 외부 테이블에 대해 파티션이 추가되었는지 확인합니다. Redshift Spectrum은 `ALTER TABLE … ADD PARTITION`을 사용하여 명시적으로 추가된, Amazon S3 위치에 있는 파일만을 스캔합니다. [SVV\$1EXTERNAL\$1PARTITIONS](r_SVV_EXTERNAL_PARTITIONS.md) 뷰를 쿼리하여 기존 파티션을 찾습니다. 누락된 각 파티션에 대해 `ALTER TABLE … ADD PARTITION`을 실행합니다.
## 권한 없음 오류
클러스터의 IAM 역할이 Amazon S3 파일 객체에 대한 액세스를 허용하는지 확인합니다. 외부 데이터베이스가 Amazon Athena에 있는 경우 IAM 역할이 Athena 리소스에 대한 액세스를 허용하는지 확인합니다. 자세한 내용은 [Amazon Redshift Spectrum에 대한 IAM 정책](c-spectrum-iam-policies.md) 섹션을 참조하세요.
## 호환되지 않는 데이터 형식
Apache Parquet 같은 컬럼 파일 형식의 경우 데이터에 열 유형이 포함되어 있습니다. CREATE EXTERNAL TABLE 정의의 열 유형이 데이터 파일의 열 유형과 일치해야 합니다. 일치하지 않으면 다음과 유사한 오류 메시지가 표시됩니다.
```
File 'https://s3bucket/location/file has an incompatible Parquet schema
for column ‘s3://s3bucket/location.col1'. Column type: VARCHAR, Par
```
위의 오류 메시지는 메시지 길이 제한으로 인해 잘릴 수도 있습니다. 이때 열 이름 및 형식을 포함하여 전체 오류 메시지를 가져오려면 [SVL\$1S3LOG](r_SVL_S3LOG.md) 시스템 뷰에 대해 쿼리를 실행하면 됩니다.
다음 예는 완료된 마지막 쿼리에 대해 SVL\$1S3QUERY를 쿼리합니다.
```
select message
from svl_s3log
where query = pg_last_query_id()
order by query,segment,slice;
```
다음은 결과가 전체 오류 메시지를 표시하는 예입니다.
```
message
–––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––-
Spectrum Scan Error. File 'https://s3bucket/location/file has an incompatible
Parquet schema for column ' s3bucket/location.col1'.
Column type: VARCHAR, Parquet schema:\noptional int64 l_orderkey [i:0 d:1 r:0]\n
```
오류를 수정하려면 Parquet 파일의 열 유형과 일치하도록 외부 테이블을 변경합니다.
## Amazon Redshift에서 Hive DDL을 사용할 때 구문 오류
Amazon Redshift는 Hive DDL과 비슷한 CREATE EXTERNAL TABLE용 DDL(데이터 정의 언어)을 지원합니다. 하지만 이 두 가지 DDL 유형이 항상 똑같은 것은 아닙니다. Hive DDL을 복사해 Amazon Redshift 외부 테이블을 생성하거나 변경하는 경우 구문 오류가 발생할 수 있습니다. 다음은 Amazon Redshift와 Hive DDL의 차이점의 예입니다.
+ Amazon Redshift에는 작은따옴표(')가 필요하지만 Hive DDL은 큰따옴표(")를 지원합니다.
+ Amazon Redshift는 STRING 데이터 형식을 지원하지 않습니다. 대신 VARCHAR를 사용하십시오.
## 임시 테이블을 생성할 수 있는 권한
Redshift Spectrum 쿼리를 실행하려면 데이터베이스 사용자가 데이터베이스에서 임시 테이블을 생성할 수 있는 권한을 보유해야 합니다. 다음 예에서는 `spectrumdb` 데이터베이스에 대한 임시 권한을 `spectrumusers` 사용자 그룹에 부여합니다.
```
grant temp on database spectrumdb to group spectrumusers;
```
자세한 내용은 [GRANT](r_GRANT.md) 섹션을 참조하세요.
## 잘못된 범위
Redshift Spectrum은 쿼리 중에 외부 테이블에 속한 Amazon S3 파일을 덮어쓰지 않을 것으로 예상합니다. 이 경우 다음 오류가 발생할 수 있습니다.
```
Error: HTTP response error code: 416 Message: InvalidRange The requested range is not satisfiable
```
이 오류를 방지하려면 Redshift Spectrum으로 쿼리되는 동안 Amazon S3 파일을 덮어쓰지 않아야 합니다.
## 잘못된 Parquet 버전 번호
Redshift Spectrum럼은 액세스하는 각 Apache Parquet 파일의 메타데이터를 확인합니다. 확인이 실패하면 다음과 비슷한 오류가 발생할 수 있습니다.
```
File 'https://s3.region.amazonaws.com/s3bucket/location/file has an invalid version number
```
확인이 실패하게 되는 두 가지 일반적인 이유가 있습니다.
+ 쿼리 중에 Parquet 파일을 덮어씁니다 ([잘못된 범위](#spectrum-troubleshooting-invalid-range) 참조).
+ Parquet 파일이 손상되었습니다.
## 외부 파티션 정보에서 필수 필드 누락
외부 카탈로그의 외부 테이블에 파티션을 추가하려고 할 때 다음 오류가 발생할 수 있습니다.
```
Error: The required field () is missing from the external partition information. Add missing field in partition and retry. Partition location:
```
이 오류는 쿼리에 사용된 외부 테이블의 파티션 중 하나에 파티션 메타데이터 정보가 누락되었음을 의미합니다. 이 동작은 다음과 같은 경우에 발생합니다.
+ 부분적 정보를 사용하여 AWS Glue Data Catalog와 같은 외부 카탈로그의 외부 테이블에 파티션을 추가했습니다.
+ AWS Glue Data Catalog와 같은 외부 카탈로그에서 해당 테이블에 대한 파티션을 추가하거나 업데이트하는 동안 Amazon Redshift에서 분할된 테이블을 쿼리했습니다.
다음은 AWS Glue Data Catalog에서 파티션을 검색할 때 채워야 하는 필드입니다.
+ StorageDescriptor
+ InputFormat
+ OutputFormat
+ SerDeInfo
+ 값
[SVV\$1EXTERNAL\$1PARTITIONS](r_SVV_EXTERNAL_PARTITIONS.md) 쿼리를 통해 기존 파티션을 찾고 해당 필드에 대한 세부 정보를 볼 수 있습니다.
AWS Glue Data Catalog 파티션 필드의 전체 목록은 *AWS Glue 웹 API 참조*의 [ 파티션](https://docs.aws.amazon.com/glue/latest/webapi/API_Partition.html)을 참조하세요.