BigQuery DataFrames verwenden

BigQuery DataFrames bietet eine Pythonic DataFrame und eine API für maschinelles Lernen (ML), die von der BigQuery-Engine unterstützt wird. BigQuery DataFrames ist ein Open-Source-Paket. Sie können pip install --upgrade bigframes ausführen, um die neueste Version zu installieren.

BigQuery DataFrames bietet drei Bibliotheken:

  • bigframes.pandas bietet eine Pandas API, mit der Sie Daten in BigQuery analysieren und bearbeiten können. Viele Arbeitslasten können von Pandas zu Bigframes migriert werden, indem nur einige Importe geändert werden. Die bigframes.pandas API ist skalierbar, um die Verarbeitung von Terabyte an BigQuery-Daten zu unterstützen. Sie verwendet die BigQuery-Abfrage-Engine für Berechnungen.
  • bigframes.bigquery bietet viele BigQuery-SQL-Funktionen, die möglicherweise kein Pandas-Äquivalent haben.
  • bigframes.ml bietet eine API, die der scikit-learn-API für maschinelles Lernen ähnelt. Mit den ML-Funktionen in BigQuery DataFrames können Sie Daten vorverarbeiten und Modelle mit diesen Daten trainieren. Diese Aktionen lassen sich auch für die Erstellung von Datenpipelines aneinanderketten.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Aufgaben in diesem Dokument benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Wenn Sie Remote-Funktionen von BigQuery DataFrames oder BigQuery DataFrames ML-Remote-Modelle verwenden, benötigen Sie außerdem die Rolle „Project IAM Admin“ (roles/resourcemanager.projectIamAdmin), wenn Sie eine BigQuery-Standardverbindung verwenden, oder die Rolle „Browser“ (roles/browser), wenn Sie eine vorkonfigurierte Verbindung verwenden. Diese Anforderung kann vermieden werden, indem die Option bigframes.pandas.options.bigquery.skip_bq_connection_check auf True gesetzt wird. In diesem Fall wird die Verbindung (Standard oder vorkonfiguriert) unverändert verwendet, ohne dass geprüft wird, ob sie besteht oder eine Berechtigung vorhanden ist. Wenn Sie die vorkonfigurierte Verbindung verwenden und die Verbindungsprüfung überspringen, prüfen Sie Folgendes:

  • Die Verbindung wird am richtigen Ort erstellt.
  • Wenn Sie Remote-Funktionen von BigQuery DataFrames verwenden, hat das Dienstkonto die Rolle Cloud Run-Aufrufer (roles/run.invoker) für das Projekt.
  • Wenn Sie BigQuery DataFrames ML-Remote-Modelle verwenden, hat das Dienstkonto die Vertex AI-Nutzerrolle (roles/aiplatform.user) für das Projekt.

Wenn Sie die Endnutzerauthentifizierung in einer interaktiven Umgebung wie einem Notebook, der Python-REPL oder der Befehlszeile ausführen, fordert BigQuery DataFrames bei Bedarf zur Authentifizierung auf. Andernfalls lesen Sie in diesem Artikel zum Einrichten von Standardanmeldedaten für Anwendungen für verschiedene Umgebungen.

Installationsoptionen konfigurieren

Nachdem Sie BigQuery DataFrames installiert haben, können Sie die folgenden Optionen angeben.

Standort und Projekt

Sie müssen den Speicherort und das Projekt angeben, in dem Sie BigQuery DataFrames verwenden möchten.

Sie können den Speicherort und das Projekt in Ihrem Notebook so definieren:

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dev"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

Ort der Datenverarbeitung

BigQuery DataFrames ist auf Skalierbarkeit ausgelegt, was durch die Speicherung von Daten und die Verarbeitung im BigQuery-Dienst ermöglicht wird. Sie können jedoch Daten in den Speicher Ihres Client-Rechners übertragen, indem Sie in einem DataFrame- oder Series-Objekt .to_pandas() aufrufen. In diesem Fall gilt die Speicherbeschränkung Ihres Clientcomputers.

Sitzungsstandort

BigQuery DataFrames verwendet ein lokales Sitzungsobjekt, um Metadaten intern zu verwalten. Diese Sitzung ist an einen Standort gebunden. BigQuery DataFrames verwendet den multiregionalen Standort US als Standard, aber Sie können session_options.location verwenden, um einen anderen Standort festzulegen. Jede Abfrage in einer Sitzung wird an dem Standort ausgeführt, an dem die Sitzung erstellt wurde. BigQuery DataFrames fügt bf.options.bigquery.location automatisch den Speicherort der Tabelle ein, wenn der Nutzer mit read_gbq/read_gbq_table/read_gbq_query() beginnt und entweder direkt oder in einer SQL-Anweisung eine Tabelle angibt.

Wenn Sie den Speicherort der erstellten DataFrame- oder Series-Objekte zurücksetzen möchten, können Sie die Sitzung durch Ausführen von bigframes.pandas.close_session() schließen. Danach können Sie bigframes.pandas.options.bigquery.location wiederverwenden, um einen anderen Ort anzugeben.

read_gbq() erfordert die Angabe eines Standorts, wenn sich das Dataset, das sie abfragen, nicht am multiregionalen Standort US befindet. Wenn Sie versuchen, eine Tabelle aus einem anderen Speicherort zu lesen, erhalten Sie die Ausnahme NotFound.

Zu BigQuery DataFrames Version 2.0 migrieren

Version 2.0 von BigQuery DataFrames bietet Verbesserungen bei Sicherheit und Leistung der BigQuery DataFrames API, neue Funktionen und bahnbrechende Änderungen. 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 neueste Version 1.x von BigQuery DataFrames verwenden.

BigQuery DataFrames Version 2.0 bietet folgende 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 festgelegt ist. Dies kann die Speicherkosten senken, insbesondere wenn Sie die Abrechnung nach physischen Byte verwenden.
  • Die Sicherheit der von BigQuery DataFrames bereitgestellten Remote-Funktionen wurde standardmäßig verbessert.

BigQuery DataFrames Version 2.0 installieren

Um Unterbrechungen zu vermeiden, können Sie in Ihrer requirements.txt-Datei (z. B. bigframes==1.42.0) oder pyproject.toml-Datei (z. B. dependencies = ["bigframes = 1.42.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 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 Unterbrechungen 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.

Keyword-Argumente werden für mehrdeutige Parameter erzwungen

Um das Übergeben von Werten an einen unbeabsichtigten Parameter zu verhindern, 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

Geben Sie bei der Verwendung dieser Parameter 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 bereitgestellten Cloud Run-Funktionen nicht mehr standardmäßig das Compute Engine-Dienstkonto. So beschränken Sie die Berechtigungen der von Ihnen bereitgestellten Funktion:

  1. Erstellen Sie ein Dienstkonto mit minimalen Berechtigungen.
  2. Geben Sie 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 Ingress-Einstellungen der Cloud Run-Funktionen fest, die auf "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

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 standortbezogene Endpunkte zurückgegriffen. In Version 2.0 von BigQuery DataFrames wird dieses Fallback-Verhalten entfernt. Wenn Sie eine Verbindung zu Standortendpunkten in Version 2.0 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.

bigframes.ml.llm-Modul verwenden

In BigQuery DataFrames Version 2.0 wurde der Standardwert model_name für GeminiTextGenerator auf "gemini-2.0-flash-001" aktualisiert. Wir empfehlen, direkt eine model_name anzugeben, um Unterbrechungen zu vermeiden, falls sich das Standardmodell in Zukunft ändert.

import bigframes.ml.llm

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

Eingabe und Ausgabe

Mit der bigframes.pandas-Bibliothek können Sie auf Daten aus verschiedenen Quellen zugreifen, darunter lokale CSV-Dateien, Cloud Storage-Dateien, pandas-DataFrames, BigQuery-Modelle und BigQuery-Funktionen. Sie können diese Daten dann in einen BigQuery DataFrames-DataFrame laden. Sie können BigQuery-Tabellen auch aus BigQuery DataFrames erstellen.

Daten aus einer BigQuery-Tabelle oder -Abfrage laden

So erstellen Sie einen DataFrame aus einer BigQuery-Tabelle oder -Abfrage:

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

Daten aus einer CSV-Datei laden

Sie können einen DataFrame aus einer lokalen oder Cloud Storage-CSV-Datei so erstellen:

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

Datentypen

BigQuery DataFrames unterstützt die folgenden dtypes von Numpy und Pandas:

BigQuery BigQuery DataFrames und Pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

Nur von to_pandas() unterstützt
INT64 pandas.Int64Dtype()
JSON pandas.ArrowDtype(pa.json_(pa.string()) in Pandas-Version 3.0 oder höher und Pyarrow-Version 19.0 oder höher, andernfalls werden JSON-Spalten als pandas.ArrowDtype(db_dtypes.JSONArrowType()) angezeigt.
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

Die folgenden BigQuery-Datentypen werden von BigQuery DataFrames nicht unterstützt:

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

Alle anderen BigQuery-Datentypen werden als Objekttyp angezeigt.

Datenmanipulation

In den folgenden Abschnitten werden die Funktionen zur Datenmanipulation für BigQuery DataFrames beschrieben. Die beschriebenen Funktionen finden Sie in der bigframes.bigquery-Bibliothek.

pandas API

Ein bemerkenswertes Merkmal von BigQuery DataFrames ist, dass die bigframes.pandas API APIs in der pandas-Bibliothek ähnelt. Mit diesem Design können Sie bekannte Syntaxmuster für Aufgaben zur Datenmanipulation verwenden. Vorgänge, die über die BigQuery DataFrames API definiert werden, werden serverseitig ausgeführt und direkt auf in BigQuery gespeicherten Daten angewendet. Es ist also nicht erforderlich, Datasets aus BigQuery zu übertragen.

Informationen dazu, welche pandas APIs von BigQuery DataFrames unterstützt werden, finden Sie unter Unterstützte pandas APIs.

Daten prüfen und bearbeiten

Sie können die bigframes.pandas API für Datenprüfungs- und Berechnungsvorgänge verwenden. Im folgenden Codebeispiel wird die bigframes.pandas-Bibliothek verwendet, um die Spalte body_mass_g zu prüfen, den Mittelwert body_mass zu berechnen und den Mittelwert body_mass nach species zu berechnen:

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

BigQuery-Bibliothek

Die BigQuery-Bibliothek bietet BigQuery-SQL-Funktionen, die möglicherweise kein Pandas-Äquivalent haben. In den folgenden Abschnitten finden Sie einige Beispiele.

Arraywerte verarbeiten

Mit der Funktion bigframes.bigquery.array_agg() in der Bibliothek bigframes.bigquery können Sie Werte nach einem groupby-Vorgang zusammenfassen:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

Sie können auch die Arrayfunktionen array_length() und array_to_string() verwenden.

Strukturreihe erstellen

Mit der Funktion bigframes.bigquery.struct() in der bigframes.bigquery-Bibliothek können Sie eine neue Strukturreihe mit Unterfeldern für jede Spalte in einem DataFrame erstellen:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

Zeitstempel in Unix-Epochen umwandeln

Mit der Funktion bigframes.bigquery.unix_micros() in der Bibliothek bigframes.bigquery können Sie Zeitstempel in Unix-Mikrosekunden konvertieren:

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

Sie können auch die Zeitfunktionen unix_seconds() und unix_millis() verwenden.

SQL-Skalarfunktion verwenden

Mit der Funktion bigframes.bigquery.sql_scalar() in der bigframes.bigquery-Bibliothek können Sie auf beliebige SQL-Syntax zugreifen, die einen Ausdruck mit einer einzelnen Spalte darstellt:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

Benutzerdefinierte Python-Funktionen

Mit BigQuery DataFrames können Sie Ihre benutzerdefinierten Python-Funktionen in BigQuery-Artefakte umwandeln, die Sie in großem Umfang auf BigQuery DataFrames-Objekten ausführen können. Dank dieser Erweiterungsunterstützung können Sie mehr Vorgänge ausführen als mit BigQuery DataFrames und SQL APIs möglich ist. So können Sie potenziell Open-Source-Bibliotheken nutzen. Die beiden Varianten dieses Erweiterungsmechanismus werden in den folgenden Abschnitten beschrieben.

Nutzerdefinierte Funktionen (UDFs)

Mit UDFs (Vorabversion) können Sie Ihre benutzerdefinierte Python-Funktion in eine Python-UDF umwandeln. Ein Beispiel für die Verwendung finden Sie unter Persistente Python-UDF erstellen.

Wenn Sie eine UDF in BigQuery DataFrames erstellen, wird eine BigQuery-Routine als Python-UDF im angegebenen Datenpool erstellt. Eine vollständige Liste der unterstützten Parameter finden Sie unter udf.

Bereinigen

Sie können die Cloud-Artefakte nicht nur direkt in der Google Cloud -Konsole oder mit anderen Tools bereinigen, sondern auch die BigQuery DataFrames-UDFs, die mit einem expliziten Namensargument erstellt wurden. Verwenden Sie dazu den Befehl bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Voraussetzungen

Wenn Sie eine BigQuery DataFrames-UDF verwenden möchten, aktivieren Sie die BigQuery API in Ihrem Projekt. Wenn Sie den Parameter bigquery_connection in Ihrem Projekt angeben, müssen Sie auch die BigQuery Connection API aktivieren.

Beschränkungen

  • Der Code in der UDF muss in sich geschlossen sein, d. h., er darf keine Verweise auf einen Import oder eine Variable enthalten, die außerhalb des Funktionsblocks definiert ist.
  • Der Code in der UDF muss mit Python 3.11 kompatibel sein, da der Code in der Cloud in dieser Umgebung ausgeführt wird.
  • Wenn Sie den Code zur UDF-Definition nach geringfügigen Änderungen am Funktionscode noch einmal ausführen, z. B. eine Variable umbenennen oder eine neue Zeile einfügen, wird die UDF neu erstellt, auch wenn diese Änderungen für das Verhalten der Funktion keine Auswirkungen haben.
  • Der Nutzercode ist für Nutzer mit Lesezugriff auf die BigQuery-Routinen sichtbar. Daher sollten Sie vertrauliche Inhalte nur mit Vorsicht einfügen.
  • Ein Projekt kann bis zu 1.000 Cloud Run-Funktionen gleichzeitig an einem BigQuery-Speicherort haben.

Für die BigQuery DataFrames-UDF wird eine benutzerdefinierte BigQuery-Python-Funktion bereitgestellt. Die entsprechenden Einschränkungen gelten.

Remote-Funktionen

Mit BigQuery DataFrames können Sie Ihre benutzerdefinierten skalaren Funktionen in BigQuery-Remote-Funktionen umwandeln. Ein Beispiel finden Sie unter Remote-Funktion erstellen. Eine vollständige Liste der unterstützten Parameter finden Sie unter remote_function.

Wenn Sie eine Remote-Funktion in BigQuery DataFrames erstellen, geschieht Folgendes:

  • Eine Cloud Run-Funktion.
  • Eine BigQuery-Verbindung. Standardmäßig wird eine Verbindung mit dem Namen bigframes-default-connection verwendet. Sie können eine vorkonfigurierte BigQuery-Verbindung verwenden, wenn Sie möchten. In diesem Fall wird die Verbindungserstellung übersprungen. Dem Dienstkonto für die Standardverbindung wird die Cloud Run-Rolle (roles/run.invoker) zugewiesen.
  • Eine BigQuery-Remote-Funktion, die die Cloud Run-Funktion verwendet, die mit der BigQuery-Verbindung erstellt wurde.

BigQuery-Verbindungen werden am selben Speicherort wie die BigQuery DataFrames-Sitzung erstellt. Dabei wird der Name verwendet, den Sie in der Definition der benutzerdefinierten Funktion angeben. So rufen Sie Verbindungen auf und verwalten sie:

  1. Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

    BigQuery aufrufen

  2. Wählen Sie das Projekt aus, in dem Sie die Remote-Funktion erstellt haben.

  3. Maximieren Sie im Bereich Explorer das Projekt und dann Externe Verbindungen.

BigQuery-Remote-Funktionen werden im von Ihnen angegebenen Dataset oder in einem anonymen Dataset erstellt, einer Art verborgenen Datasets. Wenn Sie bei der Erstellung einer Remote-Funktion keinen Namen festlegen, wird in BigQuery DataFrames ein Standardname mit dem Präfix bigframes verwendet. So rufen Sie Remote-Funktionen auf, die in einem vom Nutzer angegebenen Dataset erstellt wurden, und verwalten sie:

  1. Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

    BigQuery aufrufen

  2. Wählen Sie das Projekt aus, in dem Sie die Remote-Funktion erstellt haben.

  3. Maximieren Sie im Bereich Explorer das Projekt, maximieren Sie das Dataset, in dem Sie die Remote-Funktion erstellt haben, und maximieren Sie dann Abläufe.

So rufen Sie Cloud Run-Funktionen auf und verwalten sie:

  1. Zur Seite „Cloud Run“

    Zu Cloud Run

  2. Wählen Sie das Projekt aus, in dem Sie die Funktion erstellt haben.

  3. Filtern Sie in der Liste der verfügbaren Dienste nach Typ der Funktionsbereitstellung.

  4. Funktionen, die von BigQuery DataFrames erstellt wurden, sind an Funktionsnamen mit dem Präfix bigframes zu erkennen.

Bereinigen

Sie können die Cloud-Artefakte nicht nur direkt in der Google Cloud Console oder mit anderen Tools bereinigen, sondern auch die BigQuery-Remote-Funktionen, die ohne explizites Name-Argument erstellt wurden, und die zugehörigen Cloud Run-Funktionen auf folgende Arten:

  • Verwenden Sie für eine BigQuery DataFrames-Sitzung den Befehl session.close().
  • Verwenden Sie für die Standard-BigQuery DataFrames-Sitzung den Befehl bigframes.pandas.close_session().
  • Verwenden Sie für eine frühere Sitzung mit session_id den Befehl bigframes.pandas.clean_up_by_session_id(session_id).

Mit dem Befehl bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) können Sie auch BigQuery-Remote-Funktionen bereinigen, die mit einem expliziten Namensargument erstellt wurden, und die zugehörigen Cloud Run-Funktionen.

Voraussetzungen

Damit Sie die Remote-Funktionen von BigQuery DataFrames verwenden können, müssen Sie die folgenden APIs aktivieren:

Beschränkungen

  • Es dauert etwa 90 Sekunden, bis Remote-Funktionen nach ihrer Erstellung verwendet werden können. Zusätzliche Paketabhängigkeiten können die Latenz erhöhen.
  • Wenn Sie den Code zur Definition der Remote-Funktion nach geringfügigen Änderungen am Funktionscode noch einmal ausführen, z. B. eine Variable umbenennen, eine neue Zeile einfügen oder eine neue Zelle in das Notebook einfügen, kann die Remote-Funktion neu erstellt werden, auch wenn diese Änderungen für das Verhalten der Funktion keine Auswirkungen haben.
  • Der Nutzercode ist für Nutzer mit Lesezugriff auf die Cloud Run-Funktionen sichtbar. Daher sollten Sie vertrauliche Inhalte nur mit Vorsicht einfügen.
  • Ein Projekt kann in einer Region bis zu 1.000 Cloud Run-Funktionen gleichzeitig haben. Weitere Informationen finden Sie unter Kontingente.

ML und KI

In den folgenden Abschnitten werden die ML- und KI-Funktionen für BigQuery-DataFrames beschrieben. Für diese Funktionen wird die bigframes.ml-Bibliothek verwendet.

ML-Speicherorte

Die bigframes.ml-Bibliothek unterstützt dieselben Standorte wie BigQuery ML. BigQuery ML-Modellvorhersagen und andere ML-Funktionen werden in allen BigQuery-Regionen unterstützt. Die Unterstützung für das Modelltraining variiert je nach Region. Weitere Informationen finden Sie unter BigQuery ML-Standorte.

Daten vorverarbeiten

Erstellen Sie Transformer, um Daten für die Verwendung in Estimators (Modellen) mithilfe derModul bigframes.ml.preprocessing und dieModul bigframes.ml.compose vorzubereiten. BigQuery DataFrames bietet die folgenden Transformationen:

  • Verwenden Sie die KBinsDiscretizer-Klasse im Modul bigframes.ml.preprocessing, um kontinuierliche Daten in Intervalle zu bündeln.

  • Verwenden Sie die LabelEncoder-Klasse im Modul bigframes.ml.preprocessing, um die Ziellabels als Ganzzahlwerte zu normalisieren.

  • Verwenden Sie die MaxAbsScaler-Klasse im Modul bigframes.ml.preprocessing, um jedes Feature um seinen maximalen absoluten Wert auf den Bereich [-1, 1] zu skalieren.

  • Verwenden Sie die MinMaxScaler-Klasse im Modul bigframes.ml.preprocessing, um Features zu standardisieren, indem Sie jedes Feature auf den Bereich [0, 1] skalieren.

  • Verwenden Sie die StandardScaler-Klasse im bigframes.ml.preprocessing-Modul, um Merkmale zu standardisieren. Dazu entfernen Sie den Mittelwert und die Skalierung auf die Einheitsvarianz.

  • Verwenden Sie die OneHotEncoder-Klasse im Modul bigframes.ml.preprocessing, um kategorische Werte in ein numerisches Format umzuwandeln.

  • Verwenden Sie die ColumnTransformer-Klasse im Modul bigframes.ml.compose, um Transformer auf DataFrames-Spalten anzuwenden.

Modelle trainieren

Sie können Estimatoren zum Trainieren von Modellen in BigQuery DataFrames erstellen.

Clustering-Modelle

Mit dem bigframes.ml.cluster-Modul können Sie Estimatoren für Clustering-Modelle erstellen.

  • Verwenden Sie die KMeans-Klasse, um K-Means-Clustering-Modelle zu erstellen. Verwenden Sie diese Modelle für die Datensegmentierung. Beispiel: Identifizierung von Kundensegmenten. Da K-Means ein unüberwachtes Lernverfahren ist, sind für das Modelltraining weder Labels noch Datenaufteilungen für die Trainings- oder Evaluierungsphase erforderlich.

Mit dem Modul bigframes.ml.cluster können Sie Estimators für Clustering-Modelle erstellen.

Das folgende Codebeispiel zeigt die Verwendung der Klasse bigframes.ml.cluster KMeans zum Erstellen eines K-Means-Clustering-Modells für die Datensegmentierung:

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

Zerlegungsmodelle

Mit dem bigframes.ml.decomposition-Modul können Sie Estimatoren für Zerlegungsmodelle erstellen.

  • Verwenden Sie die PCA-Klasse, um Modelle für die Hauptkomponentenanalyse (Principal Component Analysis, PCA) zu erstellen. Verwenden Sie diese Modelle zur Berechnung der Hauptkomponenten und zur Durchführung einer Änderung der Grundlage der Daten. Dadurch wird die Dimensionalität reduziert, indem jeder Datenpunkt auf die ersten Hauptkomponenten projiziert wird, um niedrigdimensionale Daten zu erhalten und gleichzeitig einen möglichst großen Teil der Datenabweichung beizubehalten.

Ensemble-Modelle

Mit dem bigframes.ml.ensemble-Modul können Sie Estimatoren für Ensemble-Modelle erstellen.

  • Verwenden Sie die RandomForestClassifier-Klasse, um Random Forest-Klassifikatormodelle zu erstellen. Verwenden Sie diese Modelle, um mehrere Entscheidungsbäume für Lernmethoden zur Klassifizierung zu erstellen.

  • Verwenden Sie die RandomForestRegressor-Klasse, um Random Forest-Regressionsmodelle zu erstellen. Verwenden Sie diese Modelle, um mehrere Entscheidungsbäume für Lernmethoden für die Regression zu erstellen.

  • Verwenden Sie die XGBClassifier-Klasse, um Gradienten-Boosting-Baum-Klassifikatormodelle zu erstellen. Verwenden Sie diese Modelle, um mehrere Entscheidungsmethoden für Lernmethoden zur Klassifizierung additiv zu erstellen.

  • Verwenden Sie die XGBRegressor-Klasse, um Gradienten-Boosting-Baum-Regressionsmodelle zu erstellen. Verwenden Sie diese Modelle, um mehrere Entscheidungsbäume für Lernmethoden für die Regression additiv zu erstellen.

Prognosemodelle

Mit dem bigframes.ml.forecasting-Modul können Sie Estimatoren für Prognosemodelle erstellen.

  • Verwenden Sie die ARIMAPlus-Klasse, um Zeitreihenprognosemodelle zu erstellen.

Importierte Modelle

Mit dem bigframes.ml.imported-Modul können Sie Estimatoren für importierte Modelle erstellen.

Lineare Modelle

Erstellen Sie Estimatoren für lineare Modelle mit dem bigframes.ml.linear_model-Modul.

  • Verwenden Sie die LinearRegression-Klasse, um lineare Regressionsmodelle zu erstellen. Verwenden Sie diese Modelle für Prognosen. Beispiel: Umsatzprognosen für einen Artikel an einem bestimmten Tag.

  • Verwenden Sie die LogisticRegression-Klasse, um logistische Regressionsmodelle zu erstellen. Verwenden Sie diese Modelle für die Klassifizierung von zwei oder mehr möglichen Werten, z. B. ob eine Eingabe low-value, medium-value oder high-value ist.

Das folgende Codebeispiel zeigt bigframes.ml, um Folgendes zu tun:

from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

Large Language Models

Mit dem bigframes.ml.llm-Modul können Sie Estimatoren für LLMs erstellen.

Verwenden Sie die GeminiTextGenerator-Klasse, um Gemini-Textgeneratormodelle zu erstellen. Verwenden Sie diese Modelle für Aufgaben zur Textgenerierung.

Mit dem Modul bigframes.ml.llm können Sie Estimatoren für Remote-Großsprachmodelle (LLMs) erstellen.
Im folgenden Codebeispiel wird gezeigt, wie die Klasse bigframes.ml.llm GeminiTextGenerator verwendet wird, um ein Gemini-Modell für die Codegenerierung zu erstellen:

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

Remotemodelle

Wenn Sie BigQuery DataFrames-ML-Remote-Modelle (bigframes.ml.remote oder bigframes.ml.llm) verwenden möchten, müssen Sie die folgenden APIs aktivieren:

Durch das Erstellen eines Remote-Modells in BigQuery DataFrames wird eine BigQuery-Verbindung erstellt. Standardmäßig wird eine Verbindung des Namens bigframes-default-connection verwendet. Sie können eine vorkonfigurierte BigQuery-Verbindung verwenden, wenn Sie möchten. In diesem Fall wird die Verbindungserstellung übersprungen. Dem Dienstkonto für die Standardverbindung wurde die Rolle Vertex AI-Nutzer (roles/aiplatform.user) für das Projekt zugewiesen.

Pipelines erstellen

Sie können ML-Pipelines mit dem bigframes.ml.pipeline-Modul erstellen. Mit Pipelines können Sie mehrere ML-Schritte zusammenstellen, die gemeinsam validiert werden sollen, während Sie verschiedene Parameter festlegen. Dies vereinfacht den Code und ermöglicht es Ihnen, Datenvorverarbeitungsschritte und einen Estimator zusammen bereitzustellen.

Verwenden Sie die Pipelineklasse, um eine Pipeline von Transformationen mit einem endgültigen Estimator zu erstellen.

Modelle auswählen

Verwenden Sie das Modul bigframes.ml.model_selection, um Ihre Trainings- und Test-Datasets aufzuteilen und die besten Modelle auszuwählen:

  • Verwenden Sie die train_test_split-Funktion, um die Daten in Trainings- und Test-Datasets (Evaluierungs-Datasets) aufzuteilen, wie im folgenden Codebeispiel gezeigt:

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • Verwenden Sie die Klasse KFold und die Methode KFold.split, um mehrstufige Trainings- und Test-Datasets zum Trainieren und Bewerten von Modellen zu erstellen, wie im folgenden Codebeispiel gezeigt. Diese Funktion ist für kleine Datensätze geeignet.

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • Verwenden Sie die Funktion cross_validate, um automatisch mehrstufige Trainings- und Testsätze zu erstellen, das Modell zu trainieren und zu bewerten und das Ergebnis jedes Folds abzurufen, wie im folgenden Codebeispiel gezeigt:

    scores = cross_validate(model, X, y, cv=5)

Leistungsoptimierung

In diesem Abschnitt werden Möglichkeiten zur Optimierung der Leistung von BigQuery DataFrames beschrieben.

Teilsortiermodus

BigQuery DataFrames bietet eine Sortiermodus-Funktion. Legen Sie das Attribut ordering_mode auf partial fest, um effizientere Abfragen zu generieren.

Der partial-Sortiermodus unterscheidet sich vom Standardmodus strict, bei dem eine Gesamtsortierung aller Zeilen erstellt wird. Durch eine Gesamtsortierung sind BigQuery DataFrames besser mit Pandas kompatibel, da mit der Eigenschaft DataFrame.iloc ein sortierungsbasierter Zugriff auf Zeilen möglich ist. Aufgrund der Gesamtsortierung und des standardmäßigen sequenziellen Index über diese Sortierung wird die Anzahl der gescannten Byte jedoch weder durch Spaltenfilter noch durch Zeilenfilter reduziert, es sei denn, diese Filter werden als Parameter auf die Funktionen read_gbq und read_gbq_table angewendet. Um eine Gesamtsortierung aller Zeilen im DataFrame bereitzustellen, wird in BigQuery DataFrames ein Hash aller Zeilen erstellt. Dies kann zu einem vollständigen Datenscan führen, bei dem Zeilen- und Spaltenfilter ignoriert werden.

Wenn Sie die Eigenschaft ordering_mode auf partial festlegen, wird in BigQuery DataFrames keine Gesamtsortierung aller Zeilen generiert. Im Teilsortiermodus werden ebenfalls Funktionen deaktiviert, die eine vollständige Sortierung aller Zeilen erfordern, z. B. das DataFrame.iloc-Attribut. Im Teilsortiermodus wird DefaultIndexKind auf einen Nullindex anstelle eines sequenziellen Index über die Sortierung gesetzt.

Wenn Sie einen DataFrame filtern, für den die Eigenschaft ordering_mode auf partial festgelegt ist, muss BigQuery DataFrames nicht mehr berechnen, welche Zeilen im sequenziellen Index fehlen. Dadurch werden schnellere und effizientere Abfragen generiert. Die BigQuery DataFrames API ist weiterhin die vertraute pandas API, genau wie die Standardfunktion mit dem strengen Sortiermodus. Der Teilsortiermodus unterscheidet sich jedoch vom üblichen Pandas-Verhalten. Beispielsweise werden im Teilsortiermodus keine impliziten Joins nach Index ausgeführt.

Sowohl beim Teil- als auch beim strengen Sortiermodus zahlen Sie für die von Ihnen verwendeten BigQuery-Ressourcen. Bei der Arbeit mit großen geclusterten und partitionierten Tabellen können Sie jedoch Kosten sparen, wenn Sie den Teilsortiermodus verwenden, da Zeilenfilter für Cluster- und Partitionsspalten die Anzahl der verarbeiteten Bytes reduzieren.

Nutzung

Wenn Sie die Teilsortierung verwenden möchten, setzen Sie die Eigenschaft 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"

Da es im Teilsortiermodus keinen sequenziellen Index gibt, werden nicht zusammenhängende BigQuery-DataFrames nicht implizit zusammengeführt. Stattdessen müssen Sie die Methode DataFrame.merge explizit aufrufen, um zwei BigQuery-DataFrames zusammenzuführen, die aus verschiedenen Tabellenausdrücken stammen.

Die Funktionen Series.unique() und Series.drop_duplicates() sind mit dem Teilsortiermodus nicht kompatibel. Verwenden Sie stattdessen die Methode groupby, um eindeutige Werte auf diese Weise zu ermitteln:

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

Im Teilsortiermodus ist nicht garantiert, dass die Ausgabe der Funktionen DataFrame.head(n) und Series.head(n) bei allen Aufrufen idempotent ist. Wenn Sie eine kleine, beliebige Stichprobe der Daten herunterladen möchten, verwenden Sie die Methoden DataFrame.peek() oder Series.peek().

Eine detaillierte Anleitung zur Verwendung des Attributs ordering_mode = "partial" finden Sie in diesem BigQuery DataFrames-Notebook, in dem der Teilsortiermodus demonstriert wird.

Fehlerbehebung

Da DataFrames im Teilsortiermodus nicht immer eine Sortierung oder einen Index haben, können bei der Verwendung einiger pandas-kompatibler Methoden die folgenden Probleme auftreten.

Fehler: Sortierung erforderlich

Für einige Funktionen ist eine Sortierung erforderlich, z. B. für die Funktionen DataFrame.head() und DataFrame.iloc. Eine Liste der Funktionen, für die eine Sortierung erforderlich ist, finden Sie in der Spalte Sortierung erforderlich in Unterstützte pandas APIs.

Wenn das Objekt nicht sortiert ist, schlägt der Vorgang mit einer OrderRequiredError-Nachricht wie der folgenden fehl:

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

Wie in der Fehlermeldung beschrieben, können Sie mit der Methode DataFrame.sort_values() eine Sortierung nach einer oder mehreren Spalten angeben. Andere Vorgänge wie DataFrame.groupby() sorgen implizit für eine Gesamtsortierung der Gruppe nach Schlüsseln.

Wenn nicht festgestellt werden kann, dass die Sortierung eine vollständig stabile Gesamtsortierung für alle Zeilen ist, werden Sie bei nachfolgenden Vorgängen möglicherweise mit einer AmbiguousWindowWarning-Nachricht wie der folgenden gewarnt:

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

Wenn Ihre Arbeitslast nicht deterministische Ergebnisse zulassen kann oder Sie manuell prüfen können, ob die von Ihnen angegebene Sortierung eine Gesamtsortierung ist, können Sie die AmbiguousWindowWarning-Nachricht so filtern:

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
Fehler beim Nullindex

Für einige Funktionen ist ein Index erforderlich, z. B. für die Eigenschaften DataFrame.unstack() und Series.interpolate(). Eine Liste der Funktionen, für die ein Index erforderlich ist, finden Sie in der Spalte Index erforderlich in Unterstützte pandas APIs.

Wenn Sie einen Vorgang verwenden, für den ein Index mit dem Teilsortiermodus erforderlich ist, wird eine NullIndexError-Nachricht wie die folgende ausgegeben:

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

Wie in der Fehlermeldung beschrieben, können Sie mit der Methode DataFrame.set_index() einen Index angeben, um nach einer oder mehreren Spalten zu sortieren. Andere Vorgänge wie DataFrame.groupby() liefern implizit einen Index über die Gruppe nach Schlüsseln, es sei denn, der Parameter as_index=False ist festgelegt.

Visualisierungen

Die bigframes.pandas API ist ein Gateway zum vollständigen Python-System an Tools. Die API unterstützt erweiterte statistische Vorgänge und Sie können die von BigQuery DataFrames generierten Aggregationen visualisieren. Sie können auch von einem BigQuery DataFrames-DataFrame zu einem pandas-DataFrame mit integrierten Stichprobenvorgängen wechseln.

Nächste Schritte