Mengelola sesi dan I/O BigQuery DataFrames

Dokumen ini menjelaskan cara mengelola sesi dan melakukan operasi input dan output (I/O) saat Anda menggunakan BigQuery DataFrames. Anda akan mempelajari cara membuat dan menggunakan sesi, menggunakan data dalam memori, serta membaca dan menulis ke file dan tabel BigQuery.

Sesi BigQuery

BigQuery DataFrames menggunakan objek sesi lokal secara internal untuk mengelola metadata. Setiap objek DataFrame dan Series terhubung ke sesi, setiap sesi terhubung ke lokasi, dan setiap kueri dalam sesi berjalan di lokasi tempat Anda membuat sesi. Gunakan contoh kode berikut untuk membuat sesi secara manual dan menggunakannya untuk memuat data:

import bigframes
import bigframes.pandas as bpd

# Create session object
context = bigframes.BigQueryOptions(
    project=YOUR_PROJECT_ID,
    location=YOUR_LOCATION,
)
session = bigframes.Session(context)

# Load a BigQuery table into a dataframe
df1 = session.read_gbq("bigquery-public-data.ml_datasets.penguins")

# Create a dataframe with local data:
df2 = bpd.DataFrame({"my_col": [1, 2, 3]}, session=session)

Anda tidak dapat menggabungkan data dari beberapa instance sesi, meskipun Anda menginisialisasinya dengan setelan yang sama. Contoh kode berikut menunjukkan bahwa mencoba menggabungkan data dari instance sesi yang berbeda akan menyebabkan error:

import bigframes
import bigframes.pandas as bpd

context = bigframes.BigQueryOptions(location=YOUR_LOCATION, project=YOUR_PROJECT_ID)

session1 = bigframes.Session(context)
session2 = bigframes.Session(context)

series1 = bpd.Series([1, 2, 3, 4, 5], session=session1)
series2 = bpd.Series([1, 2, 3, 4, 5], session=session2)

try:
    series1 + series2
except ValueError as e:
    print(e)  # Error message: Cannot use combine sources from multiple sessions

Sesi global

BigQuery DataFrames menyediakan sesi global default yang dapat Anda akses dengan metode bigframes.pandas.get_global_session(). Di Colab, Anda harus memberikan project ID untuk atribut bigframes.pandas.options.bigquery.project sebelum menggunakannya. Anda juga dapat menetapkan lokasi dengan atribut bigframes.pandas.options.bigquery.location, yang secara default ditetapkan ke multi-region US.

Contoh kode berikut menunjukkan cara menetapkan opsi untuk sesi global:

import bigframes.pandas as bpd

# Set project ID for the global session
bpd.options.bigquery.project = YOUR_PROJECT_ID
# Update the global default session location
bpd.options.bigquery.location = YOUR_LOCATION

Untuk mereset lokasi atau project sesi global, tutup sesi saat ini dengan menjalankan metode bigframes.pandas.close_session().

Banyak fungsi bawaan BigQuery DataFrames menggunakan sesi global secara default. Contoh kode berikut menunjukkan cara fungsi bawaan menggunakan sesi global:

# The following two statements are essentially the same
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
df = bpd.get_global_session().read_gbq("bigquery-public-data.ml_datasets.penguins")

Data dalam memori

Anda dapat membuat objek DataFrames dan Series dengan struktur data Python atau NumPy bawaan, mirip dengan cara Anda membuat objek dengan pandas. Gunakan contoh kode berikut untuk membuat objek:

import numpy as np

import bigframes.pandas as bpd

s = bpd.Series([1, 2, 3])

# Create a dataframe with Python dict
df = bpd.DataFrame(
    {
        "col_1": [1, 2, 3],
        "col_2": [4, 5, 6],
    }
)

# Create a series with Numpy
s = bpd.Series(np.arange(10))

Untuk mengonversi objek pandas menjadi objek DataFrames menggunakan metode read_pandas() atau konstruktor, gunakan contoh kode berikut:

import numpy as np
import pandas as pd

import bigframes.pandas as bpd

pd_df = pd.DataFrame(np.random.randn(4, 2))

# Convert Pandas dataframe to BigQuery DataFrame with read_pandas()
df_1 = bpd.read_pandas(pd_df)
# Convert Pandas dataframe to BigQuery DataFrame with the dataframe constructor
df_2 = bpd.DataFrame(pd_df)

Untuk menggunakan metode to_pandas() guna memuat data BigQuery DataFrames ke dalam memori, gunakan contoh kode berikut:

import bigframes.pandas as bpd

bf_df = bpd.DataFrame({"my_col": [1, 2, 3]})
# Returns a Pandas Dataframe
bf_df.to_pandas()

bf_s = bpd.Series([1, 2, 3])
# Returns a Pandas Series
bf_s.to_pandas()

Estimasi biaya dengan parameter dry_run

Memuat data dalam jumlah besar dapat memerlukan banyak waktu dan resource. Untuk melihat jumlah data yang diproses, gunakan parameter dry_run=True dalam panggilan to_pandas(). Gunakan contoh kode berikut untuk melakukan uji coba:

import bigframes.pandas as bpd

df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")

# Returns a Pandas series with dry run stats
df.to_pandas(dry_run=True)

Membaca dan menulis file

Anda dapat membaca data dari file yang kompatibel ke BigQuery DataFrames. File ini dapat berada di komputer lokal atau di Cloud Storage. Gunakan contoh kode berikut untuk membaca data dari file CSV:

import bigframes.pandas as bpd

# Read a CSV file from GCS
df = bpd.read_csv("gs://cloud-samples-data/bigquery/us-states/us-states.csv")

Untuk menyimpan BigQuery DataFrames ke file lokal atau file Cloud Storage menggunakan metode to_csv, gunakan contoh kode berikut:

import bigframes.pandas as bpd

df = bpd.DataFrame({"my_col": [1, 2, 3]})
# Write a dataframe to a CSV file in GCS
df.to_csv(f"gs://{YOUR_BUCKET}/myfile*.csv")

Membaca dan menulis tabel BigQuery

Untuk membuat BigQuery DataFrames menggunakan referensi tabel BigQuery dan fungsi bigframes.pandas.read_gbq, gunakan contoh kode berikut:

import bigframes.pandas as bpd

df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")

Untuk menggunakan string SQL dengan fungsi read_gbq() guna membaca data ke BigQuery DataFrames, gunakan contoh kode berikut:

import bigframes.pandas as bpd

sql = """
SELECT species, island, body_mass_g
FROM bigquery-public-data.ml_datasets.penguins
WHERE sex = 'MALE'
"""

df = bpd.read_gbq(sql)

Untuk menyimpan objek DataFrame ke tabel BigQuery, gunakan metode to_gbq() dari objek DataFrame Anda. Contoh kode berikut menunjukkan cara melakukannya:

import bigframes.pandas as bpd

df = bpd.DataFrame({"my_col": [1, 2, 3]})

df.to_gbq(f"{YOUR_PROJECT_ID}.{YOUR_DATASET_ID}.{YOUR_TABLE_NAME}")

Langkah berikutnya