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 dapat menyebabkan gangguan. Dokumen ini menjelaskan perubahan dan memberikan panduan migrasi. Anda dapat menerapkan rekomendasi ini sebelum menginstal versi 2.0 dengan menggunakan BigQuery DataFrames versi 1.x terbaru.

BigQuery DataFrames versi 2.0 memiliki manfaat berikut:

  • Kueri yang lebih cepat dan tabel yang lebih sedikit akan dibuat saat Anda menjalankan kueri yang menampilkan hasil ke klien, karena allow_large_results ditetapkan secara default ke False. Desain 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 dapat menyebabkan gangguan, sematkan ke versi BigQuery DataFrames tertentu di file requirements.txt (misalnya, bigframes==1.42.0) atau file pyproject.toml (misalnya, dependencies = ["bigframes = 1.42.0"]). Jika sudah 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 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 menetapkan allow_large_results ke True di objek BigQueryOptions untuk menghindari perubahan yang dapat menyebabkan gangguan. 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, 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 parameternya. 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, lakukan hal berikut:

  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.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 ingress

Mulai versi 2.0, BigQuery DataFrames menetapkan setelan traffic 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 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

Di BigQuery DataFrames versi sebelum 2.0, jika suatu region tidak mendukung endpoint layanan regional dan bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames akan beralih 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

Sebaiknya berikan model_name yang didukung secara langsung (seperti "gemini-3.5-flash") untuk menghindari kerusakan jika model default berubah di masa mendatang.

import bigframes.ml.llm

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

Langkah berikutnya