Eseguire la migrazione a BigQuery DataFrames 2.0

Il 16 aprile 2025, il team di BigQuery DataFrames prevede di rilasciare la versione 2.0 di BigQuery DataFrames. Questa versione apporta miglioramenti alla sicurezza e alle prestazioni dell'API BigQuery DataFrames e aggiunge nuove funzionalità. Questo documento descrive le modifiche e fornisce indicazioni per la migrazione. Puoi applicare questi consigli prima della release utilizzando la versione 1.x più recente di BigQuery DataFrames o installando le versioni pre-release del pacchetto 2.0.

Installa BigQuery DataFrames versione 2.0

Per evitare modifiche che causano interruzioni, esegui il pinning a una versione specifica di BigQuery DataFrames nel file requirements.txt (ad esempio bigframes==1.38.0) o nel file pyproject.toml (ad esempio dependencies = ["bigframes = 1.38.0"]). Quando è tutto pronto per provare la versione più recente, puoi eseguire pip install --upgrade bigframes per installare la versione più recente di BigQuery DataFrames.

Utilizza l'opzione allow_large_results

BigQuery ha un limite di dimensione massima della risposta per i job di query. A partire dalla versione 2.0 di BigQuery DataFrames, BigQuery DataFrames applica questo limite per impostazione predefinita nei metodi che restituiscono risultati al client, ad esempio peek(), to_pandas() e to_pandas_batches(). Se il job restituisce risultati di grandi dimensioni, puoi impostare allow_large_results su True nell'oggetto BigQueryOptions per evitare modifiche che causano interruzioni. Questa opzione è impostata su False per impostazione predefinita nella versione 2.0 di BigQuery DataFrames.


  import bigframes.pandas as bpd

  bpd.options.bigquery.allow_large_results = True

Puoi ignorare l'opzione allow_large_results utilizzando il parametro allow_large_results in to_pandas() e in altri metodi. Ad esempio:


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

Utilizzare il decoratore @remote_function

La versione 2.0 di BigQuery DataFrames apporta alcune modifiche al comportamento predefinito del decoratore @remote_function.

Impostare un account di servizio

A partire dalla versione 2.0, i dataframe BigQuery non utilizzano più per impostazione predefinita l'account di servizio Compute Engine per le funzioni Cloud Run di cui eseguono il deployment. Per limitare le autorizzazioni della funzione di cui esegui il deployment:

  1. Crea un account di servizio con autorizzazioni minime.
  2. Poi, fornisci l'indirizzo email dell'account di servizio al parametro cloud_function_service_account del decoratore @remote_function.

Ad esempio:


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

Se vuoi utilizzare l'account di servizio Compute Engine, puoi impostare il parametro cloud_function_service_account del decoratore @remote_function su "default". Ad esempio:


  # 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)

Impostare le impostazioni di importazione

A partire dalla versione 2.0, BigQuery DataFrames imposta le impostazioni di ingresso delle funzioni Cloud Run di cui esegue il deployment"internal-only". In precedenza, le impostazioni di ingresso erano impostate su "all" per impostazione predefinita. Puoi modificare le impostazioni di importazione impostando il parametro cloud_function_ingress_settings del decoratore @remote_function. Ad esempio:


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

Utilizza endpoint personalizzati

In precedenza, se una regione non supportava gli endpoint di servizio regionale e bigframes.pandas.options.bigquery.use_regional_endpoints = True, i DataFrame di BigQuery utilizzavano gli endpoint di località. La versione 2.0 di BigQuery DataFrames rimuove questo comportamento di riserva. Per collegarti agli endpoint posizione nella versione 2.0, imposta l'opzione bigframes.pandas.options.bigquery.client_endpoints_override. Ad esempio:


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",
}

Sostituisci LOCATION con il nome della località BigQuery a cui vuoi connetterti.

Utilizzare la modalità di ordinamento parziale

Con la versione 2.0 di BigQuery DataFrames, la modalità di ordinamento parziale è disponibile a livello generale, ma non è abilitata per impostazione predefinita. Per utilizzare l'ordinamento parziale, imposta ordering_mode su partial prima di eseguire qualsiasi altra operazione con BigQuery DataFrames, come mostrato nel seguente esempio di codice:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Questa modalità genera query più efficienti nella maggior parte dei casi e query identiche in altri, ad esempio quelle che utilizzano la funzione groupby(). Alcune funzioni compatibili con pandas che richiedono l'ordinamento, come .iloc[row_index], non sono supportate in modalità di ordinamento parziale. Per ulteriori informazioni, consulta la sezione Modalità di ordinamento parziale.

Passaggi successivi