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. 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 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 disetel ke False secara default di BigQuery DataFrame 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 decorator @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, lakukan hal berikut:

  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="my-service-account@my-project.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 masuk 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")

Langkah berikutnya