Zu BigQuery DataFrames Version 2.0 migrieren

Version 2.0 von BigQuery DataFrames bietet Sicherheits- und Leistungsverbesserungen für die BigQuery DataFrames API, fügt neue Funktionen hinzu und führt funktionsgefährdende Änderungen ein. In diesem Dokument werden die Änderungen beschrieben und Migrationsanleitungen bereitgestellt. Sie können diese Empfehlungen vor der Installation von Version 2.0 anwenden, indem Sie die aktuelle Version 1.x von BigQuery DataFrames verwenden.

BigQuery DataFrames Version 2.0 bietet die folgenden Vorteile:

  • Wenn Sie Abfragen ausführen, die Ergebnisse an den Client zurückgeben, werden schnellere Abfragen und weniger Tabellen erstellt, da allow_large_results standardmäßig auf False gesetzt ist. Dieses Design kann die Speicherkosten senken, insbesondere wenn Sie die Abrechnung nach physischen Byte verwenden.
  • Standardmäßig verbesserte Sicherheit in den von BigQuery DataFrames bereitgestellten Remote-Funktionen.

BigQuery DataFrames Version 2.0 installieren

Um funktionsgefährdende Änderungen zu vermeiden, pinnen Sie eine bestimmte Version von BigQuery DataFrames in Ihrer requirements.txt-Datei (z. B. bigframes==1.42.0) oder Ihrer pyproject.toml-Datei (z. B. dependencies = ["bigframes = 1.42.0"]) an. Wenn Sie die neueste Version ausprobieren möchten, können Sie pip install --upgrade bigframes ausführen, um die neueste Version von BigQuery DataFrames zu installieren.

Option allow_large_results verwenden

BigQuery hat ein Limit für die maximale Antwortgröße für Abfragejobs. Ab BigQuery DataFrames-Version 2.0 wird dieses Limit standardmäßig in Methoden erzwungen, die Ergebnisse an den Client zurückgeben, z. B. peek(), to_pandas() und to_pandas_batches(). Wenn Ihr Job große Ergebnisse zurückgibt, können Sie allow_large_results in Ihrem BigQueryOptions-Objekt auf True setzen, um funktionsgefährdende Änderungen zu vermeiden. Diese Option ist in BigQuery DataFrames Version 2.0 standardmäßig auf False festgelegt.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Sie können die Option allow_large_results mit dem Parameter allow_large_results in to_pandas() und anderen Methoden überschreiben. Beispiel:

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

@remote_function-Decorator verwenden

In BigQuery DataFrames Version 2.0 wurden einige Änderungen am Standardverhalten des Decorators @remote_function vorgenommen.

Keyword-Argumente werden für mehrdeutige Parameter erzwungen

Damit Werte nicht an einen unbeabsichtigten Parameter übergeben werden, wird in BigQuery DataFrames ab Version 2.0 die Verwendung von Keyword-Argumenten für die folgenden Parameter erzwungen:

  • 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

Wenn Sie diese Parameter verwenden, geben Sie den Parameternamen an. Beispiel:

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

Dienstkonto festlegen

Ab Version 2.0 verwendet BigQuery DataFrames für die von ihm bereitgestellten Cloud Run-Funktionen nicht mehr standardmäßig das Compute Engine-Dienstkonto. So beschränken Sie die Berechtigungen der Funktion, die Sie bereitstellen:

  1. Erstellen Sie ein Dienstkonto mit minimalen Berechtigungen.
  2. Geben Sie die E-Mail-Adresse des Dienstkontos für den Parameter cloud_function_service_account des Decorators @remote_function an.

Beispiel:

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

Wenn Sie das Compute Engine-Dienstkonto verwenden möchten, können Sie den Parameter cloud_function_service_account des Decorators @remote_function auf "default" setzen. Beispiel:

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

Einstellungen für eingehenden Traffic festlegen

Ab Version 2.0 legt BigQuery DataFrames die Einstellungen für eingehenden Traffic der Cloud Run-Funktionen, die bereitgestellt werden, auf "internal-only" fest. Bisher waren die Einstellungen für eingehenden Traffic standardmäßig auf "all" festgelegt. Sie können die Einstellungen für eingehenden Traffic ändern, indem Sie den Parameter cloud_function_ingress_settings des Decorators @remote_function festlegen. Beispiel:

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

Benutzerdefinierte Endpunkte verwenden

In BigQuery DataFrames-Versionen vor 2.0 wurde auf Standortendpunkte zurückgegriffen, wenn eine Region keine regionalen Dienstendpunkte und bigframes.pandas.options.bigquery.use_regional_endpoints = True unterstützte. In Version 2.0 von BigQuery DataFrames wird dieses Fallback-Verhalten entfernt. Wenn Sie in Version 2.0 eine Verbindung zu standortbezogenen Endpunkten herstellen möchten, legen Sie die Option bigframes.pandas.options.bigquery.client_endpoints_override fest. Beispiel:

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

Ersetzen Sie LOCATION durch den Namen des BigQuery-Standorts, zu dem Sie eine Verbindung herstellen möchten.

bigframes.ml.llm-Modul verwenden

Es wird empfohlen, direkt ein unterstütztes model_name anzugeben (z. B. "gemini-3.5-flash"), um Fehler zu vermeiden, falls sich das Standardmodell in Zukunft ändert.

import bigframes.ml.llm

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

Nächste Schritte