其他組態選項 - Amazon Redshift
字串資料欄的大小上限資料欄類型資料欄上的壓縮編碼資料欄的說明Redshift 和 Amazon S3 之間的身分驗證下推陳述式連接器參數

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

其他組態選項

在此頁面上，您可以找到可指定給 Amazon Redshift Spark 連接器的選項說明。

字串資料欄的大小上限

在建立儲存為 VARCHAR(256) 的資料表時，Redshift 會將字串資料欄建立為文字資料欄。如果你想要支援更大尺寸的資料欄，則可以使用 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 是，除非指定查詢 N/A 要在 Redshift 中建立或讀取的資料表。將資料儲存回 Redshift 時，需要此參數。
query 是，除非指定 dbtable N/A 要在 Redshift 中讀取的查詢。
使用者 否 N/A Redshift 的使用者名稱。必須與密碼參數搭配使用。只有在使用者和密碼不是 URL 中的參數時才有效。同時使用兩者會導致錯誤。
密碼 否 N/A Redshift 的密碼。必須與使用者參數搭配使用。只有在使用者和密碼不是 URL 中的參數時才有效。同時使用兩者會導致錯誤。
url 否 N/A

JDBC URL。格式為 jdbc:subprotocol://host:port/database?user=username&password=password。

視您已載入的 JDBC 驅動程序而定，子通訊協定可以是 postgresql 或 Redshift。請注意，一個與 Redshift 相容的驅動程式必須位於類別路徑中，並符合此 URL。

主機和連接埠應指向 Redshift 主節點，因此您必須將安全群組和/或 VPC 設定為允許從驅動程式應用程式存取。

資料庫是 Redshift 的資料庫名稱。

使用者和密碼是用來存取資料庫的憑證，必須內嵌在 JDBC 的這個 URL 中，而且資料庫使用者必須具備用來存取資料表的必要許可。
aws_iam_role 只有在使用 IAM 角色來授權 Redshift COPY/UNLOAD 操作時 N/A 附加至 Redshift 叢集之 IAM 角色的完整指定 ARN。
forward_spark_s3_credentials 否 False 指出此程式庫是否應自動探索 Spark 用來連線到 Amazon S3 的憑證，以及是否透過 JDBC 驅動程式將這些憑證轉送至 Redshift。這些憑證會在 JDBC 查詢中傳送。因此，建議您在使用此選項時，為 JDBC 連線啟用 SSL 加密。
temporary_aws_access_key_id 否 N/A AWS 存取金鑰。必須具有 S3 儲存貯體的寫入許可。
temporary_aws_secret_access_key 否 N/A AWS 對應至存取金鑰的秘密存取金鑰。
temporary_aws_session_token 否 N/A AWS 對應至所提供存取金鑰的工作階段字符。
tempdir 否 N/A Amazon S3 中的可寫入位置。用於在讀取時卸載資料，並在寫入時將 Avro 資料載入到 Redshift。如果您在一般 ETL 管道中使用適用於 Spark 的 Redshift 資料來源，則在儲存貯體上設定生命週期政策並將其作為此資料的暫存位置會很有用。
jdbcdriver 否 由 JDBC URL 的子通訊協定決定 要使用之 JDBC 驅動程式的類別名稱。這個類別必須在類別路徑上。在大多數情況下，應該不需要指定此選項，因為 JDBC URL 的子通訊協定應該會自動決定適當的驅動程式類別名稱。
diststyle 否 Even 在建立資料表時要使用的 Redshift 分散樣式。有效選項為 EVEN、KEY 或 ALL。使用 KEY 時，也必須使用 distkey 選項設定分散索引鍵。
distkey 否，除非使用 DISTSTYLE_KEY N/A 要在建立資料表時作為分散索引鍵的資料表資料欄名稱。
sortkeyspec 否 N/A 完整的 Redshift 排序索引鍵定義。
include_column_list 否 False 指出此程式庫是否應根據資料欄映射選項，自動從結構描述擷取資料欄，並將其新增至 COPY 命令。
description 否 N/A 資料表的描述。描述可使用 SQL COMMENT 命令加以設定，並且會出現在大多數查詢工具中。請參閱 description 中繼資料以設定個別資料欄的描述。
preactions 否 N/A 要在載入 COPY 命令前執行的分號分隔 SQL 命令清單。在載入新資料前先執行 DELETE 命令或類似命令可能會很有用。如果命令中包含 %s，則系統會在執行期之前先將資料表名稱格式化 (如果您使用的是暫存資料表)。如果此命令失敗，則系統會將其視為例外狀況。如果您使用的是暫存資料表，且預先處理失敗，則系統會回復變更並還原備份資料表。
extracopyoptions 否 N/A

載入資料時要附加至 Redshift COPY 命令的額外選項清單 (例如 TRUNCATECOLUMNS 或 MAXERROR n)。如需可用參數的完整清單，請參閱選用參數。

請注意，由於這些選項會附加到 COPY 命令的結尾，因此您只能使用在命令結尾上具有意義的選項。這應該涵蓋大多數可能的使用案例。
sse_kms_key 否 N/A 在 Redshift UNLOAD 操作期間用於 S3 中伺服器端加密的 AWS KMS AWS 金鑰 ID，而不是預設加密。Redshift IAM 角色必須具有 KMS 金鑰的存取權才能使用該金鑰來進行寫入，而 Spark IAM 角色必須具有該金鑰的存取權才能進行讀取操作。只要 Spark 的 IAM 角色具有適當的存取權，讀取加密的資料就不需要進行任何變更 (AWS 處理此問題）。
tempformat 否 AVRO 在寫入到 Redshift 時，用來在 Amazon S3 中儲存暫存檔案的格式。有效值為 AVRO、CSV 和 CSV GZIP (壓縮 CSV)。
csvnullstring (實驗性) 否 Null 使用 CSV tempformat 時為 Null 值寫入的字串值。這應該是不會出現在實際資料中的值。
autopushdown 否 True 指出是否要透過擷取和分析 SQL 操作的 Spark 邏輯計畫，以套用述詞和查詢下推。這些操作會轉換成 SQL 查詢，然後在 Redshift 中執行以提高效能。
autopushdown.s3_result_cache 否 False 快取查詢 SQL 以在記憶體中卸載 Amazon S3 路徑映射資料，因此不需要在相同的 Spark 工作階段中再次執行相同的查詢。只有在開啟 autopushdown 時才支援。在混合讀取和寫入操作時，不建議使用這個參數，因為快取的結果可能包含過時的資訊。
unload_s3_format 否 Parquet 用來卸載查詢結果的格式。有效選項為 Parquet 和文字，其會指定以豎線分隔的文字格式卸載查詢結果。
extraunloadoptions 否 N/A 要附加至 Redshift UNLOAD 命令的額外選項。並非所有選項都能保證運作，因為某些選項可能會與連接器內設定的其他選項衝突。
copydelay 否 30000 Redshift COPY 操作重試之間的延遲時間 (以毫秒為單位)。
copyretrycount 否 2 要重試 Redshift COPY 操作的次數。
tempdir_region 否 N/A

tempdir 所在的 AWS 區域。設定此選項可改善連接器與 tempdir 互動時的效能，並且會在連接器的讀取和寫入操作期間，自動於 COPY 和 UNLOAD 操作中提供此值。

建議在以下情況使用此設定：

1) 當連接器在外部執行時 AWS，因為自動區域探索將會失敗，並對連接器效能造成負面影響。

2) 當 tempdir 位於與 Redshift 叢集不同的區域時，因為使用此設定就比較不需要使用 extracopyoptions 和 extraunloadoptions 參數手動提供區域。使用 PARQUET 做為 tempformat 時，即使使用此參數，tempdir 也不能位於與 Redshift 叢集不同的區域。

3) 當連接器在與 tempdir 不同的區域中執行時，因為其會改善連接器對於 tempdir 的存取效能。
secret.id 否 N/A 儲存在 AWS Secrets Manager之機密的名稱或 ARN。您可以使用此參數自動提供 Redshift 憑證，但前提是使用者、密碼和 DbUser 憑證未傳遞到 JDBC URL 或做為其他選項來傳遞。
secret.region 否 N/A

主要 AWS 區域，例如美國東部 （維吉尼亞北部） 來搜尋secret.id值。

如果未指定此區域，連接器會嘗試使用預設憑證提供者鏈結來解析 secret.id 的區域。在某些情況下，例如您使用外部的連接器的話，連接器便找不到該區域。建議在以下情況使用此設定：

1) 當連接器在外部執行時 AWS，因為自動區域探索將會失敗，並阻止使用 Redshift 進行身分驗證

當連接器在與 secret.id 不同的區域中執行時，因為其會改善連接器對於機密的存取效能。
secret.vpcEndpointUrl 否 N/A 在覆寫預設憑證提供者鏈結時， AWS Secrets Manager 的 PrivateLink DNS 端點 URL。
secret.vpcEndpointRegion 否 N/A 在覆寫預設憑證提供者鏈結時， AWS Secrets Manager 的 PrivateLink DNS 端點區域。
jdbc.* 否 N/A 要傳遞給基礎 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 授權所開發的範例程式碼和語言。