Gérer les sessions et les E/S BigQuery DataFrames

Ce document explique comment gérer les sessions et effectuer des opérations d'entrée et de sortie (E/S) lorsque vous utilisez BigQuery DataFrames. Vous apprendrez à créer et à utiliser des sessions, à travailler avec des données en mémoire, ainsi qu'à lire et à écrire dans des fichiers et des tables BigQuery.

Sessions BigQuery

BigQuery DataFrames utilise un objet de session local pour gérer les métadonnées en interne. Chaque objet DataFrame et Series se connecte à une session, chaque session se connecte à un emplacement, et chaque requête d'une session s'exécute dans l'emplacement où vous avez créé la session. Utilisez l'exemple de code suivant pour créer manuellement une session et l'utiliser pour charger des données :

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)

Vous ne pouvez pas combiner des données provenant de plusieurs instances de session, même si vous les initialisez avec les mêmes paramètres. L'exemple de code suivant montre qu'une tentative de combinaison de données provenant de différentes instances de session provoque une erreur :

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

Session globale

BigQuery DataFrames fournit une session globale par défaut à laquelle vous pouvez accéder avec la bigframes.pandas.get_global_session() méthode. Dans Colab, vous devez fournir un ID du projet pour l'attribut bigframes.pandas.options.bigquery.project avant de l'utiliser. Vous pouvez également définir un emplacement avec l bigframes.pandas.options.bigquery.location attribut, qui est défini par défaut sur la US multirégion.

L'exemple de code suivant montre comment définir des options pour la session 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

Pour réinitialiser l'emplacement ou le projet de la session globale, fermez la session actuelle en exécutant la bigframes.pandas.close_session() méthode.

De nombreuses fonctions intégrées de BigQuery DataFrames utilisent la session globale par défaut. L'exemple de code suivant montre comment les fonctions intégrées utilisent la session 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")

Données en mémoire

Vous pouvez créer des objets DataFrames et Series avec des structures de données Python ou NumPy intégrées, de la même manière que vous créez des objets avec pandas. Utilisez l'exemple de code suivant pour créer un objet :

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

Pour convertir des objets pandas en objets DataFrames à l'aide de la read_pandas() méthode ou de constructeurs, utilisez l'exemple de code suivant :

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)

Pour utiliser la méthode to_pandas() afin de charger des données BigQuery DataFrames dans votre mémoire, utilisez l'exemple de code suivant :

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

Estimation des coûts avec le paramètre dry_run

Le chargement d'une grande quantité de données peut prendre beaucoup de temps et de ressources. Pour voir la quantité de données traitées, utilisez le dry_run=True paramètre dans l' to_pandas() appel. Utilisez l'exemple de code suivant pour effectuer une simulation :

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)

Lire et écrire des fichiers

Vous pouvez lire des données à partir de fichiers compatibles dans un BigQuery DataFrames. Ces fichiers peuvent se trouver sur votre ordinateur local ou dans Cloud Storage. Utilisez l'exemple de code suivant pour lire des données à partir d'un fichier 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")

Pour enregistrer vos BigQuery DataFrames dans des fichiers locaux ou des fichiers Cloud Storage à l'aide de la méthode to_csv, utilisez l'exemple de code suivant :

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

Lire et écrire des tables BigQuery

Pour créer des BigQuery DataFrames à l'aide de références de table BigQuery et de la fonction bigframes.pandas.read_gbq, utilisez l'exemple de code suivant :

import bigframes.pandas as bpd

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

Pour utiliser une chaîne SQL avec la read_gbq() fonction afin de lire des données dans BigQuery DataFrames, utilisez l'exemple de code suivant :

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)

Pour enregistrer votre DataFrame objet dans une table BigQuery, utilisez la to_gbq() méthode de votre DataFrame objet. L'exemple de code suivant montre comment procéder :

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

Étape suivante