其他配置选项 - Amazon Redshift
字符串列的最大大小列类型列上的压缩编码列的描述Redshift 和 Amazon S3 之间的身份验证下推语句连接器参数

其他配置选项

在本页中，您可以找到可为 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))
}

列上的压缩编码

要对列使用特定的压缩编码，请使用编码字段。有关支持的压缩编码的完整列表，请参阅压缩编码。

列的描述

要设置描述，请使用 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 是，除非指定了查询 不适用 要在 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。

根据您加载的 JDBC 驱动程序，子协议可以是 postgresql 或 Redshift。请注意，类路径中必须有一个兼容 Redshift 的驱动程序并且与此 URL 相匹配。

Host 和 port 应指向 Redshift 主节点，因此您必须配置安全组和/或 VPC 以允许从您的驱动程序应用程序访问。

数据库是 Redshift 数据库名称。

用户名和密码是用于访问数据库的凭证，必须将其嵌入到此 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 数据来源，则在存储桶上设置生命周期策略并将其用作这些数据的临时位置可能会很有用。
jdbcdriver 否 由 JDBC URL 的子协议确定 要使用的 JDBC 驱动程序的类名称。此类必须位于类路径上。在大多数情况下，不必指定此选项，因为相应的驱动程序类名应由 JDBC URL 的子协议自动确定。
diststyle 否 Even 创建表时使用的 Redshift 分配方式。有效选项为 EVEN、KEY 或 ALL。使用 KEY 时，还必须使用 distkey 选项设置分配键。
distkey 否，除非使用 DISTSTYLE_KEY 不适用 表中的列的名称，在创建表时用作分配键。
sortkeyspec 否 不适用 完整的 Redshift 排序键定义。
include_column_list 否 False 指示此库是否应根据列映射选项自动从 Schema 中提取列并将其添加到 COPY 命令。
description 否 不适用 表的描述。使用 SQL COMMENT 命令设置描述，并在大多数查询工具中显示。查看 description 元数据以设置各个列的描述。
preactions 否 不适用 在加载 COPY 命令之前要运行的以分号分隔的 SQL 命令列表。在加载新数据之前运行 DELETE 命令或类似命令时可能会很有用。如果命令包含 %s，则表名将在运行时之前格式化（如果您使用的是暂存表）。如果此命令失败，则将其视为异常。如果您使用的是暂存表，则在预处理失败时恢复更改并还原备份表。
extracopyoptions 否 不适用

加载数据时要附加到 Redshift COPY 命令的额外选项列表（例如 TRUNCATECOLUMNS 或 MAXERROR n）。有关可用参数的完整列表，请参阅可选参数。

请注意，由于这些选项附加到 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）。
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 命令的额外选项。并非所有选项都能确保正常工作，因为某些选项可能与连接器中设置的其他选项发生冲突。
copydelay 否 30000 Redshift COPY 操作两次重试之间的延迟（以毫秒为单位）。
copyretrycount 否 2 重试 Redshift COPY 操作的次数。
tempdir_region 否 不适用

tempdir 所在的 AWS 区域。设置此选项可提高与 tempdir 交互的连接器性能，以及在连接器的读取和写入操作期间，自动提供此值作为 COPY 和 UNLOAD 操作的一部分。

此设置推荐用于以下情况？

1) 当连接器在 AWS 外部运行时，此时自动区域发现将失败并对连接器性能产生负面影响。

2) 当 tempdir 与 Redshift 集群位于不同的区域时，此时使用此设置可以缓解使用 extracopyoptions 和 extraunloadoptions 参数手动提供此区域的需要。当使用 PARQUET 作为 tempformat 时，tempdir 不能位于与 Redshift 集群不同的区域中，即使使用此参数也是如此。

3) 当连接器运行在与 tempdir 不同的区域中时，此时可以提高连接器对 tempdir 的访问性能。
secret.id 否 不适用 存储在 AWS Secrets Manager 中的密钥的名称或 ARN。您可以使用此参数自动提供 Redshift 凭证，但前提是用户、密码和 DbUser 凭证不会传递到 JDBC URL 或作为其他选项传递。
secret.region 否 不适用

要搜索 secret.id 值的主要 AWS 区域，例如美国东部（弗吉尼亚州北部）。

如果您未指定此区域，连接器将尝试使用原定设置凭证提供者链以解析 secret.id 的区域。在某些情况下，例如，如果您在外部使用连接器，则连接器将无法找到该区域。我们建议在以下情况下使用此设置：

1) 当连接器在 AWS 外部运行时，此时自动区域发现功能将失败并阻止使用 Redshift 进行身份验证

当连接器在与 secret.id 不同的区域中运行时，此时可以提高连接器对密钥的访问性能。
secret.vpcEndpointUrl 否 不适用 覆盖原定设置凭证提供者链时 AWS Secrets Manager 的 PrivateLink DNS 端点 URL。
secret.vpcEndpointRegion 否 不适用 覆盖原定设置凭证提供者链时 AWS Secrets Manager 的 PrivateLink DNS 端点区域。
jdbc.* 否 不适用 要传递给底层 JDBC 驱动程序的其他参数，其中通配符是 JDBC 参数的名称，例如 jdbc.ssl。请注意，jdbc 前缀在传递给 JDBC 驱动程序之前将被删除。要查看 Redshift JDBC 驱动程序的所有可能选项，请参阅 JDBC 驱动程序版本 2.1 配置的选项。
label 否 " " 使用连接器运行查询时要包含在查询组集中的标识符。必须为 100 个或更少的字符，并且所有字符都必须是有效的 unicodeIdentifierParts。如果您的标识符超过 100 个字符，则多余的字符将被删除。使用连接器运行查询时，查询组将设置为 JSON 格式的字符串，例如 
{"spark-redshift-connector":{"svc":"","ver":"5.1.0-amzn-1-spark_3.3","op":"Read","lbl":""}}`)
。此选项将替换 lbl 密钥的值。
注意

致谢：本文档包含 Apache Software Foundation 根据 Apache 2.0 许可证的许可而开发的示例代码和语言。