Utiliser BigQuery DataFrames

BigQuery DataFrames fournit un DataFrame en Python et une API de machine learning (ML) basés sur le moteur BigQuery. BigQuery DataFrames est un package Open Source. Vous pouvez exécuter pip install --upgrade bigframes pour installer la dernière version.

BigQuery DataFrames fournit deux bibliothèques :

  • bigframes.pandas, qui fournit une API compatible avec Pandas pour les données analytiques.

  • bigframes.ml, qui fournit une API de type scikit-learn pour le machine learning (ML).

Autorisations requises

Options

Après l'installation, vous devez spécifier l'emplacement et le projet dans lesquels vous souhaitez utiliser BigQuery DataFrames. Vous pouvez définir l'emplacement et le projet dans votre notebook de la manière suivante : 
import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dec"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

Si bf.options.bigquery.project n'est pas défini, la variable d'environnement $GOOGLE_CLOUD_PROJECT est utilisée. Elle est définie dans l'environnement d'exécution de notebook diffusant les notebooks BigQuery Studio et Vertex AI.

Emplacement de traitement des données

BigQuery DataFrames est conçu pour évoluer, ce qui permet de conserver les données et le traitement sur le service BigQuery. Toutefois, vous pouvez importer des données dans la mémoire de votre machine cliente en appelant .to_pandas() sur un objet DataFrame ou Series. Si vous choisissez cette solution, la limite de mémoire de votre machine cliente s'applique.

Lieu de la séance

BigQuery DataFrames utilise un objet de session local pour gérer les métadonnées en interne. Cette session est liée à un emplacement. BigQuery DataFrames utilise l'emplacement multirégional US comme emplacement par défaut, mais vous pouvez utiliser session_options.location pour définir un autre emplacement. Chaque requête d'une session est exécutée dans l'emplacement où la session a été créée. BigQuery DataFrames renseigne automatiquement bf.options.bigquery.location avec l'emplacement de la table si l'utilisateur commence par read_gbq/read_gbq_table/read_gbq_query() et spécifie une table, directement ou dans une instruction SQL.

Si vous souhaitez réinitialiser l'emplacement des objets DataFrame ou Series créés, vous pouvez fermer la session en exécutant bigframes.pandas.close_session(). Vous pouvez ensuite réutiliser bigframes.pandas.options.bigquery.location pour spécifier un autre emplacement.

read_gbq() nécessite de spécifier un emplacement si l'ensemble de données que vous interrogez ne se trouve pas dans l'emplacement multirégional US. Si vous essayez de lire une table à partir d'un autre emplacement, vous obtenez une exception NotFound.

Types de données

Les objets BigQuery DataFrames acceptent les dtypes numpy et pandas suivants :

BigQuery Objets BigQuery DataFrames et pandas
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

Soutenu par to_pandas() only
INT64 pandas.Int64Dtype()
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

BigQuery DataFrames n'accepte pas les types de données BigQuery suivants :

  • ARRAY

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

  • JSON

Tous les autres types de données BigQuery s'affichent en tant que type d'objet.

Utiliser la bibliothèque bigframes.pandas

La bibliothèque bigframes.pandas fournit une API de type pandas que vous pouvez utiliser pour analyser et manipuler des données dans BigQuery. L'API bigframes.pandas est évolutive pour traiter des téraoctets de données BigQuery et utilise le moteur de requête BigQuery pour effectuer les calculs.
L'API bigframes.pandas offre les fonctionnalités suivantes :

Entrées et sorties

Vous pouvez accéder aux données à partir de diverses sources, y compris les fichiers CSV locaux, les fichiers Cloud Storage, les objets DataFrames pandas, les modèles et les fonctions BigQuery, puis les charger dans un DataFrame BigQuery DataFrames. Vous pouvez également créer des tables BigQuery à partir de BigQuery DataFrames.

Manipulation de données

Vous pouvez utiliser Python au lieu de SQL pour votre développement. Vous pouvez développer toutes les manipulations de données BigQuery en Python, ce qui vous évite de devoir basculer d'un langage à l'autre et d'essayer de capturer des instructions SQL sous forme de chaînes de texte. L'API bigframes.pandas propose plus de 750 fonctions pandas.

Écosystème et visualisations Python

L'API bigframes.pandas est une passerelle vers l'écosystème complet d'outils Python. L'API accepte les opérations statistiques avancées et vous pouvez visualiser les agrégations générées à partir de BigQuery DataFrames. Vous pouvez également passer d'un DataFrame BigQuery DataFrames à un DataFrame pandas avec des opérations d'échantillonnage intégrées.

Fonctions Python personnalisées

BigQuery DataFrames vous permet de transformer vos fonctions scalaires personnalisées en fonctions distantes BigQuery. La création d'une fonction distante dans BigQuery DataFrames crée :

  1. une fonction Cloud Functions (2nd gen) ;

  2. une connexion BigQuery. Par défaut, une connexion nommée bigframes-default-connection est utilisée. Vous pouvez utiliser une connexion BigQuery préconfigurée si vous le souhaitez, auquel cas la création de la connexion est ignorée.

    Le compte de service pour la connexion par défaut se voit attribuer le rôle IAM Demandeur Cloud Run (roles/run.invoker).

  3. Une fonction distante BigQuery qui exploite la fonction Cloud (1) via la connexion BigQuery (2).

Pour obtenir un exemple, consultez la section Créer une fonction distante.

Les connexions BigQuery sont créées au même emplacement que la session BigQuery DataFrames, en utilisant le nom que vous indiquez dans la définition de la fonction personnalisée. Pour afficher et gérer les connexions, procédez comme suit :

  1. Accédez à BigQuery dans la console Google Cloud.

  2. Sélectionnez le projet dans lequel vous avez créé la fonction distante.

  3. Dans le volet "Explorateur", développez ce projet, puis développez "Connexions externes".

Les fonctions distantes BigQuery sont créées dans l'ensemble de données que vous spécifiez ou dans un type spécial d'ensemble de données masqué appelé dans le code comme un ensemble de données anonyme. Pour afficher et gérer les fonctions distantes créées dans un ensemble de données fourni par l'utilisateur, procédez comme suit :

  1. Accédez à BigQuery dans la console Google Cloud.

  2. Sélectionnez le projet dans lequel vous avez créé la fonction distante.

  3. Dans le volet "Explorateur", développez le projet, l'ensemble de données dans lequel vous avez créé la fonction distante, puis développez les routines.

Pour afficher et gérer les fonctions Cloud Functions, accédez à la page Fonctions et utilisez l'outil de sélection de projets pour sélectionner le projet dans lequel vous avez créé la fonction. Pour faciliter l'identification, les noms des fonctions créées par BigQuery DataFrames comportent le préfixe bigframes.

Conditions requises

Pour utiliser les fonctions distantes BigQuery DataFrames, vous devez activer les API suivantes :

Pour utiliser les fonctions distantes BigQuery DataFrames, vous devez disposer des rôles IAM suivants dans le projet :

  • Éditeur de données BigQuery (roles/bigquery.dataEditor)

  • Administrateur BigQuery Connection (roles/bigquery.connectionAdmin)

  • Développeur Cloud Functions (roles/cloudfunctions.developer)

  • Utilisateur du compte de service (roles/iam.serviceAccountUser)

  • Lecteur des objets Storage (roles/storage.objectViewer)

  • Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin) si vous utilisez la connexion BigQuery par défaut, ou Navigateur (rôles/navigateur) si vous utilisez une connexion préconfigurée. Cette exigence peut être évitée en définissant l'option bigframes.pandas.options.bigquery.skip_bq_connection_check sur True, auquel cas la connexion (par défaut ou préconfigurée) serait utilisée telle quelle, sans aucune vérification d'existence ni d'autorisation. Si vous utilisez la connexion préconfigurée et que vous ignorez la vérification des connexions, assurez-vous que la connexion est créée au bon endroit et que son compte de service dispose du rôle de demandeur Cloud Run (roles/run.invoker) pour le projet.

Limites

  • Les fonctions distantes sont disponibles en environ 90 secondes lorsque vous les créez.

  • Les modifications triviales dans le notebook, telles que l'insertion d'une nouvelle cellule ou le changement de nom d'une variable, peuvent entraîner la recréation de la fonction distante, même si ces modifications ne sont pas liées au code de la fonction distante.

  • BigQuery DataFrames ne différencie pas les données à caractère personnel que vous incluez dans le code de la fonction distante. Le code de la fonction distante est sérialisé en tant que cadre opaque pour le déployer en tant que fonction Cloud Functions.

  • Les fonctions Cloud Functions (2nd gen), les connexions BigQuery et les fonctions distantes BigQuery créées par BigQuery DataFrames persistent dans Google Cloud. Si vous ne souhaitez pas conserver ces ressources, vous devez les supprimer séparément à l'aide d'une interface Cloud Functions ou BigQuery appropriée.

  • Un projet peut contenir jusqu'à 1 000 fonctions Cloud Functions (2nd gen) à la fois. Pour connaître toutes les limites, consultez la page Quotas de Cloud Functions.

Exemples d'instructions bigframes.pandas

Les exemples suivants illustrent des méthodes courantes pour utiliser bigframes.pandas.

Charger des données à partir d'une table ou d'une requête BigQuery

Vous pouvez créer un DataFrame à partir d'une table ou d'une requête BigQuery de la manière suivante :

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

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

Charger des données à partir d'un fichier CSV

Vous pouvez créer un DataFrame à partir d'un fichier CSV local ou Cloud Storage de la manière suivante :

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

Inspecter et manipuler des données

Vous pouvez utiliser bigframes.pandas pour effectuer des opérations d'inspection et de calcul de données.
L'exemple de code suivant montre comment utiliser 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)
)

Utiliser la bibliothèque bigframes.ml

Les fonctionnalités de ML de BigQuery DataFrames vous permettent de prétraiter les données, puis d'entraîner des modèles sur ces données. Vous pouvez également associer ces actions pour créer des pipelines de données.

Emplacements de ML

bigframes.ml accepte les mêmes emplacements que BigQuery ML. La prédiction de modèle BigQuery ML et d'autres fonctions de ML sont acceptées dans toutes les régions BigQuery. La compatibilité de l'entraînement de modèle varie selon les régions. Pour en savoir plus, consultez la page Emplacements BigQuery ML.

Procéder au prétraitement des données

Créez des transformateurs pour préparer les données à utiliser dans des estimateurs (modèles) à l'aide des modules bigframes.ml.preprocessing et bigframes.ml.compose. BigQuery DataFrames propose les transformations suivantes :

  • Utilisez la classe KBinsDiscretizer dans le module bigframes.ml.preprocessing pour regrouper des données continues en intervalles.

  • Utilisez la classe LabelEncoder dans le module bigframes.ml.preprocessing pour normaliser les étiquettes cibles sous forme de valeurs entières.

  • Utilisez la classe MaxAbsScaler dans le module bigframes.ml.preprocessing pour mettre à l'échelle chaque caractéristique dans la plage [-1, 1] en fonction de sa valeur absolue maximale.

  • Utilisez la classe MinMaxScaler dans le module bigframes.ml.preprocessing pour standardiser les caractéristiques en effectuant le scaling de chaque caractéristique dans la plage [0, 1].

  • Utilisez la classe StandardScaler dans le module bigframes.ml.preprocessing pour normaliser les caractéristiques en supprimant la moyenne et en effectuant un scaling vers la variance unitaire.

  • Utilisez la classe OneHotEncoder dans le module bigframes.ml.preprocessing pour convertir les valeurs catégorielles au format numérique.

  • Utilisez la classe ColumnTransformer dans le module bigframes.ml.compose pour appliquer des transformateurs aux colonnes DataFrames.

Entraîner des modèles

Créer des estimateurs pour entraîner des modèles dans BigQuery DataFrames.

Modèles de clustering

Créez des estimateurs pour les modèles de clustering à l'aide du module bigframes.ml.cluster.

  • Utilisez la classe KMeans pour créer des modèles de clustering en k-moyennes. Utilisez ces modèles pour la segmentation des données. Par exemple, identifier des segments de clientèle. Les k-moyennes étant une technique d'apprentissage non supervisée, l'entraînement ou l'évaluation du modèle ne nécessitent pas d'étiquettes ni de données fractionnées.

Vous pouvez utiliser le module bigframes.ml.cluster pour créer des estimateurs pour les modèles de clustering.

L'exemple de code suivant montre comment utiliser la classe bigframes.ml.cluster KMeans pour créer un modèle de clustering en k-moyennes pour la segmentation des données :

from bigframes.ml.cluster import KMeans
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 the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

Modèles de décomposition

Créez des estimateurs pour les modèles de décomposition à l'aide du module bigframes.ml.decomposition.

  • Utilisez la classe d'analyse des composants principaux pour créer des modèles d'analyse des composants principaux. Utilisez ces modèles pour calculer les composants principaux et les utiliser afin d'effectuer un changement de base sur les données. Cela permet de réduire la dimensionnalité en ne projetant chaque point de données que sur les premiers composants principaux afin d'obtenir des données de dimension inférieure tout en conservant autant que possible les variations de données.

Modèles ensemblistes

Créez des estimateurs pour les modèles d'ensemble à l'aide du module bigframes.ml.ensemble.

  • Utilisez la classe RandomForestClassifier pour créer des modèles de classificateur de forêt d'arbres décisionnels. Utilisez ces modèles pour créer plusieurs arbres de décision de la méthode d'apprentissage à des fins de classification.

  • Utilisez la classe RandomForestRegressor pour créer des modèles de régression de forêt d'arbres décisionnels. Utilisez ces modèles pour créer plusieurs arbres de décision de la méthode d'apprentissage pour la régression.

  • Utilisez la classe XGBClassifier pour créer des modèles de classificateur d'arbre de décision à boosting de gradient. Utilisez ces modèles pour créer de manière additive plusieurs arbres de décision de la méthode d'apprentissage à des fins de classification.

  • Utilisez la classe XGBRegressor pour créer des modèles de régression d'arbre de décision à boosting de gradient. Utilisez ces modèles pour créer de manière additive plusieurs arbres de décision de la méthode d'apprentissage pour la régression.

Modèles de prévision

Créez des estimateurs pour les modèles de prévision à l'aide du module bigframes.ml.forecasting.

  • Utilisez la classe ARIMAPlus pour créer des modèles de prévision de séries temporelles.

Modèles importés

Créez des estimateurs pour les modèles importés à l'aide du module bigframes.ml.imported.

Modèles linéaires

Créez des estimateurs pour les modèles linéaires à l'aide du module bigframes.ml.linear_model.

  • Utilisez la classe LinearRegression pour créer des modèles de régression linéaire. Utilisez ces modèles pour effectuer des prévisions. Par exemple, prévoir les ventes d'un article un jour donné.

  • Utilisez la classe LogisticRegression pour créer des modèles de régression logistique. Utilisez ces modèles pour classer au moins deux valeurs possibles (par exemple, si une entrée est low-value, medium-value ou high-value).

L'exemple de code suivant montre comment utiliser bigframes.ml pour effectuer les opérations suivantes :

  • Charger des données à partir de BigQuery
  • Nettoyer et préparer les données d'entraînement
  • Créer et appliquer un modèle de régression bigframes.ml.LinearRegression
from bigframes.ml.linear_model import LinearRegression
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)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

Grands modèles de langage

Créez des estimateurs pour les LLM à l'aide du module bigframes.ml.llm.

  • Utilisez la classe GeminiTextGenerator pour créer des modèles de générateur de texte Gemini. Utilisez ces modèles pour les tâches de génération de texte.

  • Utilisez la classe PaLM2TextGenerator pour créer des modèles de générateur de texte PaLM2. Utilisez ces modèles pour les tâches de génération de texte.

  • Utilisez la classe PaLM2TextEmbeddingGenerator pour créer des modèles de générateur de représentations vectorielles continues de texte PaLM2. Utilisez ces modèles pour les tâches de génération de représentations vectorielles continues de texte.

Vous pouvez utiliser le module bigframes.ml.llm pour créer des estimateurs pour les grands modèles de langage (LLM) distants.
L'exemple de code suivant montre comment utiliser la classe GeminiTextGenerator bigframes.ml.llm pour créer un modèle Gemini pour la génération de code :

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(session=session, connection_name=connection)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

Modèles distants

Pour utiliser des modèles distants de DataFrame BigQuery ML (bigframes.ml.remote ou bigframes.ml.llm), vous devez activer les API suivantes :

Vous devez également disposer des rôles IAM suivants sur le projet :

  • Administrateur BigQuery Connection (roles/bigquery.connectionAdmin)
  • Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin) si vous utilisez la connexion BigQuery par défaut, ou Navigateur (rôles/navigateur) si vous utilisez une connexion préconfigurée. Cette exigence peut être évitée en définissant l'option bigframes.pandas.options.bigquery.skip_bq_connection_check sur True, auquel cas la connexion (par défaut ou préconfigurée) serait utilisée telle quelle, sans aucune vérification d'existence ni d'autorisation. Si vous utilisez la connexion préconfigurée et que vous ignorez la vérification de connexion, assurez-vous que la connexion est créée au bon endroit et que son compte de service dispose du rôle Utilisateur Vertex AI (roles/aiplatform.user) sur le projet.

La création d'un modèle distant dans BigQuery DataFrames crée une connexion BigQuery. Par défaut, une connexion nommée bigframes-default-connection est utilisée. Vous pouvez utiliser une connexion BigQuery préconfigurée si vous le souhaitez, auquel cas la création de la connexion est ignorée. Le compte de service de la connexion par défaut se voit attribuer le rôle IAM Utilisateur Vertex AI (roles/aiplatform.user).

Créer des pipelines

Créez des pipelines de ML à l'aide du module bigframes.ml.pipeline. Les pipelines vous permettent d'assembler plusieurs étapes de ML à valider de manière croisée tout en définissant différents paramètres. Cela simplifie votre code et vous permet de déployer ensemble les étapes de prétraitement des données et un estimateur.

Utilisez la classe Pipeline pour créer un pipeline de transformations avec un estimateur final.

Étapes suivantes