Menggunakan BigQuery DataFrames

BigQuery DataFrames menyediakan DataFrame Pythonic dan API machine learning (ML) yang didukung oleh mesin BigQuery. BigQuery DataFrames adalah paket open source. Anda dapat menjalankan pip install --upgrade bigframes untuk menginstal versi terbaru.

BigQuery DataFrames menyediakan tiga library:

  • bigframes.pandas menyediakan pandas API yang dapat Anda gunakan untuk menganalisis dan memanipulasi data di BigQuery. Banyak beban kerja yang dapat dimigrasikan dari pandas ke bigframe hanya dengan mengubah beberapa impor. bigframes.pandas API dapat diskalakan untuk mendukung pemrosesan terabyte data BigQuery, dan API ini menggunakan mesin kueri BigQuery untuk melakukan penghitungan.
  • bigframes.bigquery menyediakan banyak fungsi SQL BigQuery yang mungkin tidak memiliki fungsi yang setara di pandas.
  • bigframes.ml menyediakan API yang mirip dengan scikit-learn API untuk ML. Kemampuan ML di BigQuery DataFrames memungkinkan Anda memproses data terlebih dahulu, lalu melatih model pada data tersebut. Anda juga dapat merangkai tindakan ini untuk membuat pipeline data.

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:

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

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

Selain itu, saat menggunakan fungsi jarak jauh BigQuery DataFrames atau model jarak jauh BigQuery DataFrames ML, 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. Persyaratan ini dapat dihindari dengan menetapkan opsi bigframes.pandas.options.bigquery.skip_bq_connection_check ke True. Dalam hal ini, koneksi (default atau yang telah dikonfigurasi sebelumnya) digunakan seperti 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.
  • Jika Anda menggunakan model jarak jauh BigQuery DataFrames ML, akun layanan memiliki peran Pengguna Vertex AI (roles/aiplatform.user) di project.

Saat Anda melakukan autentikasi pengguna akhir di lingkungan interaktif seperti notebook, REPL Python, atau command line, BigQuery DataFrames akan meminta autentikasi, jika diperlukan. Jika tidak, lihat cara menyiapkan kredensial default aplikasi untuk berbagai lingkungan.

Mengonfigurasi opsi penginstalan

Setelah menginstal BigQuery DataFrames, Anda dapat menentukan opsi berikut.

Lokasi dan project

Anda harus menentukan lokasi dan project tempat Anda ingin menggunakan BigQuery DataFrames.

Anda dapat menentukan lokasi dan project di notebook dengan cara berikut:

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dev"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

Lokasi pemrosesan data

BigQuery DataFrames dirancang untuk skala, yang dicapai dengan menyimpan data dan pemrosesan di layanan BigQuery. Namun, Anda dapat memasukkan data ke dalam memori mesin klien dengan memanggil .to_pandas() pada objek DataFrame atau Series. Jika Anda memilih untuk melakukannya, batasan memori mesin klien akan berlaku.

Lokasi sesi

BigQuery DataFrames menggunakan objek sesi lokal secara internal untuk mengelola metadata. Sesi ini terikat dengan lokasi. DataFrame BigQuery menggunakan multi-region US sebagai lokasi default, tetapi Anda dapat menggunakan session_options.location untuk menetapkan lokasi yang berbeda. Setiap kueri dalam sesi dijalankan di lokasi tempat sesi dibuat. BigQuery DataFrames otomatis mengisi bf.options.bigquery.location dengan lokasi tabel jika pengguna memulai dengan read_gbq/read_gbq_table/read_gbq_query() dan menentukan tabel, baik secara langsung maupun dalam pernyataan SQL.

Jika ingin mereset lokasi objek DataFrame atau Series yang dibuat, Anda dapat menutup sesi dengan menjalankan bigframes.pandas.close_session(). Setelah itu, Anda dapat menggunakan kembali bigframes.pandas.options.bigquery.location untuk menentukan lokasi lain.

read_gbq() mengharuskan Anda menentukan lokasi jika set data yang Anda kirimkan kueri tidak berada di multi-region US. Jika mencoba membaca tabel dari lokasi lain, Anda akan mendapatkan pengecualian NotFound.

Bermigrasi ke BigQuery DataFrames versi 2.0

BigQuery DataFrames versi 2.0 meningkatkan keamanan dan performa BigQuery DataFrames API, menambahkan fitur baru, dan memperkenalkan perubahan yang menyebabkan gangguan. Dokumen ini menjelaskan perubahan dan memberikan panduan migrasi. Anda dapat menerapkan rekomendasi ini sebelum menginstal versi 2.0 menggunakan BigQuery DataFrames versi 1.x terbaru.

BigQuery DataFrames versi 2.0 memiliki manfaat berikut:

  • Kueri yang lebih cepat dan lebih sedikit tabel dibuat saat Anda menjalankan kueri yang menampilkan hasil ke klien, karena allow_large_results secara default ditetapkan ke False. Hal ini dapat mengurangi biaya penyimpanan, terutama jika Anda menggunakan penagihan byte fisik.
  • Keamanan yang ditingkatkan secara default di fungsi jarak jauh yang di-deploy oleh BigQuery DataFrames.

Menginstal BigQuery DataFrames versi 2.0

Untuk menghindari perubahan yang merusak, sematkan ke versi BigQuery DataFrames tertentu dalam file requirements.txt (misalnya, bigframes==1.42.0) atau file pyproject.toml (misalnya, dependencies = ["bigframes = 1.42.0"]). Jika sudah siap untuk mencoba versi terbaru, Anda dapat menjalankan pip install --upgrade bigframes untuk menginstal BigQuery DataFrames versi terbaru.

Menggunakan opsi allow_large_results

BigQuery memiliki batas ukuran respons maksimum untuk tugas kueri. Mulai BigQuery DataFrames versi 2.0, BigQuery DataFrames menerapkan batas ini secara default dalam metode yang menampilkan hasil ke klien, seperti peek(), to_pandas(), dan to_pandas_batches(). Jika tugas menampilkan hasil yang besar, Anda dapat menetapkan allow_large_results ke True di objek BigQueryOptions untuk menghindari perubahan yang merusak. Opsi ini ditetapkan ke False secara default di BigQuery DataFrames versi 2.0.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Anda dapat mengganti opsi allow_large_results menggunakan parameter allow_large_results di to_pandas() dan metode lainnya. Contoh:

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

Menggunakan dekorator @remote_function

BigQuery DataFrames versi 2.0 membuat beberapa perubahan pada perilaku default dekorator @remote_function.

Argumen kata kunci diterapkan untuk parameter yang ambigu

Untuk mencegah penerusan nilai ke parameter yang tidak diinginkan, DataFrame BigQuery versi 2.0 dan yang lebih baru menerapkan penggunaan argumen kata kunci untuk parameter berikut:

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

Saat menggunakan parameter ini, berikan nama parameter. Contoh:

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Menetapkan akun layanan

Mulai versi 2.0, BigQuery DataFrames tidak lagi menggunakan akun layanan Compute Engine secara default untuk fungsi Cloud Run yang di-deploy. Untuk membatasi izin fungsi yang Anda deploy,

  1. Buat akun layanan dengan izin minimal.
  2. Berikan email akun layanan ke parameter cloud_function_service_account dari dekorator @remote_function.

Contoh:

@remote_function(
  cloud_function_service_account="my-service-account@my-project.s3ns-system.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Jika ingin menggunakan akun layanan Compute Engine, Anda dapat menetapkan parameter cloud_function_service_account dari dekorator @remote_function ke "default". Contoh:

# This usage is discouraged. Use only if you have a specific reason to use the
# default Compute Engine service account.
@remote_function(cloud_function_service_account="default", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Menetapkan setelan traffic masuk

Mulai versi 2.0, BigQuery DataFrames menetapkan setelan masuk fungsi Cloud Run yang di-deploy ke "internal-only". Sebelumnya, setelan ingress ditetapkan ke "all" secara default. Anda dapat mengubah setelan traffic masuk dengan menetapkan parameter cloud_function_ingress_settings dekorator @remote_function. Contoh:

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Menggunakan endpoint kustom

Pada versi BigQuery DataFrames sebelum 2.0, jika suatu region tidak mendukung endpoint layanan regional dan bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames akan kembali ke endpoint lokasi. BigQuery DataFrames versi 2.0 menghapus perilaku penggantian ini. Untuk terhubung ke endpoint lokasi di versi 2.0, tetapkan opsi bigframes.pandas.options.bigquery.client_endpoints_override. Misalnya:

import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

Ganti LOCATION dengan nama lokasi BigQuery yang ingin Anda hubungkan.

Menggunakan modul bigframes.ml.llm

Di BigQuery DataFrames versi 2.0, model_name default untuk GeminiTextGenerator telah diperbarui menjadi "gemini-2.0-flash-001". Sebaiknya pasok model_name secara langsung untuk menghindari kerusakan jika model default berubah pada masa mendatang.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

Input dan output

Dengan menggunakan library bigframes.pandas, Anda dapat mengakses data dari berbagai sumber, termasuk file CSV lokal, file Cloud Storage, DataFrame pandas, model BigQuery, dan fungsi BigQuery. Kemudian, Anda dapat memuat data tersebut ke dalam DataFrame BigQuery DataFrames. Anda juga dapat membuat tabel BigQuery dari DataFrame BigQuery.

Memuat data dari tabel atau kueri BigQuery

Anda dapat membuat DataFrame dari tabel atau kueri BigQuery dengan cara berikut:

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

Memuat data dari file CSV

Anda dapat membuat DataFrame dari file CSV lokal atau Cloud Storage dengan cara berikut:

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

Jenis data

BigQuery DataFrames mendukung jenis data numpy dan pandas berikut:

BigQuery BigQuery DataFrames dan pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

Hanya didukung oleh to_pandas()
INT64 pandas.Int64Dtype()
JSON pandas.ArrowDtype(pa.json_(pa.string()) di pandas versi 3.0 atau yang lebih baru dan pyarrow versi 19.0 atau yang lebih baru. Jika tidak, kolom JSON akan ditampilkan sebagai pandas.ArrowDtype(db_dtypes.JSONArrowType()).
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

DataFrame BigQuery tidak mendukung jenis data BigQuery berikut:

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

Semua jenis data BigQuery lainnya ditampilkan sebagai jenis objek.

Manipulasi data

Bagian berikut menjelaskan kemampuan manipulasi data untuk DataFrame BigQuery. Anda dapat menemukan fungsi yang dijelaskan dalam library bigframes.bigquery.

pandas API

Fitur penting dari BigQuery DataFrames adalah bigframes.pandas API dirancang agar mirip dengan API di library pandas. Dengan desain ini, Anda dapat menggunakan pola sintaksis yang sudah dikenal untuk tugas manipulasi data. Operasi yang ditentukan melalui BigQuery DataFrames API dijalankan di sisi server, yang beroperasi langsung pada data yang disimpan dalam BigQuery dan menghilangkan kebutuhan untuk mentransfer set data dari BigQuery.

Untuk memeriksa API pandas yang didukung oleh BigQuery DataFrames, lihat API pandas yang didukung.

Memeriksa dan memanipulasi data

Anda dapat menggunakan bigframes.pandas API untuk melakukan operasi pemeriksaan dan penghitungan data. Contoh kode berikut menggunakan library bigframes.pandas untuk memeriksa kolom body_mass_g, menghitung rata-rata body_mass, dan menghitung rata-rata body_mass menurut species:

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

Library BigQuery

Library BigQuery menyediakan fungsi SQL BigQuery yang mungkin tidak memiliki padanan pandas. Bagian berikut menampilkan beberapa contoh.

Memproses nilai array

Anda dapat menggunakan fungsi bigframes.bigquery.array_agg() di library bigframes.bigquery untuk menggabungkan nilai setelah operasi groupby:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

Anda juga dapat menggunakan fungsi array array_length() dan array_to_string().

Membuat seri struct

Anda dapat menggunakan fungsi bigframes.bigquery.struct() di library bigframes.bigquery untuk membuat deret struct baru dengan subkolom untuk setiap kolom dalam DataFrame:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

Mengonversi stempel waktu ke Unix epoch

Anda dapat menggunakan fungsi bigframes.bigquery.unix_micros() di library bigframes.bigquery untuk mengonversi stempel waktu menjadi mikrodetik Unix:

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

Anda juga dapat menggunakan fungsi waktu unix_seconds() dan unix_millis().

Menggunakan fungsi skalar SQL

Anda dapat menggunakan fungsi bigframes.bigquery.sql_scalar() di library bigframes.bigquery untuk mengakses sintaksis SQL arbitrer yang mewakili ekspresi kolom tunggal:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

Fungsi Python kustom

BigQuery DataFrames memungkinkan Anda mengubah fungsi Python kustom menjadi artefak BigQuery yang dapat Anda jalankan di objek BigQuery DataFrames dalam skala besar. Dukungan ekstensi ini memungkinkan Anda melakukan operasi di luar yang dapat dilakukan dengan BigQuery DataFrames dan SQL API, sehingga Anda berpotensi memanfaatkan library open source. Dua varian mekanisme ekstensi ini dijelaskan di bagian berikut.

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 kumpulan lengkap parameter yang didukung, lihat udf.

Pembersihan

Selain membersihkan artefak cloud langsung di konsol Trusted 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).

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.

Batasan

  • Kode dalam UDF harus mandiri, artinya, kode tidak boleh berisi referensi 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 berpengaruh pada perilaku fungsi.
  • Kode pengguna dapat dilihat oleh pengguna dengan akses baca di 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 mau, 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.

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

  1. Di Trusted Cloud konsol, buka halaman BigQuery.

    Buka BigQuery

  2. Pilih project tempat Anda membuat fungsi jarak jauh.

  3. Di panel Penjelajah, luaskan project, lalu luaskan Koneksi eksternal.

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, DataFrame BigQuery 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 tindakan berikut:

  1. Di Trusted Cloud konsol, buka halaman BigQuery.

    Buka BigQuery

  2. Pilih project tempat Anda membuat fungsi jarak jauh.

  3. Di panel Explorer, luaskan project, luaskan set data tempat Anda membuat fungsi jarak jauh, lalu luaskan Routines.

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. Filter berdasarkan Jenis Deployment Fungsi dalam daftar layanan yang tersedia.

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

Pembersihan

Selain membersihkan artefak cloud secara langsung di konsol Trusted 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).

Persyaratan

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

Batasan

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

ML dan AI

Bagian berikut menjelaskan kemampuan ML dan AI untuk DataFrame BigQuery. Kemampuan ini menggunakan library bigframes.ml.

Lokasi ML

Library bigframes.ml mendukung lokasi yang sama dengan BigQuery ML. Prediksi model BigQuery ML dan fungsi ML lainnya didukung di semua region BigQuery. Dukungan untuk pelatihan model bervariasi menurut wilayah. Untuk mengetahui informasi selengkapnya, lihat Lokasi BigQuery ML.

Melakukan prapemrosesan data

Buat pengubah untuk menyiapkan data agar dapat digunakan dalam estimator (model) dengan menggunakan modul bigframes.ml.preprocessing dan modul bigframes.ml.compose. DataFrame BigQuery menawarkan transformasi berikut:

  • Gunakan class KBinsDiscretizer dalam modul bigframes.ml.preprocessing untuk mengelompokkan data berkelanjutan ke dalam interval.

  • Gunakan class LabelEncoder dalam modul bigframes.ml.preprocessing untuk menormalisasi label target sebagai nilai bilangan bulat.

  • Gunakan class MaxAbsScaler dalam modul bigframes.ml.preprocessing untuk menskalakan setiap fitur ke rentang [-1, 1] berdasarkan nilai absolut maksimumnya.

  • Gunakan class MinMaxScaler di modul bigframes.ml.preprocessing untuk menstandarkan fitur dengan menskalakan setiap fitur ke rentang [0, 1].

  • Gunakan class StandardScaler di modul bigframes.ml.preprocessing untuk menstandarkan fitur dengan menghapus rata-rata dan penskalaan ke varian unit.

  • Gunakan class OneHotEncoder dalam modul bigframes.ml.preprocessing untuk mengubah nilai kategoris menjadi format numerik.

  • Gunakan class ColumnTransformer di modul bigframes.ml.compose untuk menerapkan pengubah ke kolom DataFrames.

Melatih model

Anda dapat membuat estimator untuk melatih model di BigQuery DataFrames.

Model pengelompokan

Anda dapat membuat estimator untuk model pengelompokan menggunakan modul bigframes.ml.cluster.

  • Gunakan class KMeans untuk membuat model pengelompokan K-means. Gunakan model ini untuk segmentasi data. Misalnya, mengidentifikasi segmen pelanggan. K-means adalah teknik unsupervised learning, sehingga pelatihan model tidak memerlukan label atau data terpisah untuk pelatihan atau evaluasi.

Anda dapat menggunakan modul bigframes.ml.cluster untuk membuat estimator untuk model pengelompokan.

Contoh kode berikut menunjukkan penggunaan class bigframes.ml.cluster KMeans untuk membuat model pengelompokan k-means untuk segmentasi data:

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

Model dekomposisi

Anda dapat membuat estimator untuk model dekomposisi menggunakan modul bigframes.ml.decomposition.

  • Gunakan class PCA untuk membuat model analisis komponen utama (PCA). Gunakan model ini untuk menghitung komponen utama dan menggunakannya untuk melakukan perubahan dasar pada data. Analisis ini memberikan pengurangan dimensi dengan memproyeksikan setiap titik data ke hanya beberapa komponen utama pertama guna mendapatkan data dimensi yang lebih rendah sekaligus mempertahankan variasi data sebanyak mungkin.

Model ensemble

Anda dapat membuat estimator untuk model ensemble menggunakan modul bigframes.ml.ensemble.

  • Gunakan class RandomForestClassifier untuk membuat model pengklasifikasi random forest. Gunakan model ini untuk membuat beberapa pohon keputusan metode pembelajaran untuk klasifikasi.

  • Gunakan class RandomForestRegressor untuk membuat model regresi random forest. Gunakan model ini untuk membuat beberapa pohon keputusan metode pembelajaran untuk regresi.

  • Gunakan class XGBClassifier untuk membuat model pengklasifikasi boosted tree gradien. Gunakan model ini untuk membuat beberapa pohon keputusan metode pembelajaran secara tambahan untuk klasifikasi.

  • Gunakan class XGBRegressor untuk membuat model regresi boosted tree gradien. Gunakan model ini untuk membuat beberapa pohon keputusan metode pembelajaran secara tambahan untuk regresi.

Model peramalan

Anda dapat membuat estimator untuk model perkiraan menggunakan modul bigframes.ml.forecasting.

Model yang diimpor

Anda dapat membuat estimator untuk model yang diimpor menggunakan modul bigframes.ml.imported.

Model linear

Buat estimator untuk model linear menggunakan modul bigframes.ml.linear_model.

  • Gunakan class LinearRegression untuk membuat model regresi linear. Gunakan model ini untuk perkiraan. Misalnya, memperkirakan penjualan suatu item pada hari tertentu.

  • Gunakan class LogisticRegression untuk membuat model regresi logistik. Gunakan model ini untuk klasifikasi dua atau beberapa nilai yang mungkin, seperti apakah inputnya low-value, medium-value, atau high-value.

Contoh kode berikut menunjukkan penggunaan bigframes.ml untuk melakukan hal berikut:

from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

Model Bahasa Besar

Anda dapat membuat estimator untuk LLM menggunakan modul bigframes.ml.llm.

Gunakan class GeminiTextGenerator untuk membuat model generator teks Gemini. Gunakan model ini untuk tugas pembuatan teks.

Gunakan modul bigframes.ml.llm untuk membuat estimator model bahasa besar (LLM) jarak jauh.
Contoh kode berikut menunjukkan penggunaan class GeminiTextGenerator bigframes.ml.llm untuk membuat model Gemini guna pembuatan kode:

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

Model jarak jauh

Untuk menggunakan model jarak jauh BigQuery DataFrames ML (bigframes.ml.remote atau bigframes.ml.llm), Anda harus mengaktifkan API berikut:

Membuat model jarak jauh di BigQuery DataFrames akan membuat koneksi BigQuery. Secara default, koneksi dengan nama bigframes-default-connection akan digunakan. Anda dapat menggunakan koneksi BigQuery yang telah dikonfigurasi sebelumnya jika mau, dan dalam hal ini pembuatan koneksi akan dilewati. Akun layanan untuk koneksi default diberi peran Vertex AI User (roles/aiplatform.user) di project.

Membuat pipeline

Anda dapat membuat pipeline ML menggunakan modul bigframes.ml.pipeline. Pipeline memungkinkan Anda menyusun beberapa langkah ML untuk divalidasi silang secara bersamaan sekaligus menetapkan parameter yang berbeda. Hal ini menyederhanakan kode Anda, dan memungkinkan Anda men-deploy langkah prapemrosesan data dan estimator secara bersamaan.

Gunakan class Pipeline untuk membuat pipeline transformasi dengan estimator akhir.

Memilih model

Gunakan modul bigframes.ml.model_selection untuk membagi set data pelatihan dan pengujian, serta memilih model terbaik:

  • Gunakan fungsi train_test_split untuk membagi data menjadi set pelatihan dan pengujian (evaluasi), seperti yang ditunjukkan dalam contoh kode berikut:

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • Gunakan class KFold dan metode KFold.split untuk membuat set pelatihan dan pengujian multi-lipatan guna melatih dan mengevaluasi model, seperti yang ditunjukkan dalam contoh kode berikut. Fitur ini sangat berguna untuk set data berukuran kecil.

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • Gunakan fungsi cross_validate untuk membuat set pelatihan dan pengujian multi-lipatan secara otomatis, melatih dan mengevaluasi model, serta mendapatkan hasil dari setiap lipatan, seperti yang ditunjukkan dalam contoh kode berikut:

    scores = cross_validate(model, X, y, cv=5)

Pengoptimalan performa

Bagian ini menyajikan cara mengoptimalkan performa DataFrame BigQuery.

Mode pengurutan sebagian

BigQuery DataFrame menyediakan fitur mode pengurutan. Tetapkan properti ordering_mode ke partial untuk menghasilkan kueri yang lebih efisien.

Mode pengurutan partial kontras dengan mode strict default, yang membuat pengurutan total di semua baris. Pengurutan total membuat DataFrame BigQuery lebih kompatibel dengan pandas dengan menyediakan akses berbasis urutan ke baris dengan properti DataFrame.iloc. Namun, urutan total dan indeks berurutan default pada urutan tersebut berarti bahwa filter kolom maupun filter baris tidak mengurangi jumlah byte yang dipindai, kecuali jika filter tersebut diterapkan sebagai parameter ke fungsi read_gbq dan read_gbq_table. Untuk memberikan pengurutan total di semua baris dalam DataFrame, BigQuery DataFrames membuat hash dari semua baris. Hal ini dapat menyebabkan pemindaian data lengkap yang mengabaikan filter baris dan kolom.

Menetapkan properti ordering_mode ke partial akan menghentikan DataFrame BigQuery agar tidak menghasilkan pengurutan total di semua baris. Mode pengurutan sebagian juga menonaktifkan fitur yang memerlukan pengurutan total di semua baris, seperti properti DataFrame.iloc. Mode pengurutan parsial menetapkan class DefaultIndexKind ke indeks null, bukan ke indeks berurutan berdasarkan pengurutan.

Saat memfilter DataFrame dengan properti ordering_mode yang ditetapkan ke partial, BigQuery DataFrames tidak perlu lagi menghitung baris mana yang tidak ada dalam indeks berurutan, sehingga menghasilkan kueri yang lebih cepat dan lebih efisien. BigQuery DataFrames API masih merupakan pandas API yang sudah dikenal, seperti pengalaman default dengan mode pengurutan yang ketat. Namun, mode pengurutan parsial akan berbeda dengan perilaku pandas umum. Misalnya, mode pengurutan parsial tidak melakukan join implisit menurut indeks.

Dengan mode pengurutan parsial dan ketat, Anda membayar resource BigQuery yang Anda gunakan. Namun, menggunakan mode pengurutan sebagian dapat mengurangi biaya saat menggunakan tabel berkelompok besar dan tabel berpartisi, karena filter baris pada kolom cluster dan partisi mengurangi jumlah byte yang diproses.

Penggunaan

Untuk menggunakan pengurutan sebagian, tetapkan properti ordering_mode ke partial sebelum melakukan operasi lain dengan DataFrame BigQuery, seperti yang ditunjukkan dalam contoh kode berikut:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Karena tidak ada indeks berurutan dengan mode pengurutan parsial, DataFrame BigQuery yang tidak terkait tidak digabungkan secara implisit. Sebagai gantinya, Anda harus memanggil metode DataFrame.merge secara eksplisit untuk menggabungkan dua DataFrame BigQuery yang berasal dari ekspresi tabel yang berbeda.

Fitur Series.unique() dan Series.drop_duplicates() tidak kompatibel dengan mode pengurutan sebagian. Sebagai gantinya, gunakan metode groupby untuk menemukan nilai unik dengan cara ini:

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

Dengan mode pengurutan parsial, output fungsi DataFrame.head(n) dan Series.head(n) tidak idempoten di seluruh semua pemanggilan. Untuk mendownload sampel data arbitrer yang kecil, gunakan metode DataFrame.peek() atau Series.peek().

Untuk tutorial mendetail tentang cara menggunakan properti ordering_mode = "partial", lihat notebook BigQuery DataFrames ini yang menunjukkan penggunaan mode pengurutan parsial.

Pemecahan masalah

Karena DataFrame dalam mode pengurutan parsial tidak selalu memiliki pengurutan atau indeks, Anda mungkin mengalami masalah berikut saat menggunakan beberapa metode yang kompatibel dengan pandas.

Error pesanan diperlukan

Beberapa fitur memerlukan pengurutan, seperti fungsi DataFrame.head() dan DataFrame.iloc. Untuk daftar fitur yang memerlukan pengurutan, lihat kolom Memerlukan pengurutan di API pandas yang didukung.

Jika tidak ada pengurutan pada objek, operasi akan gagal dengan pesan OrderRequiredError seperti berikut:

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

Seperti yang dijelaskan pesan error, Anda dapat memberikan pengurutan menggunakan metode DataFrame.sort_values() untuk mengurutkan menurut satu atau beberapa kolom. Operasi lain, seperti operasi DataFrame.groupby(), secara implisit memberikan pengurutan total atas grup menurut kunci.

Jika pengurutan tidak dapat ditentukan sebagai pengurutan total yang sepenuhnya stabil di semua baris, operasi berikutnya mungkin memperingatkan Anda dengan pesan AmbiguousWindowWarning seperti berikut:

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

Jika beban kerja Anda dapat mengakomodasi hasil non-deterministik atau Anda dapat memverifikasi secara manual bahwa pengurutan yang Anda berikan adalah pengurutan total, Anda dapat memfilter pesan AmbiguousWindowWarning dengan cara ini:

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
Error indeks null

Beberapa fitur memerlukan indeks, seperti properti DataFrame.unstack() dan Series.interpolate(). Untuk daftar fitur yang memerlukan indeks, lihat kolom Requires index di API pandas yang didukung.

Saat Anda menggunakan operasi yang memerlukan indeks dengan mode pengurutan sebagian, operasi akan menampilkan pesan NullIndexError seperti berikut:

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

Seperti yang dijelaskan pesan error, Anda dapat memberikan indeks menggunakan metode DataFrame.set_index() untuk mengurutkan menurut satu atau beberapa kolom. Operasi lain, seperti operasi DataFrame.groupby(), secara implisit memberikan indeks di seluruh grup berdasarkan kunci, kecuali jika parameter as_index=False ditetapkan.

Visualisasi

bigframes.pandas API adalah gateway ke ekosistem alat Python lengkap. API ini mendukung operasi statistik lanjutan, dan Anda dapat memvisualisasikan agregasi yang dihasilkan dari BigQuery DataFrames. Anda juga dapat beralih dari DataFrame BigQuery DataFrames ke DataFrame pandas dengan operasi sampling bawaan.

Langkah berikutnya