Migrer vers BigQuery DataFrames 2.0

Le 16 avril 2025, l'équipe BigQuery DataFrames prévoit de publier la version 2.0 de BigQuery DataFrames. Cette version améliore la sécurité et les performances de l'API BigQuery DataFrames, et ajoute de nouvelles fonctionnalités. Ce document décrit les modifications et fournit des conseils de migration. Vous pouvez appliquer ces recommandations avant la sortie en utilisant la dernière version 1.x de BigQuery DataFrames ou en installant des versions préliminaires du package 2.0.

Installer la version 2.0 de BigQuery DataFrames

Pour éviter les modifications non compatibles, épinglez une version spécifique de BigQuery DataFrames dans votre fichier requirements.txt (par exemple, bigframes==1.38.0) ou votre fichier pyproject.toml (par exemple, dependencies = ["bigframes = 1.38.0"]). Lorsque vous êtes prêt à essayer la dernière version, vous pouvez exécuter pip install --upgrade bigframes pour installer la dernière version de BigQuery DataFrames.

Utiliser l'option allow_large_results

BigQuery applique une limite de taille de réponse maximale aux tâches de requête. À partir de la version 2.0 de BigQuery DataFrames, cette limite est appliquée par défaut dans les méthodes qui renvoient des résultats au client, telles que peek(), to_pandas() et to_pandas_batches(). Si votre tâche renvoie des résultats volumineux, vous pouvez définir allow_large_results sur True dans votre objet BigQueryOptions pour éviter de casser les modifications. Cette option est définie sur False par défaut dans BigQuery DataFrames version 2.0.


  import bigframes.pandas as bpd

  bpd.options.bigquery.allow_large_results = True

Vous pouvez remplacer l'option allow_large_results à l'aide du paramètre allow_large_results dans to_pandas() et d'autres méthodes. Exemple :


  bf_df = bpd.read_gbq(query)
  # ... other operations on bf_df ...
  pandas_df = bf_df.to_pandas(allow_large_results=True)

Utiliser le décorateur @remote_function

La version 2.0 de BigQuery DataFrames apporte quelques modifications au comportement par défaut du décorateur @remote_function.

Définir un compte de service

À partir de la version 2.0, BigQuery DataFrames n'utilise plus le compte de service Compute Engine par défaut pour les fonctions Cloud Run qu'il déploie. Pour limiter les autorisations de la fonction que vous déployez :

  1. Créez un compte de service avec des autorisations minimales.
  2. Fournissez ensuite l'adresse e-mail du compte de service au paramètre cloud_function_service_account du décorateur @remote_function.

Exemple :


  @remote_function(
    cloud_function_service_account="my-service-account@my-project.iam.gserviceaccount.com",
    ...
  )
  def my_remote_function(parameter: int) -> str:
    return str(parameter)

Si vous souhaitez utiliser le compte de service Compute Engine, vous pouvez définir le paramètre cloud_function_service_account du décorateur @remote_function sur "default". Exemple :


  # This usage is discouraged. Use only if you have a specific reason to use the
  # default Compute Engine service account.
  @remote_function(cloud_function_service_account="default", ...)
  def my_remote_function(parameter: int) -> str:
    return str(parameter)

Définir les paramètres d'entrée

À partir de la version 2.0, BigQuery DataFrames définit les paramètres d'entrée des fonctions Cloud Run qu'il déploie sur "internal-only". Auparavant, les paramètres d'entrée étaient définis sur "all" par défaut. Vous pouvez modifier les paramètres d'entrée en définissant le paramètre cloud_function_ingress_settings du décorateur @remote_function. Exemple :


  @remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
  def my_remote_function(parameter: int) -> str:
    return str(parameter)

Utiliser des points de terminaison personnalisés

Auparavant, si une région n'était pas compatible avec les points de terminaison de service régionaux et bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames revenait aux points de terminaison géographiques. La version 2.0 de BigQuery DataFrames supprime ce comportement de remplacement. Pour vous connecter aux points de terminaison géographiques dans la version 2.0, définissez l'option bigframes.pandas.options.bigquery.client_endpoints_override. Exemple :


import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

Remplacez LOCATION par le nom de l'emplacement BigQuery auquel vous souhaitez vous connecter.

Utiliser le mode de tri partiel

Avec la version 2.0 de BigQuery DataFrames, le mode de tri partiel est disponible pour tous les utilisateurs, mais il n'est pas activé par défaut. Pour utiliser le tri partiel, définissez ordering_mode sur partial avant d'effectuer toute autre opération avec BigQuery DataFrames, comme illustré dans l'exemple de code suivant:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Ce mode génère des requêtes plus efficaces dans la plupart des cas et des requêtes identiques dans d'autres, comme celles qui utilisent la fonction groupby(). Certaines fonctions compatibles avec pandas qui nécessitent un tri, comme .iloc[row_index], ne sont pas compatibles avec le mode de tri partiel. Pour en savoir plus, consultez la section Mode d'ordonnancement partiel.

Étape suivante