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

La gestion des sessions et des opérations d'E/S dans BigQuery DataFrames vous permet de contrôler votre environnement d'exécution et de déplacer des données vers et depuis vos workflows. Vous pouvez configurer vos sessions pour contrôler l'emplacement d'exécution de vos requêtes, et effectuer des opérations d'E/S pour lire et écrire des données en mémoire, des fichiers Cloud Storage 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 les données de plusieurs instances de session, même si vous les initialisez avec les mêmes paramètres. L'exemple de code suivant montre que la tentative de combinaison de données provenant de différentes instances de session entraîne 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 méthode bigframes.pandas.get_global_session(). 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'attribut bigframes.pandas.options.bigquery.location, qui est défini par défaut sur l'emplacement multirégional US.

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 en cours en exécutant la méthode bigframes.pandas.close_session().

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 méthode ou des constructeurs read_pandas(), 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 connaître la quantité de données traitées, utilisez le paramètre dry_run=True dans l'appel to_pandas(). Utilisez l'exemple de code suivant pour effectuer 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)

Lire et écrire des fichiers

Vous pouvez lire les données de fichiers compatibles dans un DataFrame BigQuery DataFrames. Ces fichiers peuvent se trouver sur votre ordinateur local ou dans Cloud Storage. Utilisez l'exemple de code suivant pour lire les données 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 fonction read_gbq() 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 objet DataFrame dans une table BigQuery, utilisez la méthode to_gbq() de votre objet DataFrame. 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}")

Étapes suivantes