Zu BigQuery DataFrames Version 2.0 migrieren

Version 2.0 von BigQuery DataFrames bietet Verbesserungen bei Sicherheit und Leistung der BigQuery DataFrames API, fügt neue Funktionen hinzu und führt wichtige Änderungen ein. In diesem Dokument werden die Änderungen beschrieben und es werden Migrationsanleitungen bereitgestellt. Sie können diese Empfehlungen anwenden, bevor Sie die Version 2.0 installieren, 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 weniger Tabellen erstellt und die Abfragen werden schneller ausgeführt, da für allow_large_results standardmäßig False verwendet wird. Dieses Design kann die Speicherkosten senken, insbesondere wenn Sie die Abrechnung nach physischen Byte verwenden.
  • Standardmäßig verbesserte Sicherheit bei den von BigQuery DataFrames bereitgestellten Remote-Funktionen.

BigQuery DataFrames Version 2.0 installieren

Um Breaking Changes zu vermeiden, sollten Sie in Ihrer requirements.txt-Datei (z. B. bigframes==1.42.0) oder Ihrer pyproject.toml-Datei (z. B. dependencies = ["bigframes = 1.42.0"]) eine bestimmte Version von BigQuery DataFrames angeben. 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 festlegen, um Breaking Changes 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)

Decorator @remote_function verwenden

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

Schlüsselwortargumente für mehrdeutige Parameter sind erforderlich

Damit keine Werte an einen unbeabsichtigten Parameter übergeben werden, wird in BigQuery DataFrames Version 2.0 und höher die Verwendung von Schlüsselwortargumenten 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 wird für die Cloud Run-Funktionen, die von BigQuery DataFrames bereitgestellt werden, nicht mehr standardmäßig das Compute Engine-Dienstkonto verwendet. So schränken Sie die Berechtigungen der Funktion ein, 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.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 @remote_function-Dekorators auf "default" festlegen. 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 Ingress-Einstellungen der Cloud Run-Funktionen, die es bereitstellt, auf "internal-only" fest. Bisher waren die Einstellungen für den Eingang 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 bei einer Region, die regionale Dienstendpunkte und bigframes.pandas.options.bigquery.use_regional_endpoints = True nicht unterstützte, auf Standortendpunkte zurückgegriffen. In Version 2.0 von BigQuery DataFrames wird dieses Fallback-Verhalten entfernt. Wenn Sie in Version 2.0 eine Verbindung zu Standortendpunkten 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

In BigQuery DataFrames Version 2.0 wurde der Standardwert für model_name für GeminiTextGenerator auf "gemini-2.0-flash-001" aktualisiert. Es wird empfohlen, ein model_name direkt anzugeben, um Fehler zu vermeiden, wenn sich das Standardmodell in Zukunft ändert.

import bigframes.ml.llm

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

Nächste Schritte