Manipuler des données avec BigQuery DataFrames

Ce document décrit les fonctionnalités de manipulation des données disponibles avec BigQuery DataFrames. Vous trouverez les fonctions décrites dans la bibliothèque bigframes.bigquery.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches décrites dans ce document, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Lorsque vous effectuez l'authentification d'un utilisateur final dans un environnement interactif tel qu'un notebook, un REPL Python ou la ligne de commande, BigQuery DataFrames vous invite à procéder à une authentification si nécessaire. Sinon, consultez Configurer les identifiants par défaut de l'application pour différents environnements.

API pandas

Une fonctionnalité notable de BigQuery DataFrames est que l'API bigframes.pandas est conçue pour être semblable aux API de la bibliothèque pandas. Cette conception vous permet d'utiliser des modèles de syntaxe familiers pour les tâches de manipulation de données. Les opérations définies par le biais de l'API BigQuery DataFrames sont exécutées côté serveur, en agissant directement sur les données stockées dans BigQuery. Il n'est donc pas nécessaire de transférer les ensembles de données hors de BigQuery.

Pour vérifier quelles API pandas sont compatibles avec BigQuery DataFrames, consultez API pandas compatibles.

Inspecter et manipuler des données

Vous pouvez utiliser l'API bigframes.pandas pour effectuer des opérations d'inspection et de calcul des données. L'exemple de code suivant utilise la bibliothèque bigframes.pandas pour inspecter la colonne body_mass_g, calculer la moyenne body_mass et calculer la moyenne body_mass par species :

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

Bibliothèque BigQuery

La bibliothèque BigQuery fournit des fonctions SQL BigQuery qui n'ont peut-être pas d'équivalent dans pandas. Les sections suivantes présentent quelques exemples.

Traiter les valeurs de tableau

Vous pouvez utiliser la fonction bigframes.bigquery.array_agg() dans la bibliothèque bigframes.bigquery pour agréger des valeurs après une opération groupby :

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

Vous pouvez également utiliser les fonctions de tableau array_length() et array_to_string().

Créer un objet struct Series

Vous pouvez utiliser la fonction bigframes.bigquery.struct() dans la bibliothèque bigframes.bigquery pour créer un objet Series struct avec des sous-champs pour chaque colonne d'un DataFrame :

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

Convertir des codes temporels en epochs Unix

Vous pouvez utiliser la fonction bigframes.bigquery.unix_micros() dans la bibliothèque bigframes.bigquery pour convertir les codes temporels en microsecondes Unix :

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

Vous pouvez également utiliser les fonctions temporelles unix_seconds() et unix_millis().

Utiliser la fonction scalaire SQL

Vous pouvez utiliser la fonction bigframes.bigquery.sql_scalar() dans la bibliothèque bigframes.bigquery pour accéder à une syntaxe SQL arbitraire représentant une expression à une seule colonne :

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

Étapes suivantes