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, für die es möglicherweise kein pandas-Äquivalent gibt.
  • bigframes.ml bietet eine API, die der scikit-learn-API für ML ä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 das 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 Remote-Modelle von BigQuery DataFrames ML 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 die Remote-Funktionen von BigQuery DataFrames verwenden, hat das Dienstkonto die Cloud Run-Aufruferrolle (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

Nach der Installation von BigQuery DataFrames können Sie die folgenden Optionen angeben.

Standort und Projekt

Sie müssen den Standort 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 Standort der erstellten DataFrame- oder Serienobjekte 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 Standort 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, 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. Dies 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 erforderlich

Damit keine Werte an einen unbeabsichtigten Parameter übergeben werden, wird in BigQuery DataFrames ab Version 2.0 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 wurde 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

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

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. Anschließend können Sie diese Daten in einen BigQuery DataFrames-DataFrame laden. Sie können BigQuery-Tabellen auch aus BigQuery DataFrames erstellen.

Daten aus einer BigQuery-Tabelle oder -Abfrage laden

Sie können einen DataFrame aus einer BigQuery-Tabelle oder -Abfrage so erstellen:

# 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()) dargestellt.
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 Möglichkeiten zur Datenbearbeitung für BigQuery DataFrames beschrieben. Die in der bigframes.bigquery-Bibliothek beschriebenen Funktionen finden Sie hier.

pandas API

Ein wichtiges Merkmal von BigQuery DataFrames ist, dass die bigframes.pandas API so konzipiert ist, dass sie APIs in der pandas-Bibliothek ähnelt. Dieses Design ermöglicht es Ihnen, vertraute Syntaxmuster für Datenbearbeitungsaufgaben zu verwenden. Vorgänge, die über die BigQuery DataFrames API definiert werden, werden serverseitig ausgeführt. Sie werden direkt auf Daten angewendet, die in BigQuery gespeichert sind. Datasets müssen also nicht aus BigQuery übertragen werden.

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

Daten prüfen und bearbeiten

Mit der bigframes.pandas API können Sie Datenprüfungs- und Berechnungsvorgänge ausführen. 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, für die es möglicherweise kein pandas-Äquivalent gibt. In den folgenden Abschnitten finden Sie einige Beispiele.

Arraywerte verarbeiten

Sie können die Funktion bigframes.bigquery.array_agg() in der Bibliothek bigframes.bigquery verwenden, um Werte nach einem groupby-Vorgang zu aggregieren:

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 Array-Funktionen array_length() und array_to_string() verwenden.

Struct-Reihe erstellen

Mit der Funktion bigframes.bigquery.struct() in der Bibliothek bigframes.bigquery können Sie eine neue Struct-Reihe 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 umwandeln:

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

Sie können die Funktion bigframes.bigquery.sql_scalar() in der bigframes.bigquery-Bibliothek verwenden, um auf beliebige SQL-Syntax zuzugreifen, die einen einzelnen Spaltenausdruck 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 Maßstab für BigQuery DataFrames-Objekte ausführen können. Mit dieser Erweiterbarkeit können Sie Vorgänge ausführen, die mit BigQuery DataFrames und SQL-APIs nicht möglich sind. So können Sie möglicherweise Open-Source-Bibliotheken nutzen. Die beiden Varianten dieses Erweiterbarkeitsmechanismus 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 Dataset erstellt. Eine vollständige Liste der unterstützten Parameter finden Sie unter udf.

Bereinigen

Zusätzlich zum Bereinigen der Cloud-Artefakte direkt in der Google Cloud Konsole oder mit anderen Tools können Sie die BigQuery DataFrames-UDFs, die mit einem expliziten Namensargument erstellt wurden, mit dem Befehlbigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) bereinigen.

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

Die BigQuery DataFrames-UDF stellt eine benutzerdefinierte BigQuery-Python-Funktion bereit. Es gelten die entsprechenden Einschränkungen.

Remote-Funktionen

Mit BigQuery DataFrames können Sie Ihre benutzerdefinierten skalaren Funktionen in BigQuery-Remote-Funktionen umwandeln. Ein Beispiel für die Verwendung 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 Standort 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 in dem von Ihnen angegebenen Dataset oder in einem anonymen Dataset erstellt. Ein anonymes Dataset ist eine Art verborgenes Dataset. Wenn Sie beim Erstellen einer Remote-Funktion keinen Namen festlegen, wendet BigQuery DataFrames einen Standardnamen an, der mit dem Präfix bigframes beginnt. 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 und dann das Dataset, in dem Sie die Remote-Funktion erstellt haben, und maximieren Sie dann Routinen.

So rufen Sie Cloud Run Functions 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 Function Deployment type (Typ der Funktionsbereitstellung).

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

Bereinigen

Zusätzlich zum Bereinigen der Cloud-Artefakte direkt in der Google Cloud -Konsole oder mit anderen Tools können Sie die BigQuery-Remote-Funktionen, die ohne explizites Namensargument erstellt wurden, und die zugehörigen Cloud Run-Funktionen auf folgende Arten bereinigen:

  • 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 vergangene Sitzung mit session_id den Befehl bigframes.pandas.clean_up_by_session_id(session_id).

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

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 für die Definition der Remote-Funktion nach geringfügigen Änderungen im und um den Funktionscode herum noch einmal ausführen, z. B. wenn Sie eine Variable umbenennen, eine neue Zeile einfügen oder eine neue Zelle in das Notebook einfügen, kann es sein, dass die Remote-Funktion neu erstellt wird, auch wenn diese Änderungen keine Auswirkungen auf das Verhalten der Funktion haben.
  • Der Nutzercode ist für Nutzer mit Lesezugriff auf die Cloud Run-Funktionen sichtbar. Sie sollten daher nur mit Vorsicht vertrauliche Inhalte einfügen.
  • Ein Projekt kann bis zu 1.000 Cloud Run-Funktionen gleichzeitig in einer Region 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 Modul bigframes.ml.preprocessing, um Features zu standardisieren, indem Sie den Mittelwert entfernen und auf die Einheitsvarianz skalieren.

  • Verwenden Sie die OneHotEncoder-Klasse im Modul bigframes.ml.preprocessing, um kategoriale 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 eine unbeaufsichtigte Lernmethode 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

Sie können Estimatoren für Zerlegungsmodelle mit dem bigframes.ml.decomposition-Modul 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

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

  • Verwenden Sie die RandomForestClassifier-Klasse, um Random Forest-Klassifikatormodelle zu erstellen. Verwenden Sie diese Modelle, um mehrere Entscheidungsmethoden 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-Boosted Tree-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 Entscheidungsmethoden für Lernmethoden für die Regression additiv zu erstellen.

Prognosemodelle

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

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

Importierte Modelle

Sie können Estimatoren für importierte Modelle mit dem bigframes.ml.imported-Modul 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

Sie können Estimatoren für LLMs mit dem bigframes.ml.llm-Modul 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 Estimators 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

Um BigQuery DataFrames ML-Remote-Modelle (bigframes.ml.remote oder bigframes.ml.llm) zu verwenden, 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 Pipeline-Klasse, um eine Pipeline von Transformationen mit einem endgültigen Estimator zu erstellen.

Modelle auswählen

Verwenden Sie das bigframes.ml.model_selection-Modul, 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 Trainings- und Testsätze mit mehreren Faltungen zum Trainieren und Evaluieren von Modellen zu erstellen, wie im folgenden Codebeispiel gezeigt. Diese Funktion ist für kleine Datasets nützlich.

    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 Trainings- und Testsätze mit mehreren Faltungen zu erstellen, das Modell zu trainieren und zu bewerten und das Ergebnis jeder Faltung 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 vorgestellt.

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. Das 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 mehr generiert. Im Teilsortiermodus werden auch Funktionen deaktiviert, die eine vollständige Sortierung aller Zeilen erfordern, z. B. das DataFrame.iloc-Attribut. Im Teilsortiermodus wird die Klasse DefaultIndexKind auf einen Nullindex anstelle eines sequenziellen Index über die Sortierung gesetzt.

Wenn Sie einen DataFrame filtern, bei dem die Eigenschaft ordering_mode auf partial festgelegt ist, muss BigQuery DataFrames nicht mehr berechnen, welche Zeilen im sequenziellen Index fehlen. Daher werden schnellere und effizientere Abfragen generiert. Die BigQuery DataFrames API ist weiterhin die vertraute pandas API, genau wie die Standardumgebung 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 das Attribut 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 zu verknüpfen, die aus unterschiedlichen Tabellenausdrücken abgeleitet werden.

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

# 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-Meldung 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 der Vorgang DataFrame.groupby() bieten implizit eine vollständige Sortierung der Group-by-Schlüssel.

Wenn die Sortierung nicht als vollständig stabile Gesamtsortierung für alle Zeilen bestimmt werden kann, werden Sie bei nachfolgenden Vorgängen möglicherweise mit einer AmbiguousWindowWarning-Meldung 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
)
Nullindex-Fehler

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 einen Index mit der Methode DataFrame.set_index() angeben, um nach einer oder mehreren Spalten zu sortieren. Andere Vorgänge wie DataFrame.groupby() stellen implizit einen Index für die Gruppe nach Schlüsseln bereit, sofern der Parameter as_index=False nicht festgelegt ist.

Nächste Schritte