Migrate to BigQuery DataFrames version 2.0

Version 2.0 of BigQuery DataFrames makes security and performance improvementsto the BigQuery DataFrames API, adds new features, and introducesbreaking changes. This document describes the changes and provides migrationguidance. You can apply these recommendations before installing the 2.0 versionby using the latest version 1.x of BigQuery DataFrames.

BigQuery DataFrames version 2.0 has the following benefits:

• Faster queries and fewer tables are created when you run queries that returnresults to the client, becauseallow_large_results defaults toFalse. This designcan reduce storage costs, especially if you use physical bytes billing.
• Improved security by default in the remote functions deployed byBigQuery DataFrames.

Install BigQuery DataFrames version 2.0

To avoid breaking changes, pin to a specific version ofBigQuery DataFrames in yourrequirements.txt file (for example,bigframes==1.42.0) or yourpyproject.toml file (for example,dependencies = ["bigframes = 1.42.0"]). When you're ready to try the latestversion, you can runpip install --upgrade bigframes to install the latestversion of BigQuery DataFrames.

Use theallow_large_results option

BigQuery has amaximum response size limit for query jobs.Starting in BigQuery DataFrames version 2.0, BigQuery DataFramesenforces this limit by default in methods that return results to the client,such aspeek(),to_pandas(), andto_pandas_batches(). If your job returnslarge results, you can setallow_large_results toTrue in yourBigQueryOptions object to avoid breaking changes. This option is set toFalse by default in BigQuery DataFrames version 2.0.

importbigframes.pandasasbpdbpd.options.bigquery.allow_large_results=True

You can override theallow_large_results option by using theallow_large_results parameter into_pandas() and other methods. For example:

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

Use the@remote_function decorator

BigQuery DataFrames version 2.0 makes some changes to the defaultbehavior of the@remote_function decorator.

Keyword arguments are enforced for ambiguous parameters

To prevent passing values to an unintended parameter,BigQuery DataFrames version 2.0 and beyond enforces the use of keywordarguments for the following parameters:

• 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

When using these parameters, supply the parameter name. For example:

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

Set a service account

As of version 2.0, BigQuery DataFrames no longer uses theCompute Engine service account by default for the Cloud Run functionsit deploys. To limit the permissions of the function that you deploy, do thefollowing:

1. Create a service accountwith minimal permissions.
2. Supply the service account email to thecloud_function_service_accountparameter of the@remote_function decorator.

For example:

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

If you would like to use the Compute Engine service account, you can set thecloud_function_service_account parameter of the@remote_function decoratorto"default". For example:

# 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",...)defmy_remote_function(parameter:int)->str:returnstr(parameter)

Set ingress settings

As of version 2.0, BigQuery DataFrames sets theingress settings of the Cloud Run functions itdeploys to"internal-only". Previously, the ingress settings were set to"all" by default. You can change the ingress settings by setting thecloud_function_ingress_settings parameter of the@remote_function decorator.For example:

@remote_function(cloud_function_ingress_settings="internal-and-gclb",...)defmy_remote_function(parameter:int)->str:returnstr(parameter)

Use custom endpoints

In BigQuery DataFrames versions earlier than 2.0, if a region didn'tsupportregional service endpoints andbigframes.pandas.options.bigquery.use_regional_endpoints = True, thenBigQuery DataFrames would fall back tolocational endpoints. Version 2.0 ofBigQuery DataFrames removes this fallback behavior. To connect tolocational endpoints in version 2.0, set thebigframes.pandas.options.bigquery.client_endpoints_override option. Forexample:

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

ReplaceLOCATION with the name of the BigQuerylocation that you want to connect to.

Use thebigframes.ml.llm module

In BigQuery DataFrames version 2.0, the defaultmodel_name forGeminiTextGenerator has been updated to"gemini-2.0-flash-001". It isrecommended that you supply amodel_name directly to avoid breakages if thedefault model changes in the future.

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

What's next

• Learn how tovisualize graphs using BigQuery DataFrames.
• Learn how togenerate BigQuery DataFrames code with Gemini.
• Learn how toanalyze package downloads from PyPI with BigQuery DataFrames.
• View BigQuery DataFramessource code,sample notebooks, andsampleson GitHub.
• Explore theBigQuery DataFrames API reference.