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 Spark 커넥터에 지정할 수 있는 옵션에 관한 설명을 확인합니다.
## 문자열 열의 최대 크기
Redshift는 VARCHAR(256)로 저장되는 테이블 생성 시 문자열 열을 텍스트 열로 생성합니다. 더 큰 크기를 지원하는 열을 원하면 maxlength를 사용하여 문자열 열의 최대 길이를 지정할 수 있습니다. 다음은 `maxlength`를 지정하는 방법의 예입니다.
```
columnLengthMap.foreach { case (colName, length) =>
val metadata = new MetadataBuilder().putLong("maxlength", length).build()
df = df.withColumn(colName, df(colName).as(colName, metadata))
}
```
## 열 유형
열 유형을 설정하려면 `redshift_type` 필드를 사용합니다.
```
columnTypeMap.foreach { case (colName, colType) =>
val metadata = new MetadataBuilder().putString("redshift_type", colType).build()
df = df.withColumn(colName, df(colName).as(colName, metadata))
}
```
## 열에 대한 압축 인코딩
열에서 특정 압축 인코딩을 사용하려면 인코딩 필드를 사용하세요. 지원되는 압축 인코딩의 전체 목록은 [압축 인코딩](https://docs.aws.amazon.com/redshift/latest/dg/c_Compression_encodings.html)을 참조하세요.
## 열에 대한 설명
설명을 설정하려면 `description` 필드를 사용합니다.
## Redshift와 Amazon S3 간의 인증
기본적으로 결과는 Parquet 형식으로 Amazon S3에 언로드됩니다. 파이프로 구분된 텍스트 파일로 결과를 언로드하려면 다음 옵션을 지정합니다.
```
.option("unload_s3_format", "TEXT")
```
## 푸시다운 문
| 파라미터 | 필수 | 기본값 | 설명 |
| --- | --- | --- | --- |
| spark.datasource.redshift.community.autopushdown.lazyMode | 아니요 | True | 커넥터가 푸시다운 문 Redshift를 느리게 실행할지 여부를 지정합니다.
true인 경우 Spark 커넥터는 쿼리를 실행하기 전에 모든 관련 모델과 정보를 검색하므로 일반적으로 성능이 향상됩니다.
false인 경우 Spark 커넥터는 기본 Spark 드라이버 스레드에서 즉시 푸시다운 문을 실행하고 표현식 간에 직렬화됩니다. |
## 커넥터 파라미터
Spark SQL의 파라미터 맵 또는 `OPTIONS`는 다음 설정을 지원합니다.
| 파라미터 | 필수 | 기본값 | 설명 |
| --- | --- | --- | --- |
| dbtable | 예, query를 지정하지 않는 한 필요 | 해당 사항 없음 | Redshift에서 생성하거나 읽을 테이블입니다. 이 파라미터는 Redshift에 데이터를 다시 저장할 때 필요합니다. |
| 쿼리 | 예, dbtable을 지정하지 않는 한 필요 | 해당 사항 없음 | Redshift에서 읽을 쿼리입니다. |
| user | 아니요 | 해당 사항 없음 | Redshift 사용자 이름입니다. password 파라미터와 함께 사용해야 합니다. user 및 password가 URL의 파라미터가 아닌 경우에만 유효합니다. 둘 다 사용하면 오류가 발생합니다. |
| 암호 | 아니요 | 해당 사항 없음 | Redshift 암호입니다. user 파라미터와 함께 사용해야 합니다. user 및 password가 URL의 파라미터가 아닌 경우에만 유효합니다. 둘 다 사용하면 오류가 발생합니다. |
| url | 아니요 | 해당 사항 없음 | JDBC URL입니다. 형식은 jdbc:subprotocol://host:port/database?user=username&password=password입니다.
subprotocol은 로드한 JDBC 드라이버에 따라 postgresql 또는 Redshift가 될 수 있습니다. 하나의 Redshift 호환 드라이버가 클래스 경로에 있어야 하며 이 URL과 일치해야 합니다.
host와 port는 Redshift 마스터 노드를 가리켜야 하므로 드라이버 애플리케이션에서 액세스할 수 있도록 보안 그룹 및/또는 VPC를 구성해야 합니다.
database는 Redshift 데이터베이스 이름입니다.
user 및 password는 데이터베이스에 액세스하기 위한 보안 인증 정보로 JDBC의 경우 이 URL에 포함되어야 하며 데이터베이스 사용자는 테이블에 액세스하는 데 필요한 권한이 있어야 합니다. |
| aws\_iam\_role | IAM 역할을 사용하여 Redshift COPY/UNLOAD 작업을 승인하는 경우에만 필요 | 해당 사항 없음 | Redshift 클러스터에 연결된 IAM 역할의 전체 지정된 ARN입니다. |
| forward\_spark\_s3\_credentials | 아니요 | False | 이 라이브러리가 Spark가 Amazon S3에 연결하는 데 사용하는 자격 증명을 자동으로 검색할지와 해당 자격 증명을 JDBC 드라이버를 통해 Redshift로 전달할지를 나타냅니다. 이러한 자격 증명은 JDBC 쿼리의 일부로 전송됩니다. 따라서 이 옵션을 사용할 때는 JDBC 연결을 통한 SSL 암호화를 사용하도록 설정하는 것이 좋습니다. |
| temporary\_aws\_access\_key\_id | 아니요 | 해당 사항 없음 | AWS 액세스 키입니다. S3 버킷에 대한 쓰기 권한이 있어야 합니다. |
| temporary\_aws\_secret\_access\_key | 아니요 | 해당 사항 없음 | AWS액세스 키에 해당하는 비밀 액세스 키입니다. |
| temporary\_aws\_session\_token | 아니요 | 해당 사항 없음 | AWS제공된 액세스 키에 해당하는 세션 토큰입니다. |
| tempdir | 아니요 | 해당 사항 없음 | Amazon S3에서 쓰기 가능한 위치입니다. 읽을 때 데이터를 언로드하고 쓸 때 Avro 데이터를 Redshift로 로드하는 데 사용됩니다. 일반 ETL 파이프라인의 일부로 Spark용 Redshift 데이터 소스를 사용하는 경우 버킷에 [수명 주기 정책](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)을 설정하고 이를 이 데이터의 임시 위치로 사용하는 것이 유용할 수 있습니다. |
| jdbcdriver | 아니요 | JDBC URL의 하위 프로토콜에 의해 결정됨 | 사용할 JDBC 드라이버의 클래스 이름입니다. 이 클래스는 클래스 경로에 있어야 합니다. 대부분의 경우 적절한 드라이버 클래스 이름이 JDBC URL의 하위 프로토콜에 의해 자동으로 결정되어야 하므로 이 옵션을 지정할 필요가 없습니다. |
| diststyle | 아니요 | 짝수 | 테이블을 생성할 때 사용할 Redshift [분산 스타일](https://docs.aws.amazon.com/redshift/latest/dg/c_choosing_dist_sort.html)입니다. 유효한 옵션은 EVEN, KEY 또는 ALL입니다. KEY를 사용할 때 distkey 옵션으로 분산 키도 설정해야 합니다. |
| distkey | 아니요, DISTSTYLE\_KEY를 사용하지 않는 한 필요하지 않음 | 해당 사항 없음 | 테이블을 생성할 때 분산 키로 사용할 테이블의 열 이름입니다. |
| sortkeyspec | 아니요 | 해당 사항 없음 | Redshift [정렬 키](https://docs.aws.amazon.com/redshift/latest/dg/t_Sorting_data.html) 전체 정의입니다. |
| include\_column\_list | 아니요 | False | 이 라이브러리가 스키마에서 열을 자동으로 추출하고 [열 매핑 옵션](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-column-mapping.html)에 따라 COPY 명령에 추가해야 하는지 여부를 나타냅니다. |
| description | 아니요 | 해당 사항 없음 | 테이블에 대한 설명입니다. 설명은 SQL COMMENT 명령으로 설정되며 대부분의 쿼리 도구에 나타납니다. 개별 열에 대한 설명을 설정하려면 description 메타데이터를 참조하세요. |
| preactions | 아니요 | 해당 사항 없음 | COPY 명령을 로드하기 전에 실행할 SQL 명령의 세미콜론으로 구분된 목록입니다. 새 데이터를 로드하기 전에 DELETE 명령 또는 유사한 명령을 실행하는 것이 유용할 수 있습니다. 명령에 %s가 포함되어 있으면 런타임 전에 테이블 이름의 형식이 지정됩니다(스테이징 테이블을 사용하는 경우). 이 명령이 실패하면 예외로 처리됩니다. 스테이징 테이블을 사용하는 경우 사전 조치가 실패하면 변경 사항이 되돌려지고 백업 테이블이 복원됩니다. |
| extracopyoptions | 아니요 | 해당 사항 없음 | 데이터를 로드할 때 Redshift COPY 명령에 추가할 추가 옵션 목록(예: `TRUNCATECOLUMNS` 또는 `MAXERROR n`)입니다. 사용 가능한 파라미터의 전체 목록은 [선택적 파라미터](https://docs.aws.amazon.com/redshift/latest/dg/r_COPY.html#r_COPY-syntax-overview-optional-parameters)를 참조하세요.
이러한 옵션은 `COPY` 명령 끝에 추가되므로 명령 끝에 의미가 있는 옵션만 사용할 수 있습니다. 여기서는 가능한 대부분의 사용 사례를 다루어야 합니다. |
| sse\_kms\_key | 아니요 | 해당 사항 없음 | AWS 기본 암호화가 아닌 Redshift UNLOAD 작업 중에 S3에서 서버 측 암호화에 사용할 AWS KMS 키 ID입니다. Redshift IAM 역할은 쓰기를 위해 KMS 키에 액세스할 수 있어야 하며 Spark IAM 역할은 읽기 작업을 위해 키에 액세스할 수 있어야 합니다. 암호화된 데이터를 읽으려면 Spark의 IAM 역할에 적절한 액세스 권한이 있는 한 변경할 필요가 없습니다(AWS에서 처리). |
| tempformat | 아니요 | AVRO | Redshift에 쓸 때 Amazon S3에 임시 파일을 저장하는 형식입니다. 유효한 값은 AVRO, CSV, CSV GZIP(압축 CSV) 및 PARQUET입니다. |
| csvnullstring(실험용) | 아니요 | Null | CSV 임시 형식을 사용할 때 null에 쓸 문자열 값입니다. 실제 데이터에 나타나지 않는 값이어야 합니다. |
| autopushdown | 아니요 | True | SQL 작업에 대한 Spark 논리 계획을 캡처하고 분석하여 조건자 및 쿼리 푸시다운을 적용할지를 나타냅니다. 작업은 SQL 쿼리로 변환된 다음 Redshift에서 실행되어 성능이 향상됩니다. |
| autopushdown.s3\_result\_cache | 아니요 | False | 동일한 쿼리가 동일한 Spark 세션에서 다시 실행될 필요가 없도록 쿼리 SQL을 캐시하여 데이터 Amazon S3 경로 매핑을 메모리에서 언로드합니다. autopushdown이 켜져 있을 때만 지원됩니다. 캐시된 결과에 오래된 정보가 포함될 수 있으므로 읽기 및 쓰기 작업을 혼합할 때는 이 파라미터를 사용하지 않는 것이 좋습니다. |
| unload\_s3\_format | 아니요 | Parquet | 쿼리 결과를 언로드하는 형식입니다. 유효한 옵션은 쿼리 결과를 파이프로 구분된 텍스트 형식으로 언로드하도록 지정하는 Parquet 및 Text입니다. |
| extraunloadoptions | 아니요 | 해당 사항 없음 | Redshift [UNLOAD](https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD.html) 명령에 추가할 추가 옵션입니다. 일부 옵션은 커넥터 내에 설정된 다른 옵션과 충돌할 수 있으므로 모든 옵션의 작동이 보장되지는 않습니다. |
| copydelay | 아니요 | 30000 | Redshift COPY 작업에 대한 재시도 사이의 지연 시간(밀리초)입니다. |
| copyretrycount | 아니요 | 2 | Redshift COPY 작업을 재시도할 횟수입니다. |
| tempdir\_region | 아니요 | 해당 사항 없음 | `tempdir`이 있는 AWS 리전입니다. 이 옵션을 설정하면 커넥터의 읽기 및 쓰기 작업 중 복사 및 언로드 작업의 일부로 이 값을 자동으로 제공할 뿐만 아니라 `tempdir`과의 상호 작용에 대한 커넥터 성능이 향상됩니다.
이 설정은 다음과 같은 상황에서 권장됩니다.
1) 커넥터가 AWS 외부에서 실행되는 경우(자동 리전 검색이 실패하여 커넥터 성능에 부정적인 영향을 미침)
2) 이 설정을 사용하면 `extracopyoptions` 및 `extraunloadoptions` 파라미터를 사용하여 수동으로 리전을 제공할 필요가 없으므로, `tempdir`이 Redshift 클러스터와 다른 리전에 있는 경우 이 파라미터를 사용하더라도 `PARQUET`을 `tempformat`으로 사용하는 경우 `tempdir`이 Redshift 클러스터와 다른 리전에 있을 수 없습니다.
3) 커넥터가 `tempdir`과 다른 리전에서 실행되는 경우(`tempdir` 커넥터의 액세스 성능이 향상됨) |
| secret.id | 아니요 | 해당 사항 없음 | AWS Secrets Manager에 저장된 암호의 이름 또는 ARN입니다. 이 파라미터를 사용하여 사용자, 암호 및 DbUser 보안 인증 정보가 JDBC URL에 전달되지 않은 경우 또는 다른 옵션으로 전달된 경우에만 자동으로 Redshift 보안 인증을 제공할 수 있습니다. |
| secret.region | 아니요 | 해당 사항 없음 | `secret.id` 값을 검색할 기본 AWS 리전(예: 미국 동부(버지니아 북부))입니다.
이 리전을 지정하지 않으면 커넥터는 [기본 보안 인증 제공업체 체인](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)을 사용하여 `secret.id`의 리전을 확인하려고 시도합니다. 외부에서 커넥터를 사용하는 경우와 같이 일부 경우에는 커넥터가 리전을 찾지 못할 수 있습니다. 다음과 같은 상황에서 이 설정을 사용하는 것이 좋습니다.
1) 커넥터가 AWS 외부에서 실행 중인 경우 자동 리전 검색이 실패하여 Redshift를 통한 인증이 불가능합니다.
커넥터가 `secret.id`가 아닌 다른 리전에서 실행 중인 경우, 커넥터의 비밀 액세스 성능이 향상됩니다. |
| secret.vpcEndpointUrl | 아니요 | 해당 사항 없음 | [기본 보안 인증 제공업체 체인](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)을 재정의할 때 AWS Secrets Manager용 PrivateLink DNS 엔드포인트 URL입니다. |
| secret.vpcEndpointRegion | 아니요 | 해당 사항 없음 | [기본 보안 인증 제공업체 체인](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)을 재정의할 때 AWS Secrets Manager용 PrivateLink DNS 엔드포인트 리전입니다. |
| jdbc.\* | 아니요 | 해당 사항 없음 | 기본 JDBC 드라이버에 전달할 추가 파라미터로, 와일드카드는 JDBC 파라미터의 이름입니다(예: jdbc.ssl). JDBC 드라이버에 전달되기 전에 접두사 jdbc가 제거됩니다. Redshift JDBC 드라이버에 사용할 수 있는 모든 옵션을 보려면 [JDBC 드라이버 버전 2.x 구성 옵션](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-configuration-options.html)을 참조하세요. |
| 레이블 | 아니요 | " " | 커넥터로 쿼리를 실행할 때 쿼리 그룹 집합에 포함할 식별자입니다. 100자 이하여야 하며 모든 문자는 유효한 unicodeIdentifierParts여야 합니다. 식별자가 100자를 초과하는 경우 초과 문자는 제거됩니다. 커넥터로 쿼리를 실행할 때 쿼리 그룹은 다음과 같은 JSON 형식의 문자열로 설정됩니다.{"spark-redshift-connector":{"svc":"","ver":"5.1.0-amzn-1-spark_3.3","op":"Read","lbl":""}}`). 이 옵션은 lbl 키의 값을 대체합니다. |
**참고**
인정 조항: 이 문서에는 [Apache 2.0 라이선스](https://www.apache.org/licenses/LICENSE-2.0)에 따라 라이선스가 부여된 [Apache Software Foundation](http://www.apache.org/)에서 개발한 샘플 코드 및 언어가 포함되어 있습니다.