Halaman ini diterjemahkan oleh Cloud Translation API.

Fungsi yang ditentukan pengguna di Python
bookmark_border Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Fungsi yang ditentukan pengguna (UDF) Python memungkinkan Anda menerapkan fungsi skalar di Python dan menggunakannya dalam kueri SQL. UDF Python mirip dengan UDF SQL dan JavaScript, tetapi dengan kemampuan tambahan. UDF Python memungkinkan Anda menginstal library pihak ketiga dari Python Package Index (PyPI) dan memungkinkan Anda mengakses layanan eksternal menggunakan koneksi resource Cloud.

UDF Python dibuat dan dijalankan di resource terkelola BigQuery.

Batasan

python-3.11 adalah satu-satunya runtime yang didukung.
Anda tidak dapat membuat UDF Python sementara.
Anda tidak dapat menggunakan UDF Python dengan tampilan terwujud.
Hasil kueri yang memanggil UDF Python tidak di-cache karena nilai yang ditampilkan UDF Python selalu dianggap non-deterministik.
UDF Python tidak sepenuhnya didukung di tampilan INFORMATION_SCHEMA.
Anda tidak dapat membuat atau memperbarui UDF Python menggunakan Routine API.
Kontrol layanan VPC tidak didukung.
Kunci enkripsi yang dikelola pelanggan (CMEK) tidak didukung.
Jenis data berikut tidak didukung: JSON, RANGE, INTERVAL, dan GEOGRAPHY.

Peran IAM yang diperlukan

Peran IAM yang diperlukan didasarkan pada apakah Anda adalah pemilik UDF Python atau pengguna UDF Python. Pemilik UDF Python biasanya membuat atau memperbarui UDF. Pengguna UDF Python memanggil UDF yang dibuat oleh orang lain.

Peran tambahan juga diperlukan jika Anda membuat atau menjalankan UDF Python yang mereferensikan koneksi resource Cloud.

Pemilik UDF

Jika Anda membuat atau memperbarui UDF Python, peran IAM bawaan berikut harus diberikan di resource yang sesuai:

Peran	Izin yang diperlukan	Resource
BigQuery Data Editor (`roles/bigquery.dataEditor`)	`bigquery.routines.create` untuk membuat UDF Python menggunakan pernyataan `CREATE FUNCTION`. `bigquery.routines.update` untuk memperbarui UDF Python menggunakan pernyataan `CREATE FUNCTION`.	Set data tempat UDF Python dibuat atau diperbarui.
BigQuery Job User (`roles/bigquery.jobUser`)	`bigquery.jobs.create` untuk menjalankan tugas kueri pernyataan `CREATE FUNCTION`.	Project tempat Anda menjalankan pernyataan `CREATE FUNCTION`.
BigQuery Connection Admin (`roles/bigquery.connectionAdmin`)	`bigquery.connections.create` hanya diperlukan untuk membuat koneksi resource Cloud baru. `bigquery.connections.delegate` untuk menggunakan koneksi dalam pernyataan `CREATE FUNCTION`.	Koneksi yang Anda berikan akses ke resource eksternal. Koneksi ini hanya diperlukan jika UDF Anda menggunakan klausa `WITH CONNECTION` untuk mengakses layanan eksternal.

Pengguna UDF

Jika Anda memanggil UDF Python, peran IAM bawaan berikut harus diberikan pada resource yang sesuai:

Peran	Izin yang diperlukan	Resource
BigQuery User (`roles/bigquery.user`)	`bigquery.jobs.create` untuk menjalankan tugas kueri yang mereferensikan UDF.	Project tempat Anda menjalankan tugas kueri yang memanggil UDF Python.
BigQuery Data Viewer (`roles/bigquery.dataViewer`)	`bigquery.routines.get` untuk menjalankan UDF yang dibuat oleh orang lain.	Set data tempat UDF Python disimpan.
BigQuery Connection User (`roles/bigquery.connectionUser`)	`bigquery.connections.use` untuk menjalankan UDF Python yang mereferensikan koneksi resource Cloud.	Koneksi resource Cloud yang dirujuk oleh UDF Python. Koneksi ini hanya diperlukan jika UDF Anda mereferensikan koneksi.

Untuk mengetahui informasi selengkapnya tentang peran di BigQuery, lihat Peran IAM yang telah ditetapkan.

Membuat UDF Python persisten

Ikuti aturan berikut saat Anda membuat UDF Python:

Isi UDF Python harus berupa literal string yang diapit tanda kutip yang mewakili kode Python. Untuk mempelajari lebih lanjut literal string yang diapit tanda kutip, lihat Format untuk literal yang diapit tanda kutip.
Isi UDF Python harus menyertakan fungsi Python yang digunakan dalam argumen entry_point dalam daftar opsi UDF Python.
Versi runtime Python harus ditentukan dalam opsi runtime_version. Satu-satunya versi runtime Python yang didukung adalah python-3.11. Untuk daftar lengkap opsi yang tersedia, lihat Daftar opsi fungsi untuk pernyataan CREATE FUNCTION.

Untuk membuat UDF Python persisten, gunakan pernyataan CREATE FUNCTION tanpa kata kunci TEMP atau TEMPORARY. Untuk menghapus UDF Python persisten, gunakan pernyataan DROP FUNCTION.

Saat Anda membuat UDF Python menggunakan pernyataan CREATE FUNCTION, BigQuery akan membuat atau memperbarui image container yang didasarkan pada image dasar. Container dibuat pada image dasar menggunakan kode Anda dan dependensi paket yang ditentukan. Membuat penampung adalah proses yang berjalan lama. Kueri pertama setelah Anda menjalankan pernyataan CREATE FUNCTION mungkin akan otomatis menunggu gambar selesai. Tanpa dependensi eksternal, image penampung biasanya akan dibuat dalam waktu kurang dari satu menit.

Contoh berikut membuat UDF Python persisten bernama multiplyInputs dan memanggil UDF dari dalam pernyataan SELECT:

Buka halaman BigQuery.

Buka BigQuery

Di editor kueri, masukkan pernyataan CREATE FUNCTION berikut:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(runtime_version="python-3.11", entry_point="multiply")
AS r'''

def multiply(x, y):
  return x * y

''';

-- Call the Python UDF.
WITH numbers AS
  (SELECT 1 AS x, 5 as y
  UNION ALL
  SELECT 2 AS x, 10 as y
  UNION ALL
  SELECT 3 as x, 15 as y)
SELECT x, y,
`PROJECT_ID.DATASET_ID`.multiplyInputs(x, y) AS product
FROM numbers;

Ganti PROJECT_ID.DATASET_ID dengan project ID dan ID set data Anda.

Klik Run.

Contoh ini menghasilkan output berikut:

+-----+-----+--------------+
| x   | y   | product      |
+-----+-----+--------------+
| 1   | 5   |  5.0         |
| 2   | 10  | 20.0         |
| 3   | 15  | 45.0         |
+-----+-----+--------------+

Membuat UDF Python yang di-vektorisasi

Anda dapat menerapkan UDF Python untuk memproses batch baris, bukan satu baris, menggunakan vektorisasi. Vektorisasi dapat meningkatkan performa kueri.

Untuk mengontrol perilaku pengelompokan, tentukan jumlah maksimum baris dalam setiap batch menggunakan opsi max_batching_rows di daftar opsi CREATE OR REPLACE FUNCTION. Jika Anda menentukan max_batching_rows, BigQuery akan menentukan jumlah baris dalam batch, hingga batas max_batching_rows. Jika max_batching_rows tidak ditentukan, jumlah baris yang akan di-batch ditentukan secara otomatis.

UDF Python yang di-vektor memiliki satu argumen pandas.DataFrame yang harus dianotasi. Argumen pandas.DataFrame memiliki jumlah kolom yang sama dengan parameter UDF Python yang ditentukan dalam pernyataan CREATE FUNCTION. Nama kolom dalam argumen pandas.DataFrame memiliki nama yang sama dengan parameter UDF.

Fungsi Anda harus menampilkan pandas.Series atau pandas.DataFrame kolom tunggal dengan jumlah baris yang sama dengan input.

Contoh berikut membuat UDF Python yang di-vektorisasi bernama multiplyInputs dengan dua parameter—x dan y:

Buka halaman BigQuery.

Buka BigQuery

Di editor kueri, masukkan pernyataan CREATE FUNCTION berikut:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyVectorized(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(runtime_version="python-3.11", entry_point="vectorized_multiply")
AS r'''
import pandas as pd

def vectorized_multiply(df: pd.DataFrame):
  return df['x'] * df['y']

''';

Ganti PROJECT_ID.DATASET_ID dengan project ID dan ID set data Anda.

Panggilan UDF sama seperti pada contoh sebelumnya.

Klik Run.

Jenis data UDF Python yang didukung

Tabel berikut menentukan pemetaan antara jenis data BigQuery, jenis data Python, dan jenis data Pandas:

Jenis data BigQuery	Jenis data bawaan Python yang digunakan oleh UDF standar	Jenis data Pandas yang digunakan oleh UDF yang di-vektorisasi	Jenis data PyArrow yang digunakan untuk ARRAY dan STRUCT dalam UDF vektor
`BOOL`	`bool`	`BooleanDtype`	`DataType(bool)`
`INT64`	`int`	`Int64Dtype`	`DataType(int64)`
`FLOAT64`	`float`	`FloatDtype`	`DataType(double)`
`STRING`	`str`	`StringDtype`	`DataType(string)`
`BYTES`	`bytes`	`binary[pyarrow]`	`DataType(binary)`
`TIMESTAMP`	Parameter fungsi: `datetime.datetime` (dengan zona waktu UTC ditetapkan) Nilai yang ditampilkan fungsi: `datetime.datetime` (dengan zona waktu yang ditetapkan)	Parameter fungsi: `timestamp[us, tz=UTC][pyarrow]` Nilai yang ditampilkan fungsi: `timestamp[us, tz=*][pyarrow]\(any timezone\)`	`TimestampType(timestamp[us])`, dengan zona waktu
`DATE`	`datetime.date`	`date32[pyarrow]`	`DataType(date32[day])`
`TIME`	`datetime.time`	`time64[pyarrow]`	`Time64Type(time64[us])`
`DATETIME`	`datetime.datetime` (tanpa zona waktu)	`timestamp[us][pyarrow]`	`TimestampType(timestamp[us])`, tanpa zona waktu
`ARRAY`	`list`	`list<...>[pyarrow]`, dengan jenis data elemen adalah `pandas.ArrowDtype`	`ListType`
`STRUCT`	`dict`	`struct<...>[pyarrow]`, dengan jenis data kolom adalah `pandas.ArrowDtype`	`StructType`

Versi runtime yang didukung

UDF Python BigQuery mendukung runtime python-3.11. Versi Python ini menyertakan beberapa paket bawaan tambahan. Untuk library sistem, periksa image dasar runtime.

Versi runtime	Versi Python	Mencakup	Image dasar runtime
python-3.11	Python 3.11	numpy 1.26.3 pyarrow 14.0.2 pandas 2.1.4 python-dateutil 2.8.2	google-22-full/python311

Menggunakan paket pihak ketiga

Anda dapat menggunakan daftar opsi CREATE FUNCTION untuk menggunakan modul selain yang disediakan oleh library standar Python dan paket yang telah diinstal sebelumnya. Anda dapat menginstal paket dari Python Package Index (PyPI), atau Anda dapat mengimpor file Python dari Cloud Storage.

Menginstal paket dari indeks paket Python

Saat menginstal paket, Anda harus memberikan nama paket, dan Anda dapat secara opsional memberikan versi paket menggunakan penentu versi paket Python. Jika paket berada dalam runtime, paket tersebut akan digunakan kecuali jika versi tertentu ditentukan dalam daftar opsi CREATE FUNCTION. Jika versi paket tidak ditentukan, dan paket tidak ada dalam runtime, versi terbaru yang tersedia akan digunakan. Hanya paket dengan format biner roda yang didukung.

Contoh berikut menunjukkan cara membuat UDF Python yang menginstal paket library klien Cloud Translation API menggunakan daftar opsi CREATE OR REPLACE FUNCTION:

Buka halaman BigQuery.

Buka BigQuery

Di editor kueri, masukkan pernyataan CREATE FUNCTION berikut:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.translate(src STRING)
RETURNS STRING LANGUAGE python
OPTIONS (entry_point='do_translate', runtime_version='python-3.11', packages=['google-cloud-translate>=3.11'])
AS r"""
from google.cloud import translate

def do_translate(src):
  # See the example in following section for the detail guide and
  # the implementation
  return 
""";

Ganti PROJECT_ID.DATASET_ID dengan project ID dan ID set data Anda.

Klik Run.

Mengimpor file Python tambahan sebagai library

Anda dapat memperluas UDF Python menggunakan Daftar opsi fungsi dengan mengimpor file Python dari Cloud Storage.

Dalam kode Python UDF, Anda dapat mengimpor file Python dari Cloud Storage sebagai modul menggunakan pernyataan impor, diikuti dengan jalur ke objek Cloud Storage. Misalnya, jika Anda mengimpor gs://BUCKET_NAME/path/to/lib1.py, pernyataan impor Anda akan menjadi import path.to.lib1.

Nama file Python harus berupa ID Python. Setiap nama folder dalam nama objek (setelah /) harus berupa ID Python yang valid. Dalam rentang ASCII (U+0001..U+007F), karakter berikut dapat digunakan dalam ID:

Huruf besar dan kecil A hingga Z.
Garis bawah.
Angka nol hingga sembilan, tetapi angka tidak boleh muncul sebagai karakter pertama dalam ID.

Contoh berikut menunjukkan cara membuat UDF Python yang mengimpor paket library klien lib1.py dari bucket Cloud Storage bernama my_bucket:

Buka halaman BigQuery.

Buka BigQuery

Di editor kueri, masukkan pernyataan CREATE FUNCTION berikut:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.myFunc(a FLOAT64, b STRING)
RETURNS STRING LANGUAGE python
OPTIONS (
entry_point='compute', runtime_version='python-3.11',
library=['gs://my_bucket/path/to/lib1.py'])
AS r"""
import path.to.lib1 as lib1

def compute(a, b):
  # doInterestingStuff is a function defined in
  # gs://my_bucket/path/to/lib1.py
  return lib1.doInterestingStuff(a, b);

""";

Ganti PROJECT_ID.DATASET_ID dengan project ID dan ID set data Anda.

Klik Run.

Memanggil Google Cloud atau layanan online dalam kode Python

UDF Python mengakses layanan Google Cloud atau layanan eksternal menggunakan akun layanan koneksi resource Cloud. Akun layanan koneksi harus diberi izin untuk mengakses layanan. Izin yang diperlukan bervariasi bergantung pada layanan yang diakses dan API yang dipanggil dari kode Python Anda.

Jika Anda membuat UDF Python tanpa menggunakan koneksi resource Cloud, fungsi tersebut akan dijalankan di lingkungan yang memblokir akses jaringan. Jika UDF Anda mengakses layanan online, Anda harus membuat UDF dengan koneksi resource Cloud. Jika tidak, UDF akan diblokir agar tidak dapat mengakses jaringan hingga waktu tunggu koneksi internal tercapai.

Contoh berikut menunjukkan cara mengakses layanan Cloud Translation dari UDF Python. Contoh ini memiliki dua project—project bernama my_query_project tempat Anda membuat UDF dan koneksi resource Cloud, dan project tempat Anda menjalankan Cloud Translation bernama my_translate_project.

Membuat koneksi resource Cloud

Pertama, Anda membuat koneksi resource Cloud di my_query_project. Untuk membuat koneksi resource cloud, ikuti langkah-langkah di halaman Membuat koneksi resource Cloud.

Setelah membuat koneksi, buka, dan di panel Connection info, salin ID akun layanan. Anda memerlukan ID ini saat mengonfigurasi izin untuk koneksi. Saat Anda membuat resource koneksi, BigQuery akan membuat akun layanan sistem unik dan mengaitkannya dengan koneksi.

Memberikan akses ke akun layanan koneksi

Untuk memberikan akses akun layanan koneksi resource Cloud ke project Anda, berikan peran Konsumen penggunaan layanan (roles/serviceusage.serviceUsageConsumer) ke akun layanan di my_query_project dan peran pengguna Cloud Translation API (roles/cloudtranslate.user) di my_translate_project.

Buka halaman IAM.

Buka IAM
Pastikan my_query_project dipilih.
Klik Berikan Akses.
Di kolom New principals, masukkan ID akun layanan koneksi resource Cloud yang Anda salin sebelumnya.
Di kolom Select a role, pilih Service usage, lalu pilih Service usage consumer.
Klik Simpan.
Di pemilih project, pilih my_translate_project.
Buka halaman IAM.

Buka IAM
Klik Berikan Akses.
Di kolom New principals, masukkan ID akun layanan koneksi resource Cloud yang Anda salin sebelumnya.
Di kolom Select a role, pilih Cloud translation, lalu pilih Cloud Translation API user.
Klik Simpan.

Membuat UDF Python yang memanggil layanan Cloud Translation

Di my_query_project, buat UDF Python yang memanggil layanan Cloud Translation menggunakan koneksi resource Cloud Anda.

Buka halaman BigQuery.

Buka BigQuery

Masukkan pernyataan CREATE FUNCTION berikut di editor kueri:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.translate_to_es(x STRING)
RETURNS STRING LANGUAGE python
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (entry_point='do_translate', runtime_version='python-3.11', packages=['google-cloud-translate>=3.11', 'google-api-core'])
AS r"""

from google.api_core.retry import Retry
from google.cloud import translate

project = "my_translate_project"
translate_client = translate.TranslationServiceClient()

def do_translate(x : str) -> str:

    response = translate_client.translate_text(
        request={
            "parent": f"projects/{project}/locations/us-central1",
            "contents": [x],
            "target_language_code": "es",
            "mime_type": "text/plain",
        },
        retry=Retry(),
    )
    return response.translations[0].translated_text

""";

-- Call the UDF.
WITH text_table AS
  (SELECT "Hello" AS text
  UNION ALL
  SELECT "Good morning" AS text
  UNION ALL
  SELECT "Goodbye" AS text)
SELECT text,
`PROJECT_ID.DATASET_ID`.translate_to_es(text) AS translated_text
FROM text_table;

Ganti kode berikut:

PROJECT_ID.DATASET_ID: project ID dan ID set data Anda
REGION.CONNECTION_ID: region koneksi dan ID koneksi Anda

Klik Run.

Outputnya akan terlihat seperti berikut ini:

+--------------------------+-------------------------------+
| text                     | translated_text               |
+--------------------------+-------------------------------+
| Hello                    | Hola                          |
| Good morning             | Buen dia                      |
| Goodbye                  | Adios                         |
+--------------------------+-------------------------------+

Lokasi yang didukung

Selama pratinjau, UDF Python didukung di semua lokasi multi-region dan regional BigQuery, kecuali untuk lokasi berikut:

Meksiko
- Wilayah northamerica-south1 tidak didukung.
Stockholm
- Wilayah europe-north2 tidak didukung.

Harga

UDF Python ditawarkan tanpa biaya tambahan.

Jika penagihan diaktifkan, hal berikut akan berlaku:

Biaya UDF Python ditagih menggunakan SKU Layanan BigQuery.
Biaya sebanding dengan jumlah komputasi dan memori yang digunakan saat UDF Python dipanggil.
Pelanggan UDF Python juga dikenai biaya pembuatan atau pembuatan ulang image container UDF. Biaya ini sebanding dengan resource yang digunakan untuk mem-build image dengan kode dan dependensi pelanggan.
Jika UDF Python menghasilkan traffic keluar jaringan eksternal atau internet, Anda juga akan melihat tagihan traffic keluar internet Tingkat Premium dari Cloud Networking.

Fungsi yang ditentukan pengguna di Python bookmark_borderbookmark Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Batasan

Peran IAM yang diperlukan

Pemilik UDF

Pengguna UDF

Membuat UDF Python persisten

Membuat UDF Python yang di-vektorisasi

Jenis data UDF Python yang didukung

Versi runtime yang didukung

Menggunakan paket pihak ketiga

Menginstal paket dari indeks paket Python

Mengimpor file Python tambahan sebagai library

Memanggil Google Cloud atau layanan online dalam kode Python

Membuat koneksi resource Cloud

Memberikan akses ke akun layanan koneksi

Membuat UDF Python yang memanggil layanan Cloud Translation

Lokasi yang didukung

Harga

Fungsi yang ditentukan pengguna di Python
bookmark_border Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.