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

内存中数据

您可以使用内置的 Python 或 NumPy 数据结构创建 Dataframes 和 Series 对象，这与使用 pandas 创建对象的方式类似。使用以下代码示例创建对象：

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 DataFrame 保存到本地文件或 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}")

后续步骤