Menyesuaikan fungsi Python untuk BigQuery DataFrames

BigQuery DataFrames memungkinkan Anda mengubah fungsi Python kustom menjadi artefak BigQuery yang dapat Anda jalankan pada objek BigQuery DataFrames dalam skala besar. Dukungan ekstensi ini memungkinkan Anda melakukan operasi di luar kemampuan BigQuery DataFrames dan SQL API, sehingga Anda berpotensi memanfaatkan library open source.

Ada dua varian mekanisme ekstensi ini: fungsi yang ditentukan pengguna dan fungsi jarak jauh.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tugas dalam dokumen ini, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

• BigQuery Data Editor (roles/bigquery.dataEditor)
• BigQuery Connection Admin (roles/bigquery.connectionAdmin)
• Cloud Functions Developer (roles/cloudfunctions.developer)
• Service Account User (roles/iam.serviceAccountUser)
• Storage Object Viewer (roles/storage.objectViewer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Fungsi yang ditentukan pengguna (UDF)

Dengan UDF (Pratinjau), Anda dapat mengubah fungsi Python kustom menjadi UDF Python. Untuk contoh penggunaan, lihat Membuat UDF Python persisten.

Membuat UDF di BigQuery DataFrames akan membuat rutinitas BigQuery sebagai UDF Python di set data yang ditentukan. Untuk mengetahui kumpulan lengkap parameter yang didukung, lihat bigframes.pandas.udf.

Persyaratan

Untuk menggunakan UDF BigQuery DataFrames, aktifkan BigQuery API di project Anda. Jika Anda memberikan parameter bigquery_connection di project Anda, Anda juga harus mengaktifkan BigQuery Connection API.

Pembersihan

Selain membersihkan artefak cloud langsung di Google Cloud konsol atau dengan alat lainnya, Anda dapat membersihkan UDF BigQuery DataFrames yang dibuat dengan argumen nama eksplisit menggunakan bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) perintah.

Batasan

• Kode dalam UDF harus mandiri, artinya, kode tersebut tidak boleh berisi referensi ke impor atau variabel yang ditentukan di luar isi fungsi.
• Kode dalam UDF harus kompatibel dengan Python 3.11, karena kode tersebut adalah lingkungan tempat kode dijalankan di cloud.
• Menjalankan ulang kode definisi UDF setelah perubahan kecil dalam kode fungsi—misalnya, mengganti nama variabel atau menyisipkan baris baru—akan menyebabkan UDF dibuat ulang, meskipun perubahan ini tidak berpengaruh pada perilaku fungsi.
• Kode pengguna terlihat oleh pengguna dengan akses baca pada rutinitas BigQuery, jadi Anda harus menyertakan konten sensitif dengan hati-hati.
• Project dapat memiliki hingga 1.000 Cloud Run Functions sekaligus di lokasi BigQuery.

UDF BigQuery DataFrames men-deploy fungsi Python BigQuery yang ditentukan pengguna, dan batasan terkait berlaku.

Fungsi jarak jauh

BigQuery DataFrames memungkinkan Anda mengubah fungsi skalar kustom menjadi fungsi jarak jauh BigQuery. Untuk contoh penggunaan, lihat Membuat fungsi jarak jauh. Untuk mengetahui kumpulan lengkap parameter yang didukung, lihat remote_function.

Membuat fungsi jarak jauh di BigQuery DataFrames akan membuat hal berikut:

• A Cloud Run Function.

• Koneksi BigQuery.

  Secara default, koneksi bernama bigframes-default-connection akan digunakan. Anda dapat menggunakan koneksi BigQuery yang telah dikonfigurasi sebelumnya jika mau, sehingga pembuatan koneksi akan dilewati. Akun layanan untuk koneksi default diberi peran Cloud Run (roles/run.invoker).

• Fungsi jarak jauh BigQuery yang menggunakan Cloud Run Function yang telah dibuat dengan koneksi BigQuery.

Persyaratan

Untuk menggunakan fungsi jarak jauh BigQuery DataFrames, Anda harus mengaktifkan API berikut:

• BigQuery API (bigquery.googleapis.com)
• BigQuery Connection API (bigqueryconnection.googleapis.com)
• Cloud Functions API (cloudfunctions.googleapis.com)
• Cloud Run Admin API (run.googleapis.com)
• Artifact Registry API (artifactregistry.googleapis.com)
• Cloud Build API (cloudbuild.googleapis.com)
• Compute Engine API (compute.googleapis.com)
• Cloud Resource Manager API (cloudresourcemanager.googleapis.com)

Saat menggunakan fungsi jarak jauh BigQuery DataFrames, Anda memerlukan peran Project IAM Admin (roles/resourcemanager.projectIamAdmin) jika menggunakan koneksi BigQuery default, atau peran Browser (roles/browser) jika menggunakan koneksi yang telah dikonfigurasi sebelumnya. Anda dapat menghindari persyaratan ini dengan menetapkan opsi bigframes.pandas.options.bigquery.skip_bq_connection_check ke True. Dalam hal ini, koneksi (default atau yang telah dikonfigurasi sebelumnya) akan digunakan apa adanya tanpa pemeriksaan izin atau keberadaan. Jika Anda menggunakan koneksi yang telah dikonfigurasi sebelumnya dan melewati pemeriksaan koneksi, verifikasi hal berikut:

• Koneksi dibuat di lokasi yang tepat.
• Jika Anda menggunakan fungsi jarak jauh BigQuery DataFrames, akun layanan memiliki peran Cloud Run Invoker (roles/run.invoker) di project.

Melihat dan mengelola koneksi

Koneksi BigQuery dibuat di lokasi yang sama dengan sesi BigQuery DataFrames, menggunakan nama yang Anda berikan dalam definisi fungsi kustom. Untuk melihat dan mengelola koneksi, lakukan hal berikut:

1. Di Google Cloud konsol, buka halaman BigQuery.

   Buka BigQuery

2. Pilih project tempat Anda membuat fungsi jarak jauh.

3. Di panel kiri, klik Explorer:

   

4. Di panel Explorer, luaskan project, lalu klik Connections.

Fungsi jarak jauh BigQuery dibuat di set data yang Anda tentukan, atau dibuat di set data anonim, yang merupakan jenis set data tersembunyi. Jika Anda tidak menetapkan nama untuk fungsi jarak jauh selama pembuatannya, BigQuery DataFrames akan menerapkan nama default yang dimulai dengan awalan bigframes. Untuk melihat dan mengelola fungsi jarak jauh yang dibuat di set data yang ditentukan pengguna, lakukan hal berikut:

1. Di Google Cloud konsol, buka halaman BigQuery.

   Buka BigQuery

2. Pilih project tempat Anda membuat fungsi jarak jauh.

3. Di panel kiri, klik Explorer:

   

4. Di panel Explorer, luaskan project, lalu klik Datasets.

5. Klik set data tempat Anda membuat fungsi jarak jauh.

6. Klik tab Routines.

Untuk melihat dan mengelola Cloud Run Functions, lakukan hal berikut:

1. Buka halaman Cloud Run.

   Buka Cloud Run

2. Pilih project tempat Anda membuat fungsi.

3. Dalam daftar layanan yang tersedia, filter berdasarkan Function Deployment type.

4. Untuk mengidentifikasi fungsi yang dibuat oleh BigQuery DataFrames, cari nama fungsi dengan awalan bigframes.

Pembersihan

Selain membersihkan artefak cloud langsung di Google Cloud konsol atau dengan alat lainnya, Anda dapat membersihkan fungsi jarak jauh BigQuery yang dibuat tanpa argumen nama eksplisit dan Cloud Run Functions terkait dengan cara berikut:

• Untuk sesi BigQuery DataFrames, gunakan perintah session.close().
• Untuk sesi BigQuery DataFrames default, gunakan perintah bigframes.pandas.close_session().
• Untuk sesi sebelumnya dengan session_id, gunakan perintah bigframes.pandas.clean_up_by_session_id(session_id).

Anda juga dapat membersihkan fungsi jarak jauh BigQuery yang dibuat dengan argumen nama eksplisit dan Cloud Run Functions terkait menggunakan perintah bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Batasan

• Fungsi jarak jauh memerlukan waktu sekitar 90 detik agar dapat digunakan saat pertama kali Anda membuatnya. Dependensi paket tambahan dapat menambah latensi.
• Menjalankan ulang kode definisi fungsi jarak jauh setelah perubahan kecil dalam dan di sekitar kode fungsi—misalnya, mengganti nama variabel, menyisipkan baris baru, atau menyisipkan sel baru di notebook—dapat menyebabkan fungsi jarak jauh dibuat ulang, meskipun perubahan ini tidak berpengaruh pada perilaku fungsi.
• Kode pengguna terlihat oleh pengguna dengan akses baca pada Cloud Run Functions, jadi Anda harus menyertakan konten sensitif dengan hati-hati.
• Project dapat memiliki hingga 1.000 Cloud Run Functions sekaligus di region. Untuk mengetahui informasi selengkapnya, lihat Kuota.

Langkah berikutnya

• Pelajari tentang kemampuan ML dan AI dengan BigQuery DataFrames.
• Pelajari cara membuat kode BigQuery DataFrames dengan Gemini.
• Pelajari cara menganalisis download paket dari PyPI dengan BigQuery DataFrames.
• Lihat kode sumber BigQuery DataFrames , notebook contoh, dan contoh di GitHub.
• Pelajari referensi BigQuery DataFrames API.