Zu BigQuery DataFrames 2.0 migrieren

Am 16. April 2025 wird das BigQuery DataFrames-Team Version 2.0 von BigQuery DataFrames veröffentlichen. Diese Version enthält Sicherheits- und Leistungsverbesserungen für die BigQuery DataFrames API sowie neue Funktionen. In diesem Dokument werden die Änderungen beschrieben und es werden Migrationshinweise gegeben. Sie können diese Empfehlungen vor der Veröffentlichung anwenden, indem Sie die neueste Version 1.x von BigQuery DataFrames verwenden oder Vorabversionen des Pakets 2.0 installieren.

BigQuery DataFrames Version 2.0 installieren

Um Unterbrechungen zu vermeiden, können Sie in Ihrer requirements.txt-Datei (z. B. bigframes==1.38.0) oder pyproject.toml-Datei (z. B. dependencies = ["bigframes = 1.38.0"]) eine bestimmte Version von BigQuery DataFrames anpinnen. 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 BigQuery DataFrames-Methoden erzwungen, die Ergebnisse an den Client zurückgeben, z. B. peek(), to_pandas() und to_pandas_batches(). Wenn Ihr Job viele Ergebnisse zurückgibt, können Sie allow_large_results in Ihrem BigQueryOptions-Objekt auf True festlegen, um fehlerhafte Änderungen zu vermeiden. In BigQuery DataFrames Version 2.0 ist diese Option 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 überschreiben, indem Sie den Parameter allow_large_results in to_pandas() und anderen Methoden verwenden. 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 @remote_function-Dekorators vorgenommen.

Dienstkonto festlegen

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

  1. Erstellen Sie ein Dienstkonto mit minimalen Berechtigungen.
  2. Geben Sie dann die E-Mail-Adresse des Dienstkontos im Parameter cloud_function_service_account des @remote_function-Decorators 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 Zugriffseinstellungen der Cloud Run-Funktionen fest, die in "internal-only" bereitgestellt werden. Bisher waren die Ingress-Einstellungen standardmäßig auf "all" festgelegt. Sie können die Einstellungen für den 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

Bisher wurde in einer Region, in der regionale Dienstendpunkte und bigframes.pandas.options.bigquery.use_regional_endpoints = True nicht unterstützt wurden, in BigQuery DataFrames auf standortbezogene Endpunkte 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-Speicherorts, mit dem Sie eine Verbindung herstellen möchten.

Teilsortiermodus verwenden

In BigQuery DataFrames Version 2.0 ist der Teilsortiermodus allgemein verfügbar, aber standardmäßig deaktiviert. Wenn Sie die Teilsortierung verwenden möchten, setzen Sie ordering_mode auf partial, bevor Sie andere Vorgänge mit BigQuery DataFrames ausführen, wie im folgenden Codebeispiel gezeigt:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

In den meisten Fällen werden mit diesem Modus effizientere Abfragen generiert, in anderen Fällen identische Abfragen, z. B. solche, die die Funktion groupby() verwenden. Einige pandas-kompatible Funktionen, für die eine Sortierung erforderlich ist, z. B. .iloc[row_index], werden im Teilsortiermodus nicht unterstützt. Weitere Informationen finden Sie unter Modus für die teilweise Sortierung.

Nächste Schritte