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. Diebigframes.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:
-
BigQuery-Jobnutzer (
roles/bigquery.jobUser
) -
BigQuery Read Session-Nutzer ()
roles/bigquery.readSessionUser
-
BigQuery DataFrames in einem BigQuery-Notebook verwenden:
-
BigQuery-Nutzer (
roles/bigquery.user
) -
Notebook Runtime-Nutzer (
roles/aiplatform.notebookRuntimeUser
) -
Code Creator (
roles/dataform.codeCreator
)
-
BigQuery-Nutzer (
-
Remote-Funktionen von BigQuery DataFrames verwenden:
-
BigQuery Data Editor (
roles/bigquery.dataEditor
) -
BigQuery Connection Admin (
roles/bigquery.connectionAdmin
) -
Cloud Functions Developer (
roles/cloudfunctions.developer
) -
Dienstkontonutzer (
roles/iam.serviceAccountUser
) -
Storage-Objekt-Betrachter (
roles/storage.objectViewer
)
-
BigQuery Data Editor (
-
BigQuery DataFrames ML-Remote-Modelle verwenden:
BigQuery-Verbindungsadministrator (
roles/bigquery.connectionAdmin
)
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:
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äßigFalse
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:
- Erstellen Sie ein Dienstkonto mit minimalen Berechtigungen.
- 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:
Daten aus einer CSV-Datei laden
Sie können einen DataFrame aus einer lokalen oder Cloud Storage-CSV-Datei so erstellen:
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 |
Nur von |
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:
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:
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:
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:
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:
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:
Rufen Sie in der Google Cloud Console die Seite BigQuery auf.
Wählen Sie das Projekt aus, in dem Sie die Remote-Funktion erstellt haben.
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:
Rufen Sie in der Google Cloud Console die Seite BigQuery auf.
Wählen Sie das Projekt aus, in dem Sie die Remote-Funktion erstellt haben.
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:
Zur Seite „Cloud Run“
Wählen Sie das Projekt aus, in dem Sie die Funktion erstellt haben.
Filtern Sie in der Liste der verfügbaren Dienste nach Function Deployment type (Typ der Funktionsbereitstellung).
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 Befehlbigframes.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:
- BigQuery API (
bigquery.googleapis.com
) - BigQuery Connection API (
bigqueryconnection.googleapis.com
) - Cloud Functions API (
cloudfunctions.googleapis.com
) - Cloud Run Admin API (
run.googleapis.com
) - Artifact Registry API (
artifactregistry.googleapis.com
) - Cloud Build API (
cloudbuild.googleapis.com
) - Compute Engine API (
compute.googleapis.com
) Cloud Resource Manager API (
cloudresourcemanager.googleapis.com
)Sie können diese Anforderung vermeiden, indem Sie die Option
bigframes.pandas.options.bigquery.skip_bq_connection_check
aufTrue
setzen. In diesem Fall wird die Verbindung (entweder standardmäßig oder vorkonfiguriert) unverändert verwendet, ohne dass die Existenz der Verbindung oder Überprüfung ihrer Berechtigungen geprüft wird.
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:
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.
Verwenden Sie die ONNXModel-Klasse, um ONNX-Modelle (Open Neural Network Exchange) zu importieren.
Verwenden Sie die TensorFlowModel-Klasse, um TensorFlow-Modelle zu importieren.
Verwenden Sie die XGBoostModel-Klasse, um XGBoostModel-Modelle zu importieren.
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
oderhigh-value
ist.
Das folgende Codebeispiel zeigt bigframes.ml
, um Folgendes zu tun:
- Daten aus BigQuery laden
- Trainingsdaten bereinigen und vorbereiten
- Regressionsmodell bigframes.ml.LinearRegression erstellen und anwenden
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:
Remotemodelle
Um BigQuery DataFrames ML-Remote-Modelle (bigframes.ml.remote
oder bigframes.ml.llm
) zu verwenden, müssen Sie die folgenden APIs aktivieren:
Cloud Resource Manager API (
cloudresourcemanager.googleapis.com
)Sie können diese Anforderung vermeiden, indem Sie die Option
bigframes.pandas.options.bigquery.skip_bq_connection_check
aufTrue
setzen. In diesem Fall wird die Verbindung (entweder standardmäßig oder vorkonfiguriert) unverändert verwendet, ohne dass die Existenz der Verbindung oder Überprüfung ihrer Berechtigungen geprüft wird.
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 MethodeKFold.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:
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:
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:
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
- BigQuery-DataFrames visualisieren
- Code für BigQuery DataFrames mit Gemini generieren
- Informationen zum Analysieren von Paketdownloads von PyPI mit BigQuery DataFrames
- Quellcode, Beispiel-Notebooks und Beispiele für BigQuery DataFrames finden Sie auf GitHub.
- Referenz zur BigQuery DataFrames API