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 dua library:

  • bigframes.pandas, yang menyediakan API yang kompatibel dengan pandas untuk analitik.

  • bigframes.ml, yang menyediakan API seperti scikit-learn untuk machine learning (ML).

Izin yang diperlukan

Opsi

Setelah penginstalan, Anda perlu 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-dec"  # @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 untuk mengelola metadata secara internal. 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 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 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 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 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 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 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="[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 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 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 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")

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.

Mode pengurutan sebagian

BigQuery DataFrame menyediakan fitur mode pengurutan. Tetapkan 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 membuat 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 DefaultIndexKind ke indeks null, bukan ke indeks berurutan berdasarkan pengurutan.

Saat memfilter DataFrame dengan ordering_mode 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 seperti pandas, sama seperti pengalaman default dengan mode pengurutan ketat. Namun, mode pengurutan sebagian akan berbeda dengan perilaku pandas umum---misalnya, mode pengurutan sebagian tidak melakukan gabungan 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 parsial, 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"

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, hal ini dapat menyebabkan masalah umum saat menggunakan beberapa metode yang kompatibel dengan pandas.

Error pesanan wajib

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 berdasarkan 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 Memerlukan indeks 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.

Menggunakan library bigframes.pandas

Library bigframes.pandas menyediakan API mirip pandas yang dapat Anda gunakan untuk menganalisis dan memanipulasi data di BigQuery. bigframes.pandas API bersifat skalabel untuk mendukung pemrosesan terabyte data BigQuery, dan menggunakan mesin kueri BigQuery untuk melakukan penghitungan. Untuk mengetahui informasi selengkapnya, lihat API pandas yang didukung.

bigframes.pandas API menyediakan kemampuan berikut:

Input dan output

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

Manipulasi data

Anda dapat menggunakan Python, bukan SQL, untuk pengembangan. Anda dapat mengembangkan semua manipulasi data BigQuery di Python, sehingga tidak perlu beralih antarbahasa dan mencoba mengambil pernyataan SQL sebagai string teks. bigframes.pandas API menawarkan lebih dari 750 fungsi pandas.

Ekosistem dan visualisasi Python

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.

Fungsi Python kustom

BigQuery DataFrames memberi Anda kemampuan untuk mengubah fungsi skalar kustom menjadi fungsi jarak jauh BigQuery . Membuat fungsi jarak jauh di BigQuery DataFrames akan membuat:

  1. Fungsi Cloud Run (generasi ke-2).

  2. Koneksi BigQuery. Secara default, koneksi dengan nama bigframes-default-connection akan digunakan. Anda dapat menggunakan koneksi BigQuery yang telah dikonfigurasi sebelumnya jika mau. Jika demikian, pembuatan koneksi akan dilewati.

    Akun layanan untuk koneksi default diberi peran IAM Cloud Run Invoker (roles/run.invoker).

  3. Fungsi jarak jauh BigQuery yang menggunakan fungsi cloud (1) menggunakan koneksi BigQuery (2).

Untuk mengetahui contohnya, lihat Membuat fungsi jarak jauh.

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. Buka BigQuery di konsolGoogle Cloud .

  2. Pilih project tempat Anda membuat fungsi jarak jauh.

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

Fungsi jarak jauh BigQuery dibuat di set data yang Anda tentukan, atau di set data anonim, yaitu jenis set data tersembunyi. Jika Anda tidak menetapkan nama untuk fungsi jarak jauh selama pembuatannya, BigQuery DataFrames 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. Buka BigQuery di konsolGoogle Cloud .

  2. Pilih project tempat Anda membuat fungsi jarak jauh.

  3. Di panel Penjelajah, luaskan project tersebut, luaskan set data tempat Anda membuat fungsi jarak jauh, lalu luaskan Rutinitas.

Untuk melihat dan mengelola fungsi Cloud Run, gunakan halaman Functions dan gunakan pemilih project untuk memilih project tempat Anda membuat fungsi. Untuk mengidentifikasi fungsi yang dibuat oleh BigQuery DataFrames, cari fungsi yang namanya diawali dengan bigframes.

Anda dapat membersihkan fungsi jarak jauh BigQuery yang tidak bernama dan fungsi fungsi Cloud Run terkait dengan cara berikut:

  • Untuk session BigQuery DataFrames, gunakan session.close().
  • Untuk sesi BigQuery DataFrames default, gunakan bigframes.pandas.close_session().
  • Untuk sesi sebelumnya dengan session_id, gunakan bigframes.pandas.clean_up_by_session_id(session_id).

Persyaratan

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

Untuk menggunakan fungsi jarak jauh BigQuery DataFrames, Anda harus diberi peran IAM berikut dalam project:

Batasan

  • Fungsi jarak jauh memerlukan waktu sekitar 90 detik untuk tersedia saat Anda pertama kali membuatnya.

  • Perubahan sepele dalam notebook, seperti menyisipkan sel baru atau mengganti nama variabel, dapat menyebabkan fungsi jarak jauh dibuat ulang, meskipun perubahan ini tidak terkait dengan kode fungsi jarak jauh.

  • BigQuery DataFrames tidak membedakan data pribadi apa pun yang Anda sertakan dalam kode fungsi jarak jauh. Kode fungsi jarak jauh diserialisasi sebagai kotak buram untuk men-deploynya sebagai fungsi Cloud Run.

  • Fungsi Cloud Run (generasi ke-2), koneksi BigQuery, dan fungsi jarak jauh BigQuery yang dibuat oleh BigQuery DataFrames tetap ada diGoogle Cloud. Jika tidak ingin menyimpan resource ini, Anda harus menghapusnya secara terpisah menggunakan fungsi Cloud Run atau antarmuka BigQuery yang sesuai.

  • Sebuah project dapat memiliki hingga 1.000 fungsi Cloud Run (generasi ke-2) sekaligus. Lihat Kuota fungsi Cloud Run untuk mengetahui semua batas.

bigframes.pandas contoh

Contoh berikut menunjukkan cara umum menggunakan bigframes.pandas.

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()

Memeriksa dan memanipulasi data

Anda dapat menggunakan bigframes.pandas untuk melakukan operasi penghitungan dan pemeriksaan data.
Contoh kode berikut menunjukkan penggunaan bigframes.pandas untuk memeriksa kolom body_mass_g, menghitung body_mass rata-rata, dan menghitung body_mass rata-rata 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) )

Menggunakan library bigframes.bigquery

Library bigframes.bigquery menyediakan banyak fungsi SQL BigQuery yang mungkin tidak memiliki pandas yang setara.

Contoh berikut menunjukkan cara umum menggunakan bigframes.bigquery.

Membuat seri struct

Fungsi bigframes.bigquery.struct() 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]

Menggunakan fungsi skalar SQL

Gunakan fungsi bigframes.bigquery.sql_scalar() untuk mengakses sintaksis SQL arbitrer yang mewakili satu ekspresi 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

Menggunakan library bigframes.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.

Lokasi ML

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 di 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 dalam 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 di 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

Membuat estimator untuk melatih model di BigQuery DataFrames.

Model pengelompokan

Buat 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

Buat 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

Buat 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

Buat estimator untuk model perkiraan menggunakan modul bigframes.ml.forecasting.

Model yang diimpor

Buat 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

Buat estimator untuk LLM menggunakan modul bigframes.ml.llm.

Anda dapat menggunakan

Modul bigframes.ml.llm untuk membuat estimator model bahasa besar (LLM) jarak jauh.
Contoh kode berikut menunjukkan penggunaan bigframes.ml.llm

Class GeminiTextGenerator 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-1.5-flash-002" )  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:

Anda juga harus diberi peran IAM berikut dalam project:

  • BigQuery Connection Admin (roles/bigquery.connectionAdmin)
  • Admin IAM Project (roles/resourcemanager.projectIamAdmin) jika menggunakan koneksi BigQuery default, atau Browser (peran/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) akan digunakan apa adanya tanpa pemeriksaan izin atau keberadaan. Jika Anda menggunakan koneksi yang telah dikonfigurasi sebelumnya dan melewati pemeriksaan koneksi, pastikan koneksi dibuat di lokasi yang tepat dan akun layanannya memiliki peran Pengguna Vertex AI (roles/aiplatform.user) di project.

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, sehingga pembuatan koneksi akan dilewati. Akun layanan untuk koneksi default diberi peran IAM Vertex AI User (roles/aiplatform.user).

Membuat pipeline

Buat pipeline ML menggunakan modul bigframes.ml.pipeline. Pipeline memungkinkan Anda menyusun beberapa langkah ML untuk divalidasi secara silang bersama-sama sambil 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.

Langkah berikutnya