全部產品
Search

搜尋本產品

    MaxCompute：通用配置

    文件中心

    MaxCompute：通用配置

    更新時間：Mar 13, 2026

    本文介紹Spark用戶端各個版本的通用參數配置。

    MaxCompute帳號參數配置

    參數

    說明

    spark.hadoop.odps.project.name

    MaxCompute專案名稱。

    若使用DataWorks提交任務，使用預設值即可，無需配置。

    spark.hadoop.odps.access.id

    具備目標MaxCompute專案存取權限的AccessKey ID，可以進入AccessKey管理頁面擷取AccessKey ID。

    若使用DataWorks提交任務，使用預設值即可，無需配置。

    spark.hadoop.odps.access.key

    AccessKey ID對應的AccessKey Secret。

    若使用DataWorks提交任務，使用預設值即可，無需配置。

    spark.hadoop.odps.access.security.token

    MaxCompute專案STS Token。

    若使用DataWorks提交任務，使用預設值即可，無需配置。

    spark.hadoop.odps.end.point

    • MaxCompute所屬Region獨享的公網Endpoint或VPC Endpoint。設定為公網 Endpoint 或 VPC Endpoint取決於 Spark 用戶端所處網路環境。Dataworks 提交任務使用預設值即可，無需配置。

    • 例如，杭州VPC Endpoint為https://service.cn-hangzhou-vpc.maxcompute.aliyun-inc.com/api

    spark.hadoop.odps.runtime.end.point

    MaxCompute所屬Region的雲產品互聯 Endpoint。

    例如，杭州雲產品互聯Endpoint為https://service.cn-hangzhou-intranet.maxcompute.aliyun-inc.com/api

    MaxCompute Spark作業提交、版本及日誌等配置

    參數

    說明

    spark.hadoop.odps.kube.mode

    • 預設值 false。

    • 該配置參數表明是否使用 Kubernetes（k8s）模式提交作業，目前MaxCompute Spark已經全面升級為kube模式，舊版cupid模式將下線。

    • 新使用者使用時請確保開啟該配置。

    spark.hadoop.odps.cupid.data.proxy.enable

    • 預設值 false。

    • 該配置參數表明在讀寫資料的介面是否使用MaxStorage。

    • 不開啟可能會導致無法使用 kube 模式，確保使用 kube 模式時開啟該選項。

    spark.hadoop.odps.cupid.fuxi.shuffle.enable

    • 預設值 false

    • 該配置參數表明是否在 shuffle 時使用 Fuxi Shuffle Service，防止使用本地碟導致儲存空間溢出。

    • 作業規模較大或者遇到儲存滿盤的問題建議開啟。

    spark.hadoop.odps.spark.version

    • 提交Spark任務所用的Spark版本，版本可參見Spark發布列表。例如spark-3.1.1-odps0.35.0。

    • 當通過Spark用戶端提交任務時，需要同時配置spark.hadoop.odps.spark.libs.public.enable為true

    spark.hadoop.odps.spark.libs.public.enable

    • 預設值 false。設定為true後，可以免上傳Spark libs，直接從服務端拉取，加速啟動。

    • 需同時配置spark.hadoop.odps.spark.version指定版本後才可生效。

    spark.eventLog.enabled

    • 預設值 false。該配置參數表明開啟eventLog以便查看SparkUI history。

    • 建議開啟以便排查問題，kube 模式下需要配合設定spark.eventLog.dir。

    spark.eventLog.dir

    • 預設值 /tmp/spark-events/ 或 /workdir/eventlog（視版本而定）。

    • 該配置參數表明eventLog的儲存位置，如果參數錯誤，則無法上傳eventLog以查看history。

    • kube 模式下推薦手動設定為/workdir/eventlog/。

    Spark資源申請參數配置

    參數

    說明

    spark.executor.instances

    預設值1。Spark 應用程式在叢集中啟動的Executor進程總數。

    spark.executor.cores

    預設值1。每個Executor進程可使用的CPU核心數。

    spark.executor.memory

    預設值 2g。每個Executor進程的記憶體總量（包括堆內和堆外記憶體）。

    spark.driver.cores

    預設值 1。Driver進程使用的CPU核心數。

    spark.driver.memory

    預設值 2g。Driver進程的記憶體總量。

    spark.executor.memoryOverhead

    • 預設值 參考社區配置。當堆外記憶體使用量比較多時建議提高此值避免整體記憶體超出被Kill。

    • 單個Executor的記憶體總量是spark.executor.memory+spark.executor.memoryOverhead。

    spark.driver.memoryOverhead

    • 預設值 參考社區配置。當堆外記憶體使用量比較多時建議提高此值避免整體記憶體超出被Kill。

    • Driver的記憶體總量是spark.driver.memory+spark.driver.memoryOverhead。

    spark.hadoop.odps.cupid.disk.driver.device_size

    • 預設值 20g。本地網盤大小，當出現No space left on device時可適當調大該值，最大支援100g。

    • 必須配置在spark-defaults.conf檔案或者DataWorks的配置項中才可生效，不能配置在代碼中。

    MaxCompute讀寫相關配置

    重要

    以下以spark.sql.catalog.odps開頭的配置僅在 3.x 版本中才可以使用。

    參數

    說明

    spark.sql.catalog.odps.tableReadProvider

    • 預設值 v1

    • 使用Local模式時需要設定為tunnel

    spark.sql.catalog.odps.tableWriteProvider

    • 預設值 v1

    • 使用Local模式時需要設定為tunnel

    spark.sql.catalog.odps.metaCacheSize

    • 預設值 100

    • 中繼資料快取的最大條數（包括project、schema、table的中繼資料快取），用於加速讀寫，不建議改動。

    spark.sql.catalog.odps.metaCacheExpireSeconds

    • 預設值 30

    • 單位為秒。中繼資料快取到期時間，用於加速讀寫，不推薦增大（除非涉及的表使用很頻繁且不變化，否則容易導致讀到髒資料）。

    spark.sql.catalog.odps.viewCacheExpireSeconds

    • 預設值 3600

    • 單位為秒。視圖中繼資料快取到期時間，不推薦修改。

    spark.sql.catalog.odps.enableVectorizedReader

    • 預設值 true

    • 表示是否使用向量化讀，不推薦修改。

    spark.sql.catalog.odps.enableVectorizedWriter

    • 預設值 true

    • 表示是否使用向量化寫，不推薦修改。

    spark.sql.catalog.odps.columnarReaderBatchSize

    • 預設值 4096

    • 表示讀取時一個批次的資料行數大小。

    spark.sql.catalog.odps.columnarWriterBatchSize

    • 預設值 4096

    • 表示寫入時一個批次的資料行數大小。

    spark.sql.catalog.odps.splitParallelism

    • 預設值 -1

    • 表示底層儲存分割時並行度大小，必須大於0才生效。

    • 不要輕易設定該選項，當前預設使用splitByRowOffset或splitByByteSize，此時計算出的分區大小更合適。

    spark.sql.catalog.odps.splitSizeInMB

    • 預設值 256

    • 單位為 MB。表示每個分區大小，可以通過調小該值來增大讀取的並發度，反之亦然。

    spark.sql.catalog.odps.enableExternalProject

    • 預設值 false

    • 是否開啟支援外部項目。

    spark.sql.catalog.odps.enableExternalTable

    • 預設值 false

    • 是否開啟支援外部表格。

    spark.sql.catalog.odps.tableCompressionCodec

    • 預設值 none

    • 對錶的壓縮演算法，預設為空白，目前支援lz4_frame和zstd。

    spark.sql.catalog.odps.enableNamespaceSchema

    • 預設值 false

    • 是否支援MaxCompute Schema級文法開關。

    spark.sql.catalog.odps.defaultSchema

    • 預設值 default

    • 預設的schemaName，建議不要修改。

    spark.sql.catalog.odps.writerChunkSize

    • 預設值 4194304

    • 寫入時chunk大小，單位為位元組，預設為 4MB。

    spark.sql.catalog.odps.writerMaxRetires

    • 預設值 10

    • 寫入失敗後的重試次數。

    spark.sql.catalog.odps.writerRetrySleepIntervalMs

    • 預設值 10000

    • 寫入失敗後重試的間隔時間，單位為毫秒。

    spark.sql.catalog.odps.writerBlocks

    • 預設值 20000

    • 寫入的最大block數量。

    spark.sql.catalog.odps.splitSessionParallelismEnable

    • 預設值 true

    • 是否在分區維度並行得到讀取資料。

    spark.sql.catalog.odps.splitSessionParallelism

    • 預設值 1

    • 在分區維度得到讀取資料的並行線程數。

    • 通常該參數的配置不會成為效能瓶頸，除非裁剪後的分區數量仍然非常多，此時可以考慮調整該參數。

    spark.sql.catalog.odps.splitMaxFileNum

    • 預設值 0

    • 底層單個分區的檔案數量最大值，預設為0表示不設限。

    • 如果小檔案過多導致單個 split 讀取時間過長可以設定該參數來增多 split 數量以調動更多 reader 讀取提高速度。

    spark.sql.catalog.odps.splitMaxWaitTime

    • 預設值 15

    • 單位為分鐘。表示分區的等待時間，如果分區時間過長可以調大該值。

    spark.sql.catalog.odps.enableFilterPushDown

    • 預設值 false

    • 是否在Spark層面開啟謂詞下推。

    spark.sql.catalog.odps.enableDeltaInsertDeduplicate

    • 預設值 false

    • 是否在分區內去重，如果是 transactional 且 overwrite 寫入預設會去重。

    spark.sql.catalog.odps.maxFieldSizeInMB

    • 預設值 -1

    • 單位為 MB。表示VARCHAR/CHAR/STRING/BINARY類型寫入的最大大小，預設的 -1 表示8MB。

    • 設定該參數時，內建的上限為專案級參數odps.sql.cfile2.field.maxsize大小。

    spark.sql.catalog.odps.splitReaderNum

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 1

    • 讀取並發數量，當 CPU 不是效能瓶頸時可以通過設定該選項來加快讀取速度（不推薦超過 4，實際請以接近 CPU 瓶頸的並發數作為上限，繼續上升反而會導致效能下降）

    • 該配置參數無論是否開啟asnycRead和batchReused都會生效。

    spark.sql.catalog.odps.enableBatchReused

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 true

    • 表示是否複用 batch，用於減少讀資料時的記憶體使用量量。如果設定為false建議開啟非同步讀，通過空間換時間的策略來加快讀取速度，但是需要注意記憶體容量大小。

    • 如果設定asyncRead且readNum為1時會忽略該參數並強行不複用 batch 以實作類別似bufferRead的效果。

    spark.sql.catalog.odps.enableAsyncRead

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 false

    • 開啟非同步讀，通過空間換時間的策略加快讀取速度，需要注意記憶體容量大小。

    • 建議配合readerNum和batchReused參數使用以達到讀取效率最大化，詳情參考asyncQueueSize參數配置。

    spark.sql.catalog.odps.asyncQueueSize

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 8

    • 非同步讀時的 buffer 大小，需要注意記憶體容量大小。

    • 如果開啟非同步讀並且設定batchReused=false時，該參數即為實際隊列大小。確保queueSize >= readerNum，否則有可能導致效率無法拉滿。

    • 如果開啟非同步讀並且設定batchReused=true，實際隊列大小為readerNum，此時如果想reuseBatch切記不要設定readNum=1。

    spark.sql.catalog.odps.enhanceWriteCheck

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 false

    • 是否在寫入的時候開啟正確性檢查。

    spark.sql.catalog.odps.dynamicPartitionLimit

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 512

    • 寫入時允許建立的動態分區數量上限。

    spark.sql.catalog.odps.streamingWriteLimit

    • 該參數僅在Spark 版本>=3.4 時開啟，低版本無效。

    • 預設值 60

    • 單位為秒，流式寫入時建立writeSession的時間間隔限流，預設表示 60s 一次，下限為 30s 一次。

    MaxCompute資料互連配置

    spark.hadoop.odps.cupid.resources

    該配置項必須要配置在spark-default.conf中或DataWorks的配置項中才會生效，不能寫在代碼中。

    • 參數說明：

      指定任務運行所需要的MaxCompute資源。格式為<projectname>.<resourcename>，可指定多個，通過半形逗號（,）分隔。

      指定的資源將被下載到Driver和Executor的當前工作目錄（/workdir），資源下載到工作目錄後預設的名字是<projectname>.<resourcename>。壓縮包資源會被自動解壓，頂層目錄名字與原壓縮包名字保持一致。例如資源名為examples.tar.gz且未重新命名，其展開路徑為/workdir/examples.tar.gz/sub/...。如果重新命名為examples，則展開路徑為/workdir/examples/sub/...，具體路徑取決於包名字和包內部的目錄結構。

    • 配置樣本：spark.hadoop.odps.cupid.resources = public.python-python-2.7-ucs4.zip,public.myjar.jar。

    • 檔案重新命名：配置時通過<projectname>.<resourcename>:<newresourcename>方式重新命名。

    • 重新命名樣本：spark.hadoop.odps.cupid.resources = public.myjar.jar:myjar.jar。

    MaxCompute其他配置

    參數

    說明

    spark.hadoop.odps.cupid.eni.enable & spark.hadoop.odps.cupid.eni.info

    用於配置 VPC，詳細內容請參考訪問阿里雲VPC

    spark.hadoop.odps.cupid.trusted.services.access.list

    無預設值。如果在Spark叢集模式下，訪問雲產品互聯網站網路不通，請配置該參數（可以參考訪問阿里雲OSS)。

    spark.hadoop.odps.cupid.smartnat.enable

    • 預設值 false

    • 開啟以用於訪問公網。

    spark.hadoop.odps.cupid.internet.access.list

    • 預設值 無

    • 訪問公網開關開啟後，需要設定對應的白名單才可以訪問（可以參考訪問公網)。

    spark.hadoop.odps.spark.alinux3.enabled

    • 預設值 false

    • 叢集模式下開啟後使用 alinux3 base 鏡像，使用 Python 3.11 版本。

    spark.hadoop.odps.native.engine.enable

    • 預設值 false

    • 叢集模式下使用 Native Engine(Gluten) 加速計算，Native Engine 預設使用 alinux3 base 鏡像。

    spark.hadoop.odps.spark.metrics.enable

    • 預設值 false

    • 是否在Spark內部採集指標資料，開啟後指標資料更加準確。