Menggunakan BigQuery DataFrames

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

DataFrame BigQuery menyediakan tiga library:

  • bigframes.pandas menyediakan API pandas yang dapat Anda gunakan untuk menganalisis dan memanipulasi data di BigQuery. Banyak beban kerja dapat dimigrasikan dari pandas ke bigframes hanya dengan mengubah beberapa impor. API bigframes.pandas dapat diskalakan untuk mendukung pemrosesan data BigQuery berukuran terabyte, dan API ini menggunakan mesin kueri BigQuery untuk melakukan penghitungan.
  • bigframes.bigquery menyediakan banyak fungsi SQL BigQuery yang mungkin tidak memiliki fungsi pandas yang setara.
  • bigframes.ml menyediakan API yang mirip dengan API scikit-learn untuk ML. Kemampuan ML di BigQuery DataFrames memungkinkan Anda memproses data terlebih dahulu, lalu melatih model berdasarkan data tersebut. Anda juga dapat menggabungkan 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 ML BigQuery DataFrames, Anda memerlukan peran Project IAM Admin (roles/resourcemanager.projectIamAdmin) jika Anda menggunakan koneksi BigQuery default, atau peran Browser (roles/browser) jika Anda menggunakan koneksi yang telah dikonfigurasi sebelumnya. Persyaratan ini dapat dihindari dengan menetapkan opsi bigframes.pandas.options.bigquery.skip_bq_connection_check ke True, yang dalam hal ini koneksi (default atau yang telah dikonfigurasi sebelumnya) 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.
  • Jika Anda menggunakan model jarak jauh ML BigQuery DataFrames, 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, DataFrame BigQuery 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 perlu menentukan lokasi dan project tempat Anda ingin menggunakan DataFrame BigQuery.

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

DataFrame BigQuery dirancang untuk skala besar, yang dicapainya 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 Anda akan berlaku.

Lokasi sesi

BigQuery DataFrames menggunakan objek sesi lokal secara internal untuk mengelola metadata. Sesi ini terkait 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 kueri tidak berada di multi-region US. Jika Anda mencoba membaca tabel dari lokasi lain, Anda akan mendapatkan pengecualian NotFound.

Bermigrasi ke BigQuery DataFrames versi 2.0

BigQuery DataFrames versi 2.0 melakukan peningkatan keamanan dan performa pada 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 dengan menggunakan DataFrame BigQuery 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 adalah False. Hal ini dapat mengurangi biaya penyimpanan, terutama jika Anda menggunakan penagihan byte fisik.
  • Peningkatan keamanan secara default dalam fungsi jarak jauh yang di-deploy oleh BigQuery DataFrames.

Menginstal BigQuery DataFrames versi 2.0

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

Menggunakan opsi allow_large_results

BigQuery memiliki batas ukuran respons maksimum untuk tugas kueri. Mulai dari 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 Anda menampilkan hasil yang besar, Anda dapat menyetel 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 ambigu

Untuk mencegah penerusan nilai ke parameter yang tidak diinginkan, BigQuery DataFrames 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-nya. 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 decorator @remote_function.

Contoh:

@remote_function(
  cloud_function_service_account="[email protected]",
  ...
)
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 ingress fungsi Cloud Run yang di-deploy ke "internal-only". Sebelumnya, setelan ingress ditetapkan ke "all" secara default. Anda dapat mengubah setelan ingress dengan menyetel parameter cloud_function_ingress_settings dari 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 yang lebih lama dari 2.0, jika suatu region tidak mendukung endpoint layanan regional dan bigframes.pandas.options.bigquery.use_regional_endpoints = True, maka BigQuery DataFrames akan melakukan penggantian 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 diupdate menjadi "gemini-2.0-flash-001". Sebaiknya Anda memberikan 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 library bigframes.pandas, Anda dapat mengakses data dari berbagai sumber, termasuk file CSV lokal, file Cloud Storage, DataFrame bigframes.pandas, model BigQuery, dan fungsi BigQuery.pandas 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

DataFrame BigQuery mendukung dtypes 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 diekspos 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 BigQuery DataFrames adalah bigframes.pandas API didesain agar mirip dengan API di library pandas. Desain ini memungkinkan Anda menggunakan pola sintaksis yang sudah dikenal untuk tugas manipulasi data. Operasi yang ditentukan melalui BigQuery DataFrames API dieksekusi di sisi server, beroperasi langsung pada data yang disimpan dalam BigQuery dan menghilangkan kebutuhan untuk mentransfer set data keluar dari BigQuery.

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

Memeriksa dan memanipulasi data

Anda dapat menggunakan bigframes.pandas API untuk melakukan operasi inspeksi dan kalkulasi 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 deret struct

Anda dapat menggunakan fungsi bigframes.bigquery.struct() di library bigframes.bigquery untuk membuat deret struct baru dengan sub-bidang untuk setiap kolom di 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 menjadi epoch Unix

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 merepresentasikan ekspresi satu kolom:

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

Dengan BigQuery DataFrames, Anda dapat mengubah fungsi Python kustom menjadi artefak BigQuery yang dapat Anda jalankan pada objek BigQuery DataFrames dalam skala besar. Dukungan ekstensibilitas 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 ekstensibilitas 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 mengetahui kumpulan lengkap parameter yang didukung, lihat udf.

Pembersihan

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

Persyaratan

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

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 itulah 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 penting bagi perilaku fungsi.
  • Kode pengguna dapat dilihat oleh pengguna dengan akses baca pada rutinitas BigQuery, jadi Anda harus menyertakan konten sensitif dengan hati-hati.
  • 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:

  • Cloud Run function.
  • Koneksi BigQuery. Secara default, koneksi bernama bigframes-default-connection digunakan. Anda dapat menggunakan koneksi BigQuery yang telah dikonfigurasi sebelumnya jika mau, yang dalam hal ini 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 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 Explorer, luaskan project, lalu luaskan External 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, DataFrame BigQuery akan menerapkan nama default yang dimulai dengan prefiks bigframes. Untuk melihat dan mengelola fungsi jarak jauh yang dibuat dalam set data yang ditentukan pengguna, lakukan langkah berikut:

  1. Di Google 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 pada Function Deployment type dalam daftar layanan yang tersedia.

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

Pembersihan

Selain menghapus artefak cloud secara langsung di konsol Google Cloud atau dengan alat lain, Anda dapat menghapus 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 menghapus 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 DataFrame BigQuery, Anda harus mengaktifkan API berikut:

Batasan

  • Fungsi jarak jauh memerlukan waktu sekitar 90 detik agar dapat digunakan saat Anda pertama kali 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 penting bagi perilaku fungsi.
  • Kode pengguna dapat dilihat oleh pengguna dengan akses baca di fungsi Cloud Run, jadi Anda harus menyertakan konten sensitif dengan hati-hati.
  • Project dapat memiliki hingga 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 BigQuery DataFrames. Kemampuan ini menggunakan library bigframes.ml.

Lokasi ML

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

Memproses data

Buat transformer untuk menyiapkan data yang akan digunakan dalam estimator (model) dengan menggunakan modul bigframes.ml.preprocessing dan modul bigframes.ml.compose. BigQuery DataFrames menawarkan transformasi berikut:

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

  • Gunakan LabelEncoder class 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 menstandardisasi fitur dengan menskalakan setiap fitur ke rentang [0, 1].

  • Gunakan class StandardScaler dalam modul bigframes.ml.preprocessing untuk menstandardisasi fitur dengan menghapus mean dan menskalakan ke varians unit.

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

  • Gunakan class ColumnTransformer dalam modul bigframes.ml.compose untuk menerapkan transformer ke kolom DataFrame.

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 bagi 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. Metode 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 ansambel 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 pohon yang ditingkatkan gradiennya. Gunakan model ini untuk membuat beberapa pohon keputusan metode pembelajaran secara aditif untuk klasifikasi.

  • Gunakan class XGBRegressor untuk membuat model regresi pohon yang ditingkatkan gradiennya. Gunakan model ini untuk membuat beberapa pohon keputusan metode pembelajaran secara aditif untuk regresi.

Model prakiraan

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 peramalan. 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 bagi model bahasa besar (LLM) jarak jauh.
Contoh kode berikut menunjukkan penggunaan class bigframes.ml.llm GeminiTextGenerator untuk membuat model Gemini bagi 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 ML BigQuery DataFrames (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 digunakan. Anda dapat menggunakan koneksi BigQuery yang telah dikonfigurasi sebelumnya jika mau, dalam hal ini pembuatan koneksi 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. Dengan Pipelines, Anda dapat mengumpulkan beberapa langkah ML untuk divalidasi silang bersama-sama sambil menetapkan parameter yang berbeda. Hal ini menyederhanakan kode Anda, dan memungkinkan Anda men-deploy langkah-langkah praproses data dan estimator secara bersamaan.

Gunakan class Pipeline untuk membuat pipeline transformasi dengan estimator akhir.

Pilih model

Gunakan modul bigframes.ml.model_selection untuk memisahkan 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-fold guna melatih dan mengevaluasi model, seperti yang ditunjukkan dalam contoh kode berikut. Fitur ini berguna untuk set data 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-fold secara otomatis, melatih dan mengevaluasi model, serta mendapatkan hasil setiap fold, seperti yang ditunjukkan dalam contoh kode berikut:

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

Pengoptimalan performa

Bagian ini menyajikan cara untuk mengoptimalkan performa DataFrame BigQuery Anda.

Mode pemesanan sebagian

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

Mode pengurutan partial berbeda dengan mode strict default, yang membuat pengurutan total di semua baris. Pengurutan total membuat BigQuery DataFrames lebih kompatibel dengan pandas dengan menyediakan akses berbasis urutan ke baris dengan properti DataFrame.iloc. Namun, pengurutan total dan indeks berurutan default atas pengurutan 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 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 parsial 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 di atas 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 tetap merupakan pandas API yang sudah dikenal, seperti pengalaman default dengan mode pengurutan ketat. Namun, mode pengurutan parsial akan berbeda dari perilaku pandas umum---misalnya, mode pengurutan parsial tidak melakukan penggabungan implisit berdasarkan indeks.

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

Penggunaan

Untuk menggunakan pengurutan parsial, 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 berikut:

# 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 bersifat idempoten di semua pemanggilan. Untuk mendownload sampel data kecil yang arbitrer, gunakan metode DataFrame.peek() atau Series.peek().

Untuk tutorial mendetail yang 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 mengetahui daftar fitur yang memerlukan pemesanan, lihat kolom Memerlukan pemesanan 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 dalam 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 pada kunci pengelompokan.

Jika pengurutan tidak dapat ditentukan sebagai pengurutan total yang sepenuhnya stabil di semua baris, operasi berikutnya mungkin akan 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 Memerlukan indeks di API pandas yang Didukung.

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

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

Seperti yang dijelaskan dalam 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 menyediakan indeks melalui pengelompokan menurut kunci, kecuali parameter as_index=False ditetapkan.

Langkah berikutnya