Faça a gestão das sessões e da E/S do BigQuery DataFrames

Este documento explica como gerir sessões e realizar operações de entrada e saída (E/S) quando usa DataFrames do BigQuery. Vai aprender a criar e usar sessões, trabalhar com dados na memória e ler e escrever em ficheiros e tabelas do BigQuery.

Sessões do BigQuery

O BigQuery DataFrames usa um objeto de sessão local internamente para gerir metadados. Cada objeto DataFrame e Series está ligado a uma sessão. Cada sessão está ligada a uma localização, e cada consulta numa sessão é executada na localização onde criou a sessão. Use o exemplo de código seguinte para criar manualmente uma sessão 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 pode combinar dados de várias instâncias de sessões, mesmo que os inicialize com as mesmas definições. O exemplo de código seguinte mostra que a tentativa de combinar dados de diferentes instâncias de sessões provoca 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 BigQuery DataFrames fornece uma sessão global predefinida à qual pode aceder com o método bigframes.pandas.get_global_session(). No Colab, tem de fornecer um ID do projeto para o atributo bigframes.pandas.options.bigquery.project antes de o usar. Também pode definir uma localização com o atributo bigframes.pandas.options.bigquery.location, que é predefinido para a US multirregião.

O seguinte exemplo de código 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 repor a localização ou o projeto da sessão global, feche a sessão atual executando o método bigframes.pandas.close_session().

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

Pode criar objetos Dataframes e Series com estruturas de dados Python ou NumPy incorporadas, de forma semelhante à criação de objetos com o pandas. Use o exemplo de código seguinte 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 através do método read_pandas() ou dos construtores, 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() para carregar dados de DataFrames do BigQuery para a 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

O carregamento de uma grande quantidade de dados pode demorar muito tempo e consumir muitos recursos. Para ver a quantidade de dados que está a ser processada, use o parâmetro dry_run=True na chamada to_pandas(). Use o seguinte exemplo de código para fazer um teste de execuçã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 escrever ficheiros

Pode ler dados de ficheiros compatíveis para um BigQuery DataFrames. Estes ficheiros podem estar no seu computador local ou no armazenamento na nuvem. Use o seguinte exemplo de código para ler dados de um ficheiro 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 guardar os seus DataFrames do BigQuery em ficheiros locais ou ficheiros do Cloud Storage através do método to_csv, use o seguinte exemplo de código:

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 escrever tabelas do BigQuery

Para criar DataFrames do BigQuery com referências de tabelas 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() para ler dados em DataFrames do BigQuery, use o seguinte exemplo de código:

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 guardar o objeto DataFrame numa tabela do BigQuery, use o método to_gbq() do objeto DataFrame. O seguinte exemplo de código mostra como o fazer:

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

O que se segue?