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 file e tabelle BigQuery.

Sessioni BigQuery

BigQuery DataFrames utilizza internamente un oggetto sessione locale per gestire i metadati. Ogni DataFrame e Series oggetto si connette a una sessione, ogni sessione si connette a una località, e ogni query in una sessione viene eseguita nella località 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 i dati di istanze di sessione diverse genera 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 bigframes.pandas.get_global_session() metodo. 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' bigframes.pandas.options.bigquery.location attributo, che per impostazione predefinita è la US multi-regione.

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 località 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 in 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 elaborati, utilizza il dry_run=True parametro nella to_pandas() chiamata. Utilizza il seguente esempio di codice per eseguire un'esecuzione di prova:

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)

Leggere e scrivere file

Puoi leggere i dati dai file compatibili in un BigQuery DataFrames. Questi file possono essere 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 BigQuery DataFrames nei file locali o nei file di 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 esempio di codice:

import bigframes.pandas as bpd

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

Per utilizzare una stringa SQL con la read_gbq() funzione 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 eseguire questa operazione:

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