从补丁 198 开始，Amazon Redshift 将不再支持创建新的 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/)。

# 其他配置选项
<a name="spark-redshift-connector-other-config"></a>

在本页中，您可以找到可为 Amazon Redshift Spark 连接器指定的选项的说明。

## 字符串列的最大大小
<a name="spark-redshift-connector-other-config-max-size"></a>

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))
}
```

## 列类型
<a name="spark-redshift-connector-other-config-column-type"></a>

要设置列类型，请使用 `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))
}
```

## 列上的压缩编码
<a name="spark-redshift-connector-other-config-compression-encoding"></a>

 要对列使用特定的压缩编码，请使用编码字段。有关支持的压缩编码的完整列表，请参阅[压缩编码](https://docs.aws.amazon.com/redshift/latest/dg/c_Compression_encodings.html)。

## 列的描述
<a name="spark-redshift-connector-other-config-description"></a>

要设置描述，请使用 `description` 字段。

## Redshift 和 Amazon S3 之间的身份验证
<a name="spark-redshift-connector-other-config-unload-as-text"></a>

 默认情况下，结果将以 Parquet 格式转存到 Amazon S3。要以竖线分隔的文本文件转存结果，请指定以下选项。

```
.option("unload_s3_format", "TEXT")
```

## 下推语句
<a name="spark-redshift-connector-other-config-lazy-pushdown"></a>


| 参数 | 必需  | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| spark.datasource.redshift.community.autopushdown.lazyMode | 否 | True | 指定连接器是否应延时运行下推语句 Redshift。<br />如果为 true，则 spark 连接器会在运行查询之前检索所有相关的模型和信息，这通常会产生更好的性能。<br />如果为 false，则 spark 连接器会立即在 Spark 驱动程序主线程中运行下推语句，并跨表达式进行序列化。 | 

## 连接器参数
<a name="spark-redshift-connector-other-config-spark-parameters"></a>

Spark SQL 中的参数映射或 `OPTIONS` 支持以下设置。


| 参数 | 必需  | 默认值 | 说明 | 
| --- | --- | --- | --- | 
| dbtable | 是，除非指定了查询 | 不适用 | 要在 Redshift 中创建或读取的表。将数据保存回 Redshift 时需要此参数。 | 
| 查询 | 是，除非指定了 dbtable | 不适用 | 要在 Redshift 中读取的查询。 | 
| 用户 | 否 | 不适用 | Redshift 用户名。必须与 password 参数一起使用。仅当 user 和 password 不是 URL 中的参数时才有效。同时使用两者会引发错误。 | 
| password | 否 | 不适用 | Redshift 密码。必须与 user 参数一起使用。仅当 user 和 password 不是 URL 中的参数时才有效。同时使用两者会引发错误。 | 
| url | 否 | 不适用 | JDBC URL。格式为 jdbc:subprotocol://host:port/database?user=username&password=password。<br />根据您加载的 JDBC 驱动程序，子协议可以是 postgresql 或 Redshift。请注意，类路径中必须有一个兼容 Redshift 的驱动程序并且与此 URL 相匹配。<br /> Host 和 port 应指向 Redshift 主节点，因此您必须配置安全组和/或 VPC 以允许从您的驱动程序应用程序访问。<br /> 数据库是 Redshift 数据库名称。<br /> 用户名和密码是用于访问数据库的凭证，必须将其嵌入到此 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 | 否 | Even | 创建表时使用的 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)自动从 Schema 中提取列并将其添加到 COPY 命令。 | 
| 描述 | 否 | 不适用 | 表的描述。使用 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)。<br />请注意，由于这些选项附加到 `COPY` 命令的末尾，因此只能使用在命令末尾有意义的选项。这应该涵盖最有可能的使用案例。 | 
| sse\_kms\_key | 否 | 不适用 | 在 Redshift UNLOAD 操作期间，为 S3 中的服务器端加密使用 AWS KMS 密钥 ID，而不是使用 AWS 默认加密。Redshift IAM 角色必须能够访问 KMS 密钥，这样才能使用它进行写入，而 Spark IAM 角色必须能够访问密钥，这样才能执行读取操作。只要 Spark 的 IAM 角色具有适当的访问权限，读取加密的数据就不需要更改（AWS 处理此任务）。 | 
| 临时格式 | 否 | AVRO | 写入 Redshift 时在 Amazon S3 中保存临时文件的格式。有效值为 AVRO、CSV、CSV GZIP（压缩的 CSV）和 PARQUET。 | 
| cvsnullstring（实验） | 否 | Null |  使用 CSV 临时格式时要为空值写入的字符串值。这应该是一个不会出现在实际数据中的值。 | 
| autopushdown | 否 | True | 指示是否通过捕获和分析 SQL 操作的 Spark 逻辑计划来应用谓词和查询下推。这些操作转换为 SQL 查询，然后在 Redshift 中运行以提高性能。 | 
| autopushdown.s3\_result\_cache | 否 | False | 缓存查询 SQL 以在内存中转存数据 Amazon S3 路径映射，这样就无需在同一 Spark 会话中再次运行相同的查询。仅在开启自动下推时支持。因为缓存的结果可能包含陈旧信息，我们不建议在混合读取和写入操作时使用此参数。 | 
| 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` 交互的连接器性能，以及在连接器的读取和写入操作期间，自动提供此值作为 COPY 和 UNLOAD 操作的一部分。<br /> 此设置推荐用于以下情况？<br />1) 当连接器在 AWS 外部运行时，此时自动区域发现将失败并对连接器性能产生负面影响。<br />2) 当 `tempdir` 与 Redshift 集群位于不同的区域时，此时使用此设置可以缓解使用 `extracopyoptions` 和 `extraunloadoptions` 参数手动提供此区域的需要。当使用 `PARQUET` 作为 `tempformat` 时，`tempdir` 不能位于与 Redshift 集群不同的区域中，即使使用此参数也是如此。<br /> 3) 当连接器运行在与 `tempdir` 不同的区域中时，此时可以提高连接器对 `tempdir` 的访问性能。 | 
| secret.id | 否 | 不适用 | 存储在 AWS Secrets Manager 中的密钥的名称或 ARN。您可以使用此参数自动提供 Redshift 凭证，但前提是用户、密码和 DbUser 凭证不会传递到 JDBC URL 或作为其他选项传递。 | 
| secret.region | 否 | 不适用 | 要搜索 `secret.id` 值的主要 AWS 区域，例如美国东部（弗吉尼亚州北部）。<br />如果您未指定此区域，连接器将尝试使用[原定设置凭证提供者链](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)以解析 `secret.id` 的区域。在某些情况下，例如，如果您在外部使用连接器，则连接器将无法找到该区域。我们建议在以下情况下使用此设置：<br />1) 当连接器在 AWS 外部运行时，此时自动区域发现功能将失败并阻止使用 Redshift 进行身份验证<br />当连接器在与 `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 格式的字符串，例如 <pre>{"spark-redshift-connector":{"svc":"","ver":"5.1.0-amzn-1-spark_3.3","op":"Read","lbl":""}}`)</pre>。此选项将替换 lbl 密钥的值。 | 

**注意**  
 致谢：本文档包含 [Apache Software Foundation](http://www.apache.org/) 根据 [Apache 2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0)的许可而开发的示例代码和语言。