Bermigrasi ke BigQuery DataFrames 2.0

Pada 16 April 2025, tim BigQuery DataFrames berencana merilis BigQuery DataFrames versi 2.0. Versi ini meningkatkan keamanan dan performa pada BigQuery DataFrames API serta menambahkan fitur baru. Dokumen ini menjelaskan perubahan dan memberikan panduan migrasi. Anda dapat menerapkan rekomendasi ini sebelum rilis menggunakan BigQuery DataFrames versi 1.x terbaru atau dengan menginstal paket 2.0 versi pra-rilis.

Menginstal BigQuery DataFrames versi 2.0

Untuk menghindari perubahan yang merusak, sematkan ke versi BigQuery DataFrames tertentu dalam file requirements.txt (misalnya, bigframes==1.38.0) atau file pyproject.toml (misalnya, dependencies = ["bigframes = 1.38.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.

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. Kemudian, 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.",
    ...
  )
  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". Misalnya:


  # 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 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

Sebelumnya, jika suatu region tidak mendukung endpoint layanan regional dan bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrame akan kembali ke endpoint lokasi. DataFrame BigQuery 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. Contoh:


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 mode pengurutan sebagian

Dengan BigQuery DataFrames versi 2.0, mode pengurutan sebagian tersedia secara umum, tetapi tidak diaktifkan secara default. Untuk menggunakan pengurutan sebagian, tetapkan ordering_mode ke partial sebelum melakukan operasi lain dengan BigQuery DataFrames, seperti yang ditunjukkan dalam contoh kode berikut:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Dalam sebagian besar kasus, mode ini menghasilkan kueri yang lebih efisien, dan kueri yang identik dalam kasus lainnya, seperti kueri yang menggunakan fungsi groupby(). Beberapa fungsi yang kompatibel dengan pandas yang memerlukan pengurutan, seperti .iloc[row_index], tidak didukung dalam mode pengurutan sebagian. Untuk mengetahui informasi selengkapnya, lihat Mode pengurutan sebagian.

Langkah berikutnya