MaxFrame menyediakan dua lapisan konfigurasi: flag MaxCompute (pengaturan tingkat SQL yang mengontrol cara eksekusi setiap job) dan opsi MaxFrame (pengaturan waktu proses yang mengatur sesi, sumber daya, dan perilaku klien). Panduan ini mencakup kedua lapisan tersebut—tujuannya, nilai default-nya, serta kapan harus mengubahnya.
Penting
Banyak flag tingkat lanjut memerlukan whitelisting sebelum berlaku. Hubungi tim dukungan teknis MaxCompute sebelum mengonfigurasi opsi tingkat ahli.
Cara mengatur flag
Semua flag SQL MaxCompute dimasukkan ke dalam kamus options.sql.settings. Opsi MaxFrame diatur langsung menggunakan options.<name>.
from maxframe import options
# Flag SQL MaxCompute — diatur melalui options.sql.settings
options.sql.settings = {
"odps.sql.job.max.time.hours": 72,
"odps.session.image": "common",
"odps.sql.split.dop": '{"*":50000}',
"odps.sql.executionengine.batch.rowcount": 1024,
}
# Opsi MaxFrame — diatur langsung
options.session.logview_hours = 24
options.retry_times = 3
options.sql.enable_mcqa = TrueTemukan flag berdasarkan masalah
Gunakan tabel berikut untuk langsung menuju flag yang paling relevan dengan masalah tertentu.
| Masalah | Flag terkait |
|---|---|
| Job split lambat | odps.sql.split.dop, odps.sql.split.cluster.parallel_explore |
| Error out-of-memory (OOM) | odps.stage.mapper.mem, odps.stage.reducer.mem, odps.stage.joiner.mem, odps.sql.executionengine.batch.rowcount |
| Shuffle skala besar gagal atau lambat | fuxi_streamline_x_EnableNormalCheckpoint, fuxi_ShuffleService_client_CheckpointMaxCopy, odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize |
| Data skew pada GROUP BY atau JOIN | odps.stage.reducer.num, odps.stage.joiner.num |
| UDF (User-Defined Function) berjalan lama tiba-tiba dihentikan | odps.sql.runtime.flag.fuxi_EnableInstanceMonitor, fuxi_InstanceMonitorTimeout, odps.sql.udf.timeout, odps.function.timeout |
| Statistik column-store (CMF) tidak dihasilkan setelah menulis ke tabel partisi dinamis | Kombinasi tetap penulisan tabel dan CMF |
| Job gagal karena error mesin sementara | odps.job.instance.retry.times |
| Log Python UDF terpotong | odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize |
| Perlu menggunakan runtime image atau versi MaxCompute tertentu | odps.session.image, odps.task.major.version |
Flag MaxCompute
Flag berikut diatur melalui options.sql.settings.
Konkurensi dan chunking
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.sql.split.dop | Menetapkan degree of parallelism (DOP) untuk pembacaan data per tabel, menggunakan informasi statistik column-store (CMF). Memiliki prioritas lebih tinggi daripada split.size. Format: {"table_name": value}. Gunakan project.[schema.]table untuk nama lengkap. Gunakan {"*": value} untuk menargetkan semua tabel. Rentang: 1–99999. | None | Saat memproses tabel besar atau menjalankan tugas skala besar, aktifkan parameter ini secara eksplisit untuk mencapai konkurensi tinggi. |
odps.stage.mapper.split.size | Saat CMF tidak tersedia, membagi tugas berdasarkan ukuran tabel input dalam MB. Rentang: ≥1 MB. | 256 MB | Pertahankan nilai default. |
Resource dan memori
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.stage.mapper.mem / odps.stage.reducer.mem / odps.stage.joiner.mem | Memori dalam MB yang dialokasikan untuk satu worker pada tahap Mapper, Reducer, dan Joiner, masing-masing. Rentang: 1024–12288 MB. | 1024 MB | Tingkatkan saat memproses volume data yang besar, menghadapi hot spot data, atau mengalami error OOM akibat join yang kompleks. |
odps.stage.reducer.num / odps.stage.joiner.num | Jumlah instans konkuren untuk tahap Reduce dan Join. Maksimum: 10.000. | Dihitung secara dinamis | Tingkatkan untuk shuffle skala besar (GROUP BY atau JOIN) atau saat data skew menyebabkan satu instans menangani beban yang tidak proporsional. |
Shuffle dan keamanan output
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.sql.runtime.flag.fuxi_streamline_x_EnableNormalCheckpoint & fuxi_ShuffleService_client_CheckpointMaxCopy | Mengaktifkan backup untuk output Mapper antara dan menetapkan jumlah replika. | — | Untuk job berjalan lama dengan shuffle skala besar, atur replika menjadi 2: "fuxi_ShuffleService_client_CheckpointMaxCopy": 2. Ini secara signifikan meningkatkan toleransi kesalahan dan stabilitas pembacaan data selama shuffle. |
odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize | Ukuran total maksimum dalam MB untuk data shuffle antara yang dihasilkan oleh satu job. | — | Tingkatkan saat job gagal dengan pesan Internal data size exceeds limit selama shuffle tabel besar. |
Stabilitas komputasi dan pemantauan
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.sql.runtime.flag.fuxi_EnableInstanceMonitor & fuxi_InstanceMonitorTimeout | Mengaktifkan pemantauan heartbeat untuk penjadwal Fuxi dan menetapkan timeout dalam detik. Gunakan bersamaan. Mencegah sistem menganggap UDF berjalan lama sebagai tidak responsif dan menghentikannya. | — | Aktifkan saat UDF berjalan lama salah dihentikan. Untuk mengubah fuxi_InstanceMonitorTimeout, hubungi dukungan teknis untuk menambahkannya ke daftar putih. |
odps.job.instance.retry.times | Jumlah maksimum retry otomatis untuk satu worker setelah kegagalan sementara seperti kerusakan mesin. Default: 3. Maksimum yang direkomendasikan: 100. | 3 | Tingkatkan untuk job yang gagal karena error infrastruktur sementara. Untuk mengatur di atas default, hubungi dukungan teknis untuk menambahkan parameter ke daftar putih. |
odps.dag2.compound.config | Mengonfigurasi kebijakan reuse worker. Atur ke fuxi.worker.reuse.policy:NO_REUSE untuk menonaktifkan reuse. | — | Nonaktifkan reuse saat UDF memiliki risiko memory leak atau kontaminasi state, sehingga setiap tugas dimulai dalam lingkungan bersih. Hal ini sedikit meningkatkan overhead startup tugas. |
Efisiensi eksekusi dan optimasi
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.sql.executionengine.batch.rowcount | Ukuran batch dalam baris — unit dasar untuk pemrosesan data internal. | 1024 | Turunkan jika satu baris sangat besar dan menyebabkan OOM. Tingkatkan untuk beban kerja komputasi sederhana guna meningkatkan throughput. |
odps.sql.runtime.flag.executionengine_EnableVectorizedExpr | Mengaktifkan mesin eksekusi vektorisasi untuk ekspresi. | — | Aktifkan saat menggunakan rand() atau menjalankan operasi aritmetika intensif. |
odps.optimizer.enable.conditional.mapjoin & odps.optimizer.cbo.rule.filter.black | Digunakan bersamaan untuk menonaktifkan HashJoin. Atur cbo.rule.filter.black ke "hj". | — | Opsi ahli. Jangan dikonfigurasi kecuali Anda benar-benar memahami dampaknya terhadap rencana eksekusi. |
odps.sql.split.cluster.parallel_explore | Membaca informasi CMF secara konkuren selama tahap split tugas. | — | Aktifkan saat tahap split job memakan waktu terlalu lama. |
odps.sql.jobmaster.memory | Ukuran memori dalam MB untuk node Master job. | — | Tingkatkan untuk job shuffle yang melibatkan tabel sangat besar. Misalnya, atur ke 30.000 MB. |
Keamanan UDF dan fungsi
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.sql.udf.timeout & odps.function.timeout | Timeout dalam detik untuk eksekusi satu batch data dalam UDF atau fungsi. Mengatur ke 0 tidak berpengaruh. Rentang: 1–3600 dtk. | 1.800 s | — |
odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize | Panjang maksimum dalam MB untuk log yang dioutput ke stdout oleh pernyataan print Python UDF. Maksimum: 100 MB. | 20 MB | Tingkatkan saat log Python UDF terpotong. Hubungi dukungan teknis untuk menambahkannya ke daftar putih. |
Resource dan lingkungan
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.session.image | Menentukan lingkungan runtime. Nilainya harus berupa nama custom image yang ada di Proyek MaxCompute penyewa saat ini. | — | — |
odps.task.major.version | Mengunci job ke versi utama MaxCompute tertentu untuk stabilitas fitur dan perilaku. | — | Opsi ahli. Jangan dikonfigurasi kecuali Anda memahami dampaknya. |
odps.storage.orc.row.group.stride & odps.storage.meta.file.version | Mengontrol ukuran grup baris file ORC dan versi file metadata CMF, masing-masing. | — | Opsi ahli. Jangan dikonfigurasi kecuali Anda memahami mekanisme dasarnya. |
Flag umum lainnya
| Parameter | Deskripsi | Default | Kapan mengubah |
|---|---|---|---|
odps.sql.allow.fullscan | Mengizinkan pemindaian tabel penuh pada tabel partisi tanpa kondisi filter partisi. | — | Aktifkan dengan hati-hati. Pemindaian penuh pada tabel partisi besar dapat mengakibatkan biaya tinggi dan waktu eksekusi lama. |
odps.sql.cfile2.field.maxsize | Ukuran penyimpanan maksimum dalam byte untuk satu kolom. Default: 8.388.608 (8 MB). Maksimum: 268.435.456 (256 MB). | 8.388.608 (8 MB) | Tingkatkan saat memproses kolom dengan konten sangat besar, seperti teks panjang, HTML, atau data terenkripsi Base64. |
odps.sql.job.max.time.hours | Waktu proses maksimum dalam jam untuk seluruh job SQL. Maksimum: 72 jam. | 24 jam | — |
odps.sql.always.commit.result & odps.sql.runtime.flag.executionengine_EnableWorkerCommit | Digunakan bersamaan untuk mengaktifkan commit parsial. Meskipun job gagal karena beberapa error pemrosesan, data yang berhasil diproses tetap di-commit. | — | Gunakan dalam pipeline ETL di mana keberhasilan parsial dapat diterima. |
Kombinasi tetap penulisan tabel dan CMF
Saat menulis ke tabel partisi dinamis, terapkan kelima flag berikut secara bersamaan. Hal ini memastikan statistik column-store (CMF) dihasilkan dengan cepat dan akurat—yang penting agar job downstream dapat menggunakan odps.sql.split.dop untuk pemisahan data yang tepat.
options.sql.settings = {
"odps.task.merge.enabled": "false",
"odps.sql.reshuffle.dynamicpt": "false",
"odps.sql.enable.dynaparts.stats.collection": "true",
"odps.optimizer.dynamic.partition.is.first.nth.value.split.enable": "false",
"odps.sql.stats.collection.aggressive": "true",
}Opsi MaxFrame
Opsi berikut diatur langsung menggunakan options.<name>.
| Opsi | Deskripsi | Tipe | Default |
|---|---|---|---|
options.session.quota_name | Kuota yang digunakan untuk eksekusi job. | str / None | None |
options.local_timezone | Zona waktu lokal. Mempengaruhi perilaku default fungsi tanggal dan waktu. | str / None | None |
options.session.logview_hours | Periode retensi dalam jam untuk tautan LogView. | int | 24 |
options.sql.enable_mcqa | Menentukan apakah akan mengaktifkan fitur optimasi dan akselerasi kueri cerdas bawaan MaxCompute. | bool | True |
options.sql.generate_comments | Secara otomatis menambahkan komentar ke pernyataan SQL yang dihasilkan untuk pelacakan. | bool | True |
options.sql.auto_use_common_image | Secara otomatis mengonfigurasi gambar publik umum saat sistem mendeteksi bahwa kode menggunakan library dengan dependensi tambahan. | bool | True |
options.session.max_alive_seconds | Masa hidup maksimum untuk sesi. | — | — |
options.session.max_idle_seconds | Waktu idle maksimum untuk sesi. Jika terlampaui, sesi dicabut. Harus kurang dari atau sama dengan max_alive_seconds. | — | — |
options.session.temp_table_lifecycle | Masa hidup default dalam hari untuk tabel temporary yang dibuat oleh MaxFrame. | int | 1 |
options.session.auto_purge_temp_tables | Secara otomatis membersihkan semua tabel temporary yang dibuat dalam sesi saat ini ketika sesi berakhir. | bool | False |
options.function.default_running_options | Konfigurasi resource default untuk fungsi yang didaftarkan dengan dekorator @remote. Kunci: cpu, memory, gpu. | dict | — |
options.dpe.settings = {"substep.public_network_whitelist": ["<ip_or_cidr>"]} | Menambahkan daftar putih akses jaringan publik untuk UDF di mesin DPE. | — | — |
options.dpe.settings = {"substep.internal_network_whitelist": ["<ip_or_cidr>"]} | Menambahkan daftar putih akses jaringan internal untuk UDF di mesin DPE. | — | — |
Penting
Sebelum mengonfigurasi flag tingkat lanjut—terutama yang memerlukan whitelisting atau bergantung pada statistik CMF—hubungi tim dukungan teknis MaxCompute untuk mengonfirmasi prasyarat dan memvalidasi konfigurasi Anda.