Menyesuaikan fungsi Python untuk BigQuery DataFrames

Dengan menyesuaikan fungsi Python untuk BigQuery DataFrames, Anda dapat mengubah kode menjadi artefak BigQuery yang skalabel, seperti fungsi yang ditentukan pengguna (UDF) atau fungsi jarak jauh. Anda dapat men-deploy fungsi kustom ini untuk memanfaatkan library open source dan melakukan operasi di luar kemampuan API SQL standar.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tugas dalam dokumen ini, minta administrator 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 dalam 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 dalam project, Anda juga harus mengaktifkan BigQuery Connection API.

Pembersihan

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

Batasan

• Kode dalam UDF harus mandiri, artinya, kode tersebut tidak boleh berisi referensi apa pun ke impor atau variabel yang ditentukan di luar isi fungsi.
• Kode dalam UDF harus kompatibel dengan Python 3.11, karena itulah lingkungan tempat kode dieksekusi di cloud.
• Menjalankan ulang kode definisi UDF setelah perubahan kecil pada kode fungsi—misalnya, mengganti nama variabel atau menyisipkan baris baru—akan menyebabkan UDF dibuat ulang, meskipun perubahan ini tidak memengaruhi perilaku fungsi.
• Kode pengguna dapat dilihat oleh pengguna yang memiliki akses baca pada rutinitas BigQuery, jadi Anda harus menyertakan konten sensitif hanya dengan hati-hati.
• Sebuah project dapat memiliki hingga 1.000 fungsi Cloud Run 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:

• Fungsi Cloud Run.

• Koneksi BigQuery.

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

• Fungsi jarak jauh BigQuery yang menggunakan fungsi Cloud Run 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, sehingga koneksi (default atau yang telah dikonfigurasi sebelumnya) digunakan apa adanya tanpa pemeriksaan keberadaan atau izin. 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 konsol Google Cloud , 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 dalam set data yang Anda tentukan, atau dibuat dalam 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 diawali dengan awalan bigframes. Untuk melihat dan mengelola fungsi jarak jauh yang dibuat dalam set data yang ditentukan pengguna, lakukan hal berikut:

1. Di konsol Google Cloud , 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 Rutinitas.

Untuk melihat dan mengelola fungsi Cloud Run, 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 DataFrame, cari nama fungsi dengan awalan bigframes.

Pembersihan

Selain membersihkan artefak cloud langsung di konsol Google Cloud atau dengan alat lain, Anda dapat membersihkan fungsi jarak jauh BigQuery yang dibuat tanpa argumen nama eksplisit dan fungsi Cloud Run 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 fungsi Cloud Run terkait menggunakan perintah bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Batasan

• Fungsi jarak jauh memerlukan waktu sekitar 90 detik untuk dapat digunakan saat Anda pertama kali membuatnya. Dependensi paket tambahan mungkin 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 dapat dilihat oleh pengguna yang memiliki akses baca di Cloud Run Functions, jadi Anda harus menyertakan konten sensitif hanya dengan hati-hati.
• Sebuah project dapat memiliki hingga 1.000 fungsi Cloud Run sekaligus di satu region. Untuk mengetahui informasi selengkapnya, lihat Kuota.

Langkah berikutnya

• Pelajari 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, notebook contoh, dan contoh BigQuery DataFrame di GitHub.
• Pelajari referensi BigQuery DataFrames API.