Gerenciar sessões e E/S do BigQuery DataFrames

Neste documento, explicamos como gerenciar sessões e realizar operações de entrada e saída (E/S) ao usar DataFrames do BigQuery. Você vai aprender a criar e usar sessões, trabalhar com dados na memória e ler e gravar em arquivos e tabelas do BigQuery.

Sessões do BigQuery

O BigQuery DataFrames usa um objeto de sessão local internamente para gerenciar metadados. Cada objeto DataFrame e Series se conecta a uma sessão, cada sessão se conecta a um local, e cada consulta em uma sessão é executada no local em que você criou a sessão. Use o exemplo de código a seguir para criar uma sessão manualmente e usá-la para carregar dados:

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)

Não é possível combinar dados de várias instâncias de sessão, mesmo que você as inicialize com as mesmas configurações. O exemplo de código a seguir mostra que tentar combinar dados de diferentes instâncias de sessão causa um erro:

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

Sessão global

O DataFrames do BigQuery fornece uma sessão global padrão que pode ser acessada com o método bigframes.pandas.get_global_session(). No Colab, você precisa fornecer um ID do projeto para o atributo bigframes.pandas.options.bigquery.project antes de usá-lo. Você também pode definir um local com o atributo bigframes.pandas.options.bigquery.location, que tem como padrão a multirregião US.

O exemplo de código a seguir mostra como definir opções para a sessão 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

Para redefinir o local ou o projeto da sessão global, encerre a sessão atual executando o método bigframes.pandas.close_session().

Muitas funções integradas do BigQuery DataFrames usam a sessão global por padrão. O exemplo de código a seguir mostra como as funções integradas usam a sessão 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")

Dados na memória

É possível criar objetos Dataframes e Series com estruturas de dados integradas do Python ou do NumPy, de maneira semelhante à criação de objetos com pandas. Use o exemplo de código a seguir para criar um objeto:

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

Para converter objetos pandas em objetos DataFrames usando o método ou construtores read_pandas(), use o seguinte exemplo de código:

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)

Para usar o método to_pandas() e carregar dados de DataFrames do BigQuery na memória, use o seguinte exemplo de código:

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

Estimativa de custos com o parâmetro dry_run

Carregar uma grande quantidade de dados pode levar muito tempo e recursos. Para saber a quantidade de dados que está sendo processada, use o parâmetro dry_run=True na chamada to_pandas(). Use o exemplo de código a seguir para fazer uma simulação:

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)

Ler e gravar arquivos

É possível ler dados de arquivos compatíveis em um BigQuery DataFrames. Esses arquivos podem estar na sua máquina local ou no Cloud Storage. Use o exemplo de código a seguir para ler dados de um arquivo 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")

Para salvar seus DataFrames do BigQuery em arquivos locais ou do Cloud Storage usando o método to_csv, use o exemplo de código a seguir:

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

Ler e gravar tabelas do BigQuery

Para criar DataFrames do BigQuery usando referências de tabela do BigQuery e a função bigframes.pandas.read_gbq, use o seguinte exemplo de código:

import bigframes.pandas as bpd

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

Para usar uma string SQL com a função read_gbq() e ler dados em DataFrames do BigQuery, use o exemplo de código a seguir:

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)

Para salvar o objeto DataFrame em uma tabela do BigQuery, use o método to_gbq() do objeto DataFrame. O exemplo de código a seguir mostra como fazer isso:

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

A seguir