Migrer vers BigQuery DataFrames version 2.0

La version 2.0 de BigQuery DataFrames apporte des améliorations de sécurité et de performances à l'API BigQuery DataFrames, ajoute de nouvelles fonctionnalités et introduit des modifications destructives. 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 offre 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 en octets physiques.
  • Amélioration de la sécurité 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 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 jobs 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 job renvoie des résultats volumineux, vous pouvez définir allow_large_results sur True dans votre objet BigQueryOptions pour éviter les modifications destructives. 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.

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 ultérieures applique 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 le nom du paramètre. Exemple :

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

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

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

Exemple :

@remote_function(
  cloud_function_service_account="my-service-account@my-project.s3ns.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 à la version 2.0, 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 utilisait des points de terminaison d'emplacement. La version 2.0 de BigQuery DataFrames supprime ce comportement de remplacement. Pour vous connecter à des 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 module bigframes.ml.llm

Nous vous recommandons de fournir directement un model_name compatible (tel que "gemini-3.5-flash") pour éviter les interruptions si le modèle par défaut change à l'avenir.

import bigframes.ml.llm

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

Étapes suivantes