MaxCompute:FAQ PyODPS

"Warning: XXX not installed"

Instal komponen yang hilang menggunakan pip. Pesan error tersebut menunjukkan nama komponen pada bagian XXX.

"Project Not Found"

Periksa dua hal berikut:

• Endpoint: Endpoint harus mengarah ke proyek target Anda. Lihat Endpoint.

• Parameter objek entri: Pastikan parameter objek entri MaxCompute berada pada posisi yang benar. Lihat Migrasi node PyODPS dari DataWorks ke lingkungan on-premises.

"Syntax Error"

PyODPS tidak mendukung Python 2.5 atau versi sebelumnya. Gunakan Python 2.6, Python 2.7.6 atau versi lebih baru, atau Python 3.3 atau versi lebih baru.

"Permission Denied" pada macOS

Jalankan instalasi dengan sudo:

sudo pip install pyodps

"Operation Not Permitted" pada macOS

Ini disebabkan oleh System Integrity Protection (SIP). Untuk menonaktifkannya:

1. Mulai ulang Mac Anda dan tahan Command (⌘) + R selama startup untuk masuk ke Recovery Mode.

2. Buka Terminal dan jalankan:

   csrutil disable
   reboot

Untuk detail lebih lanjut, lihat Operation Not Permitted when on root - El Capitan (rootless disabled).

"No Module Named ODPS"

Hal ini paling sering terjadi karena konflik penamaan di direktori kerja Anda. Periksa apakah direktori saat ini berisi file bernama odps.py atau init.py, atau folder bernama odps — jika iya, ganti namanya.

Penyebab lain:

• Paket yang bertabrakan: Jika sebelumnya Anda menginstal paket bernama odps, hapus dengan sudo pip uninstall odps.

• Versi Python ganda: Lebih dari satu versi Python terinstal. Pastikan hanya satu versi yang aktif.

• PyODPS belum diinstal: Instal di bawah versi Python saat ini. Lihat Instal PyODPS.

"Cannot Import Name ODPS"

File bernama odps.py ada di direktori kerja Anda dan mengaburkan paket tersebut. Ganti nama atau pindahkan file tersebut, lalu coba lagi impor.

"Cannot Import Module odps"

Ini biasanya merupakan masalah dependensi. Bergabunglah dengan grup dukungan teknis PyODPS di DingTalk dan hubungi administrator grup untuk bantuan.

"ImportError" di IPython atau Jupyter Notebook

Tambahkan from odps import errors di bagian atas kode Anda. Jika error tetap muncul, dependensi IPython mungkin belum terinstal — instal ulang Jupyter:

sudo pip install -U jupyter

Apa yang dikembalikan oleh o.get_table('table_name').size?

Bidang size mengembalikan ukuran penyimpanan fisik tabel, bukan jumlah baris.

Bagaimana cara mengonfigurasi endpoint Tunnel?

Atur options.tunnel.endpoint ke URL endpoint Anda. Untuk semua opsi yang tersedia, lihat referensi opsi aliyun-odps-python-sdk.

Bagaimana cara menggunakan paket pihak ketiga yang berisi CPython?

Buat paket wheel yang menyertakan CPython. Untuk contoh, lihat Buat crcmod yang dapat digunakan di MaxCompute.

Apakah ada batas ukuran untuk DataFrame PyODPS?

PyODPS sendiri tidak memiliki batas ukuran tabel. Untuk DataFrame yang dibuat dari Pandas lokal, batasnya adalah memori lokal yang tersedia.

Bagaimana cara menggunakan max_pt dalam DataFrame?

Gunakan modul odps.df.func untuk memanggil fungsi bawaan MaxCompute:

from odps.df import func
df = o.get_table('your_table').to_df()
df[df.ds == func.max_pt('your_project.your_table')]  # ds adalah kolom partisi.

Apa perbedaan antara open_writer() dan write_table()?

Setiap pemanggilan write_table() membuat file baru di server. Memanggilnya berulang kali dengan dataset kecil akan menghasilkan banyak file, yang mengurangi performa kueri dan dapat menyebabkan masalah memori.

Disarankan: Kirim semua catatan dalam satu pemanggilan atau gunakan objek Generator untuk meminimalkan jumlah file yang dibuat:

# Kurang efisien: satu file dibuat per pemanggilan
write_table(records_batch_1)
write_table(records_batch_2)

# Lebih efisien: semua catatan dalam satu pemanggilan
write_table(all_records)

open_writer() menulis langsung ke Block dan lebih cocok untuk penulisan streaming.

Untuk detail penggunaan, lihat Tulis data ke tabel.

Mengapa node PyODPS DataWorks mengembalikan lebih sedikit baris dibanding eksekusi lokal?

DataWorks tidak mengaktifkan Instance Tunnel secara default. Tanpa itu, instance.open_reader menggunakan antarmuka Result, yang dibatasi hingga 10.000 catatan.

Untuk mengambil semua catatan, aktifkan Instance Tunnel dan hapus batasannya:

options.tunnel.use_instance_tunnel = True
options.tunnel.limit_instance_tunnel = False  # Hapus batas 10.000 catatan.

with instance.open_reader() as reader:
    for record in reader:
        ...

Setelah mengaktifkan Instance Tunnel, gunakan reader.count untuk mendapatkan jumlah total catatan.

Bagaimana cara mendapatkan jumlah baris DataFrame?

DataFrame menggunakan eksekusi lazy — operasi tidak dijalankan hingga Anda secara eksplisit memicunya. Untuk mendapatkan jumlah segera:

iris = DataFrame(o.get_table('pyodps_iris'))
iris.count().execute()

Memanggil count() tanpa execute() mengembalikan ekspresi lazy, bukan angka. Untuk informasi lebih lanjut tentang eksekusi lazy, lihat Eksekusi dan Agregasi.

"sourceIP is not in the white list"

Proyek MaxCompute telah mengaktifkan perlindungan daftar putih IP. Hubungi pemilik proyek untuk menambahkan alamat IP Anda ke daftar putih. Lihat Kelola daftar putih alamat IP.

options.sql.settings tidak berlaku

Nama parameter berbeda antara client dan PyODPS. Client menggunakan odps.stage.mapper.split.size, tetapi PyODPS menggunakan odps.sql.mapper.split.size. Ini bukan parameter yang sama.

Gunakan nama parameter yang benar di PyODPS:

from odps import options
options.sql.settings = {'odps.stage.mapper.split.size': 32}

"IndexError: list index out of range" saat memanggil head()

DataFrame tidak memiliki baris, atau indeks yang diminta melebihi jumlah baris yang tersedia. Periksa apakah DataFrame kosong sebelum memanggil head().

"ODPSError: ODPS entrance should be provided" saat mengunggah DataFrame Pandas

PyODPS tidak dapat menemukan objek entri MaxCompute global. Perbaiki ini dengan salah satu pendekatan berikut:

• Gunakan perintah ajaib %enter (mekanisme Room) untuk mengatur entri global secara otomatis.

• Panggil to_global() pada objek entri MaxCompute Anda.

• Kirimkan objek entri secara eksplisit: DataFrame(pd_df).persist('your_table', odps=odps).

"lifecycle is not specified in mandatory mode"

Proyek mewajibkan nilai lifecycle untuk setiap tabel. Atur sebelum menulis:

from odps import options
options.lifecycle = 7  # Jumlah hari. Harus berupa bilangan bulat.

"Perhaps the datastream from server is crushed"

Ini menunjukkan adanya data rusak. Periksa apakah jumlah kolom dalam data Anda sesuai dengan skema tabel target.

"Project is protected"

Kebijakan keamanan proyek membatasi pembacaan data langsung.

• Untuk mengakses semua data: Minta pemilik proyek menambahkan aturan pengecualian, atau ekspor data ke proyek yang tidak dilindungi menggunakan DataWorks atau tool penyembunyian lainnya.

• Untuk pratinjau data: Gunakan o.execute_sql('select * from <table_name>').open_reader() atau o.get_table('<table_name>').to_df().

"ConnectionError: timed out try catch exception"

Timeout koneksi default adalah 5 detik. Hal ini paling sering menyebabkan kegagalan intermiten ketika jaringan atau server memiliki latensi tinggi. Tingkatkan timeout di bagian atas skrip Anda:

from odps import options
options.connect_timeout = 30

Jika error terjadi pada mesin tertentu, pembatasan jaringan sandbox mungkin memblokir akses. Gunakan kelompok sumber daya khusus untuk menjalankan tugas-tugas tersebut.

"NameError: name 'get_task_cost' is not defined"

Nama fungsi get_sql_task_cost tidak valid. Gunakan execute_sql_cost sebagai gantinya.

Karakter Tionghoa muncul sebagai string terenkripsi dalam log

Ini hanya memengaruhi Python 2. Gunakan operator format % saat mencetak string yang berisi karakter Tionghoa:

print("我叫 %s" % ('abc'))

Bidang DATETIME dikembalikan sebagai STRING saat menggunakan open_reader

Saat options.tunnel.use_instance_tunnel = False, PyODPS memanggil antarmuka Result lawas, yang mengembalikan data dalam format CSV — sehingga nilai DATETIME dikembalikan sebagai string.

Aktifkan Instance Tunnel untuk mendapatkan data dengan tipe yang benar:

options.tunnel.use_instance_tunnel = True

Bagaimana cara menggunakan fitur bahasa Python dalam DataFrame PyODPS?

DataFrame PyODPS kompatibel dengan fungsi standar Python dan alur kendali.

Definisikan dan gunakan kembali fungsi:

def euclidean_distance(from_x, from_y, to_x, to_y):
    return ((from_x - to_x) ** 2 + (from_y - to_y) ** 2).sqrt()

def manhattan_distance(from_x, from_y, to_x, to_y):
    return (from_x - to_x).abs() + (from_y - to_y).abs()

# Terapkan ke DataFrame
euclidean_distance(df.from_x, df.from_y, df.to_x, df.to_y).rename('distance')

Gunakan loop dan `reduce` untuk menggabungkan tabel:

Alih-alih menulis 30 pernyataan SQL UNION ALL, gunakan reduce milik Python:

table_names = ['table1', ..., 'tableN']
dfs = [o.get_table(tn).to_df() for tn in table_names]
result = reduce(lambda x, y: x.union(y), dfs)

Bagaimana cara melakukan debug PyODPS secara lokal menggunakan backend Pandas?

Gunakan flag DEBUG untuk beralih antara eksekusi Pandas lokal dan eksekusi MaxCompute tanpa mengubah kode lainnya:

df = o.get_table('movielens_ratings').to_df()
DEBUG = True
if DEBUG:
    df = df[:100].to_pandas(wrap=True)

# Semua kode berikutnya tidak berubah — dijalankan secara lokal saat DEBUG=True.

Atur DEBUG = False untuk menjalankan pekerjaan penuh di MaxCompute. Untuk pengalaman debugging lokal yang lebih kaya, gunakan MaxCompute Studio.

Loop bersarang berjalan lambat

Penyebab paling umum adalah menempatkan df = XXX di dalam loop luar. Ini membuat objek DataFrame baru pada setiap iterasi, yang mahal. Sebagai gantinya, kumpulkan hasil dalam dict di dalam loop, lalu buat DataFrame sekali setelah loop selesai.

Bagaimana cara menghindari mengunduh data secara lokal?

Lihat Gunakan node PyODPS untuk mengunduh data ke direktori lokal untuk diproses atau memproses data secara online.

Kapan tepatnya mengunduh data secara lokal?

Unduh data untuk pemrosesan lokal ketika volumenya kecil.

Untuk operasi skala besar — terutama memperluas satu baris menjadi beberapa baris atau menerapkan fungsi Python per baris — pertahankan komputasi di MaxCompute menggunakan DataFrame PyODPS. Misalnya, untuk memperluas string JSON menjadi baris pasangan kunci-nilai:

from odps.df import output

@output(['k', 'v'], ['string', 'int'])
def h(row):
    import json
    for k, v in json.loads(row.json).items():
        yield k, v

df.apply(h, axis=1)

open_reader hanya mengembalikan 10.000 catatan — bagaimana cara mendapatkan lebih banyak?

Simpan hasil SQL sebagai tabel, lalu baca dari tabel tersebut:

o.execute_sql('create table result_table as select * from your_table')
o.get_table('result_table').open_reader()

Mengapa menggunakan operator bawaan daripada UDF?

Operator bawaan berjalan jauh lebih cepat daripada fungsi yang ditentukan pengguna (UDF). Untuk pekerjaan yang memproses jutaan baris, UDF dapat meningkatkan waktu eksekusi dari 7 detik menjadi 27 detik. Untuk dataset yang lebih besar, selisihnya semakin besar.

Mengapa DataFrame().schema.partitions kosong untuk tabel partisi?

DataFrame memperlakukan kolom partisi sama seperti kolom biasa — tidak membedakannya. Untuk memfilter berdasarkan kolom partisi, kueri langsung:

df = o.get_table('your_table').to_df()
print(df[df.ds == ''].execute())

Untuk informasi lebih lanjut tentang partisi dan pembacaan berbasis partisi, lihat Tabel.

Bagaimana cara melakukan Produk Kartesius dalam DataFrame PyODPS?

Lihat Penanganan Produk Kartesius DataFrame PyODPS.

Bagaimana cara melakukan segmentasi teks Tionghoa menggunakan Jieba di node PyODPS?

Lihat Gunakan node PyODPS untuk melakukan segmentasi teks Tionghoa berdasarkan Jieba.

Bagaimana cara mengunduh semua data dari tabel?

Secara default, PyODPS tidak membatasi jumlah data yang dapat dibaca dari instans. Namun, jika Anda tidak menentukan options.tunnel.limit_instance_tunnel, batas tersebut diaktifkan secara otomatis, dan jumlah catatan yang dapat diunduh dibatasi berdasarkan konfigurasi proyek — dalam kebanyakan kasus, maksimal 10.000 catatan sekaligus. Untuk mengunduh semua data, aktifkan Instance Tunnel dan nonaktifkan batasannya:

options.tunnel.use_instance_tunnel = True
options.tunnel.limit_instance_tunnel = False  # Hapus batas catatan.

with instance.open_reader() as reader:
    for record in reader:
        ...

Dapatkah saya menghitung persentase nilai null menggunakan execute_sql atau DataFrame?

Keduanya berfungsi, tetapi operasi agregasi DataFrame umumnya lebih cepat untuk perhitungan jenis ini.

Bagaimana cara mengaktifkan tipe data baru di PyODPS?

Untuk satu kueri, kirimkan pengaturan sebagai petunjuk dengan execute_sql:

o.execute_sql(
    'set odps.sql.type.system.odps2=true; select * from your_table',
    hints={"odps.sql.submit.mode": "script"}
)

Untuk satu pekerjaan DataFrame (persist, execute, atau to_pandas), kirimkan petunjuk tersebut ke pemanggilan tersebut:

from odps.df import DataFrame
users = DataFrame(o.get_table('odps2_test'))
users.persist('copy_test', hints={'odps.sql.type.system.odps2': 'true'})

Untuk semua pekerjaan DataFrame dalam sesi, atur opsi global:

options.sql.use_odps2_extension = True

"ValueError" saat menggunakan PyODPS

Upgrade SDK ke V0.8.4 atau versi lebih baru. Jika Anda tidak dapat melakukan upgrade, tambahkan berikut ini ke skrip Anda:

from odps.types import Decimal
Decimal._max_precision = 38

Kueri SQL melalui PyODPS berjalan lambat

Eksekusi SQL yang lambat biasanya bukan disebabkan oleh PyODPS itu sendiri. Ikuti langkah-langkah berikut:

1. Periksa latensi jaringan dan server

Verifikasi apakah server proxy atau tautan jaringan Anda menambahkan penundaan, dan periksa apakah antrian tugas di sisi server sedang penuh.

2. Pisahkan pengiriman tugas dari pembacaan data

Menggabungkan pengiriman dan pembacaan dalam satu pemanggilan menyulitkan untuk mengetahui di mana penundaan terjadi. Pisahkan keduanya untuk mengukur setiap fase secara independen:

# Sebelum: pengiriman dan pembacaan digabung
with o.execute_sql('select * from your_table').open_reader() as reader:
    for row in reader:
        print(row)

# Setelah: dipisah menjadi langkah terpisah
inst = o.run_sql('select * from your_table')
inst.wait_for_success()
with inst.open_reader() as reader:
    for row in reader:
        print(row)

3. Periksa Logview yang hilang (hanya DataWorks)

Untuk pekerjaan yang dikirim melalui DataWorks, pastikan tugas SQL Anda menghasilkan tautan Logview. Tugas yang dikirim dengan execute_sql atau run_sql pada versi PyODPS di bawah 0.11.6 mungkin gagal menghasilkan Logview.

4. Aktifkan logging debug

PyODPS mencatat semua permintaan dan tanggapan saat logging debug diaktifkan. Ini menunjukkan cap waktu pasti untuk setiap tahap permintaan:

import datetime
import logging
from odps import ODPS

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
o = ODPS(...)  # Isi kredensial akun Anda.
print("Check time:", datetime.datetime.now())
inst = o.run_sql("select * from your_table")

Output log menunjukkan kapan setiap fase dimulai dan berapa lama waktu yang dibutuhkan, membantu Anda mengidentifikasi di mana penundaan terjadi.