Amazon Redshift 將不再支援從修補程式 198 開始建立新的 Python UDFs。現有 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 連接器指定之選項的說明。 ## 字串欄的大小上限 在建立儲存為 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)) } ``` ## 欄的壓縮編碼 若要在資料欄上使用特定的壓縮編碼，請使用編碼欄位。如需支援壓縮編碼的完整清單，請參閱[壓縮編碼](https://docs.aws.amazon.com/redshift/latest/dg/c_Compression_encodings.html)。 ## 欄的說明 若要設定描述，請使用 `description` 欄位。 ## Redshift 和 Amazon S3 之間的身分驗證 根據預設，結果會以 parquet 格式卸載到 Amazon S3。若要將結果卸載為以豎線分隔的文字檔案，請指定下列選項。 ``` .option("unload_s3_format", "TEXT") ``` ## Pushdown 陳述式 | 參數 | 必要 | 預設 | 說明 | | --- | --- | --- | --- | | 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 中讀取的查詢。 | | user | 否 | N/A | Redshift 的使用者名稱。必須與密碼參數搭配使用。只有在使用者和密碼不是 URL 中的參數時才有效。同時使用兩者會導致錯誤。 | | password | 否 | 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 資料來源，則在儲存貯體上設定[生命週期政策](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 | N/A | 要在建立資料表時作為分散索引鍵的資料表資料欄名稱。 | | sortkeyspec | 否 | N/A | 完整的 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 | 否 | N/A | 資料表的描述。描述可使用 SQL COMMENT 命令加以設定，並且會出現在大多數查詢工具中。請參閱 description 中繼資料以設定個別資料欄的描述。 | | preactions | 否 | N/A | 要在載入 COPY 命令前執行的分號分隔 SQL 命令清單。在載入新資料前先執行 DELETE 命令或類似命令可能會很有用。如果命令中包含 %s，則系統會在執行期之前先將資料表名稱格式化 (如果您使用的是暫存資料表)。如果此命令失敗，則系統會將其視為例外狀況。如果您使用的是暫存資料表，且預先處理失敗，則系統會回復變更並還原備份資料表。 | | extracopyoptions | 否 | N/A | 載入資料時要附加至 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 | 否 | 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) 和 PARQUET。 | | 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](https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD.html) 命令的額外選項。並非所有選項都能保證運作，因為某些選項可能會與連接器內設定的其他選項衝突。 | | 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 | 搜尋`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 | 否 | N/A | 在覆寫[預設憑證提供者鏈結](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)時， AWS Secrets Manager 的 PrivateLink DNS 端點 URL。 | | secret.vpcEndpointRegion | 否 | N/A | 在覆寫[預設憑證提供者鏈結](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)時， AWS Secrets Manager 的 PrivateLink DNS 端點區域。 | | jdbc.\* | 否 | N/A | 要傳遞給基礎 JDBC 驅動程式的其他參數，其中萬用字元是 JDBC 參數的名稱，例如 jdbc.ssl。請注意，在傳遞給 JDBC 驅動程序之前，會先刪除 jdbc 字首。若要查看 Redshift JDBC 驅動器的所有可能選項，請參閱 [JDBC 驅動器 2.x 版組態的選項](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-configuration-options.html)。 | | 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](http://www.apache.org/) 根據 [Apache 2.0 授權](https://www.apache.org/licenses/LICENSE-2.0)所開發的範例程式碼和語言。