BigQuery DataFrames セッションと I/O を管理する

このドキュメントでは、BigQuery DataFrames の使用時にセッションを管理し、入出力（I/O）オペレーションを実行する方法について説明します。セッションの作成と使用、インメモリデータの操作、ファイルと BigQuery テーブルからの読み取りと書き込みの方法について説明します。

BigQuery セッション

BigQuery DataFrames は、メタデータの管理に内部的にローカルセッションオブジェクトを使用します。各 DataFrame オブジェクトと Series オブジェクトはセッションに接続され、各セッションはロケーションに接続されます。セッション内の各クエリは、セッションを作成したロケーションで実行されます。次のコードサンプルを使用して、セッションを手動で作成し、データの読み込みに使用します。

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)

複数のセッションインスタンスを同じ設定で初期化しても、それらのデータを結合することはできません。次のコードサンプルは、異なるセッションインスタンスのデータを結合しようとするとエラーが発生することを示しています。

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

グローバルセッション

BigQuery DataFrames には、bigframes.pandas.get_global_session() メソッドでアクセスできるデフォルトのグローバルセッションが用意されています。Colab では、bigframes.pandas.options.bigquery.project 属性を使用する前に、その属性のプロジェクト ID を指定する必要があります。bigframes.pandas.options.bigquery.location 属性を使用してロケーションを設定することもできます。デフォルトは US マルチリージョンです。

次のコードサンプルは、グローバルセッションのオプションを設定する方法を示しています。

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

グローバルセッションのロケーションまたはプロジェクトをリセットするには、bigframes.pandas.close_session() メソッドを実行して現在のセッションを閉じます。

多くの BigQuery DataFrames 組み込み関数は、デフォルトでグローバルセッションを使用します。次のコードサンプルは、組み込み関数がグローバルセッションを使用する方法を示しています。

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

インメモリデータ

pandas でオブジェクトを作成する方法と同様に、組み込みの Python または NumPy データ構造を使用して Dataframes オブジェクトと Series オブジェクトを作成できます。次のコードサンプルを使用してオブジェクトを作成します。

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

read_pandas() メソッドまたはコンストラクタを使用して pandas オブジェクトを DataFrames オブジェクトに変換するには、次のコードサンプルを使用します。

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)

to_pandas() メソッドを使用して BigQuery DataFrames データをメモリに読み込むには、次のコードサンプルを使用します。

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

`dry_run` パラメータを使用した費用見積もり

大量のデータを読み込むには、多くの時間とリソースが必要になることがあります。処理されるデータ量を確認するには、to_pandas() 呼び出しで dry_run=True パラメータを使用します。次のコードサンプルを使用して、ドライランを実行します。

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)

ファイルの読み取りと書き込み

互換性のあるファイルから BigQuery DataFrames にデータを読み取ることができます。これらのファイルは、ローカルマシンまたは Cloud Storage に保存できます。次のコードサンプルを使用して、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")

to_csv メソッドを使用して BigQuery DataFrames をローカルファイルまたは Cloud Storage ファイルに保存するには、次のコードサンプルを使用します。

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

BigQuery テーブルの読み取りと書き込み

BigQuery テーブル参照と bigframes.pandas.read_gbq 関数を使用して BigQuery DataFrames を作成するには、次のコードサンプルを使用します。

import bigframes.pandas as bpd

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

read_gbq() 関数で SQL 文字列を使用して BigQuery DataFrames にデータを読み込むには、次のコードサンプルを使用します。

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)

DataFrame オブジェクトを BigQuery テーブルに保存するには、DataFrame オブジェクトの to_gbq() メソッドを使用します。次のコードサンプルは、その方法を示しています。

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}")

次のステップ

BigQuery DataFrames の使用方法について確認する。
BigQuery DataFrames でデータ型の操作方法について確認する。
BigQuery DataFrames を使用してグラフを可視化する方法を確認する。
BigQuery DataFrames API リファレンスを確認する。