Migrer vers BigQuery DataFrames version 2.0

La version 2.0 de BigQuery DataFrames apporte des améliorations en termes de sécurité et de performances à l'API BigQuery DataFrames, ajoute de nouvelles fonctionnalités et introduit des modifications incompatibles. Ce document décrit les modifications et fournit des conseils de migration. Vous pouvez appliquer ces recommandations avant d'installer la version 2.0 en utilisant la dernière version 1.x de BigQuery DataFrames.

BigQuery DataFrames version 2.0 présente les avantages suivants :

  • Les requêtes sont plus rapides et moins de tables sont créées lorsque vous exécutez des requêtes qui renvoient des résultats au client, car allow_large_results est défini par défaut sur False. Cette conception peut réduire les coûts de stockage, en particulier si vous utilisez la facturation par octet physique.
  • Sécurité améliorée par défaut dans les fonctions distantes déployées par BigQuery DataFrames.

Installer BigQuery DataFrames version 2.0

Pour éviter les modifications destructives, épinglez une version spécifique de BigQuery DataFrames dans votre fichier requirements.txt (par exemple, bigframes==1.42.0) ou dans votre fichier pyproject.toml (par exemple, dependencies = ["bigframes = 1.42.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 pour les tâches de requête. À partir de la version 2.0 de BigQuery DataFrames, BigQuery DataFrames applique cette limite 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 les modifications incompatibles. 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 en utilisant le 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.

Les arguments de mots clés sont appliqués pour les paramètres ambigus

Pour éviter de transmettre des valeurs à un paramètre non prévu, BigQuery DataFrames version 2.0 et versions ultérieures imposent l'utilisation d'arguments de mot clé pour les paramètres suivants :

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

Lorsque vous utilisez ces paramètres, indiquez leur nom. Exemple :

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Définir un compte de service

Depuis 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, procédez comme suit :

  1. Créez un compte de service avec des autorisations minimales.
  2. Fournissez 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

Dans les versions de BigQuery DataFrames antérieures à 2.0, si une région n'acceptait pas 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 secours. Pour vous connecter aux points de terminaison de localisation 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 module bigframes.ml.llm

Dans la version 2.0 de BigQuery DataFrames, la model_name par défaut pour GeminiTextGenerator a été remplacée par "gemini-2.0-flash-001". Nous vous recommandons de fournir un model_name directement pour éviter les problèmes si le modèle par défaut change à l'avenir.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

Étapes suivantes