Gestire le sessioni e l'I/O di BigQuery DataFrames

Questo documento spiega come gestire le sessioni ed eseguire operazioni di input e output (I/O) quando utilizzi BigQuery DataFrames. Imparerai a creare e utilizzare le sessioni, a lavorare con i dati in memoria e a leggere e scrivere in file e tabelle BigQuery.

Sessioni BigQuery

BigQuery DataFrames utilizza internamente un oggetto sessione locale per gestire i metadati. Ogni oggetto DataFrame e Series si connette a una sessione, ogni sessione si connette a una posizione e ogni query in una sessione viene eseguita nella posizione in cui hai creato la sessione. Utilizza il seguente esempio di codice per creare manualmente una sessione e utilizzarla per caricare i dati:

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)

Non puoi combinare i dati di più istanze di sessione, anche se le inizializzi con le stesse impostazioni. Il seguente esempio di codice mostra che il tentativo di combinare dati di istanze di sessione diverse causa un errore:

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

Sessione globale

BigQuery DataFrames fornisce una sessione globale predefinita a cui puoi accedere con il metodo bigframes.pandas.get_global_session(). In Colab, devi fornire un ID progetto per l'attributo bigframes.pandas.options.bigquery.project prima di utilizzarlo. Puoi anche impostare una località con l'attributo bigframes.pandas.options.bigquery.location, che per impostazione predefinita è la multi-regione US.

Il seguente esempio di codice mostra come impostare le opzioni per la sessione globale:

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

Per reimpostare la posizione o il progetto della sessione globale, chiudi la sessione corrente eseguendo il metodo bigframes.pandas.close_session().

Molte funzioni integrate di BigQuery DataFrames utilizzano la sessione globale per impostazione predefinita. Il seguente esempio di codice mostra come le funzioni integrate utilizzano la sessione globale:

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

Dati in memoria

Puoi creare oggetti Dataframes e Series con strutture di dati Python o NumPy integrate, in modo simile a come crei oggetti con pandas. Utilizza il seguente esempio di codice per creare un oggetto:

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

Per convertire gli oggetti pandas in oggetti DataFrames utilizzando il metodo read_pandas() o i costruttori, utilizza il seguente esempio di codice:

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)

Per utilizzare il metodo to_pandas() per caricare i dati di BigQuery DataFrames nella memoria, utilizza il seguente esempio di codice:

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

Stima dei costi con il parametro dry_run

Il caricamento di una grande quantità di dati può richiedere molto tempo e risorse. Per vedere la quantità di dati in fase di elaborazione, utilizza il parametro dry_run=True nella chiamata to_pandas(). Utilizza il seguente esempio di codice per eseguire un dry run:

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)

Lettura e scrittura nei file

Puoi leggere i dati da file compatibili in un BigQuery DataFrames. Questi file possono trovarsi sulla tua macchina locale o in Cloud Storage. Utilizza il seguente esempio di codice per leggere i dati da un 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")

Per salvare i DataFrame BigQuery in file locali o file Cloud Storage utilizzando il metodo to_csv, utilizza il seguente esempio di codice:

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

Leggere e scrivere tabelle BigQuery

Per creare BigQuery DataFrames utilizzando i riferimenti alle tabelle BigQuery e la funzione bigframes.pandas.read_gbq, utilizza il seguente codice di esempio:

import bigframes.pandas as bpd

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

Per utilizzare una stringa SQL con la funzione read_gbq() per leggere i dati in BigQuery DataFrames, utilizza il seguente esempio di codice:

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)

Per salvare l'oggetto DataFrame in una tabella BigQuery, utilizza il metodo to_gbq() dell'oggetto DataFrame. Il seguente esempio di codice mostra come farlo:

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

Passaggi successivi