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 zwei Bibliotheken:

  • bigframes.pandas bietet eine mit Pandas kompatible API für Analysen.

  • bigframes.ml bietet eine scikit-learn-ähnliche API für maschinelles Lernen (ML).

Erforderliche Berechtigungen

Optionen

Nach der Installation müssen Sie 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-dec"  # @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 eine 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 in Ihrem BigQueryOptions-Objekt allow_large_results auf True festlegen, um fehlerhafte Änderungen zu vermeiden. In BigQuery DataFrames Version 2.0 ist diese Option standardmäßig auf False festgelegt.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Sie können die Option allow_large_results überschreiben, indem Sie den Parameter allow_large_results in to_pandas() und anderen Methoden verwenden. Beispiel:

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

@remote_function-Decorator verwenden

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

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 in "internal-only" bereitgestellt werden. Bisher waren die Ingress-Einstellungen standardmäßig auf "all" festgelegt. Sie können die Einstellungen für den Traffic von außen ä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 in einer Region, in der regionale Dienstendpunkte und bigframes.pandas.options.bigquery.use_regional_endpoints = True nicht unterstützt wurden, auf Standortendpunkte 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")

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.

Teilsortiermodus

BigQuery DataFrames bietet eine Sortiermodus-Funktion. Legen Sie 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 mit ordering_mode = partial filtern, muss in BigQuery DataFrames nicht mehr berechnet werden, welche Zeilen im sequenziellen Index fehlen. Dadurch werden schnellere und effizientere Abfragen generiert. Die BigQuery DataFrames API ist weiterhin pandas-ähnlich, 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 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, kann dies bei der Verwendung einiger pandas-kompatibler Methoden zu häufigen Problemen führen.

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.

Bibliothek bigframes.pandas verwenden

Die bigframes.pandas-Bibliothek bietet eine pandas-ähnliche API, mit der Sie Daten in BigQuery analysieren und bearbeiten können. 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. Weitere Informationen finden Sie unter Unterstützte Pandas-APIs.

Die bigframes.pandas API bietet folgende Funktionen:

Eingabe und Ausgabe

Sie können auf Daten aus verschiedenen Quellen, einschließlich lokaler CSV-Dateien, Cloud Storage-Dateien, pandas-DataFrames, BigQuery-Modelle und BigQuery-Funktionen, zugreifen und sie in ein BigQuery DataFrames-DataFrame laden. Sie können BigQuery-Tabellen auch aus BigQuery DataFrames erstellen.

Pandas-ähnliche API

Ein bemerkenswertes Merkmal von BigQuery DataFrames ist, dass die API so konzipiert ist, dass sie den APIs in der pandas-Bibliothek ähnelt. So können Sie vertraute 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.

Ein API-Beispiel finden Sie unter Daten prüfen und bearbeiten.

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

Python-Umgebung und 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.

Benutzerdefinierte Python-Funktionen

Mit BigQuery DataFrames können Sie Ihre benutzerdefinierten skalaren Funktionen in BigQuery-Remote-Funktionen umwandeln . Wenn Sie eine Remote-Funktion in BigQuery DataFrames erstellen, geschieht Folgendes:

  1. Eine Cloud Run-Funktion (2. Generation).

  2. Eine BigQuery-Verbindung. 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 wird die IAM-Rolle „Cloud Run Invoker“ (roles/run.invoker) zugewiesen.

  3. Eine BigQuery-Remote-Funktion, die die Cloud Functions-Funktion (1) über die BigQuery-Verbindung verwendet (2).

Ein Beispiel finden Sie unter Remote-Funktion erstellen.

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 BigQuery in derGoogle Cloud Console auf.

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

  3. Maximieren Sie im Explorer-Bereich dieses Projekt und dann „Externe Verbindungen“.

BigQuery-Remote-Funktionen werden im von Ihnen angegebenen Dataset oder in einem anonymen Dataset erstellt, einer Art verborgenes Dataset. Wenn Sie beim Erstellen einer Remote-Funktion keinen Namen festlegen, wird in BigQuery DataFrames ein Standardname verwendet, 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 BigQuery in derGoogle Cloud Console auf.

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

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

Verwenden Sie zum Anzeigen und Verwalten von Cloud Run Functions-Funktionen die Seite Funktionen und wählen Sie mithilfe der Projektauswahl das Projekt aus, in dem Sie die Funktion erstellt haben. Funktionen, die von BigQuery DataFrames erstellt wurden, sind an dem Präfix bigframes zu erkennen.

Sie können unbenannte BigQuery-Remote-Funktionen und die zugehörigen Cloud Run Functions-Funktionen auf folgende Arten bereinigen:

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

Voraussetzungen

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

Wenn Sie die Remote-Funktionen von BigQuery DataFrames verwenden möchten, benötigen Sie im Projekt die folgenden IAM-Rollen:

  • BigQuery-Dateneditor (roles/bigquery.dataEditor)

  • BigQuery Connection Admin (roles/bigquery.connectionAdmin)

  • Cloud Functions-Entwickler (roles/cloudfunctions.developer)

  • Dienstkontonutzer (roles/iam.serviceAccountUser)

  • Storage-Objekt-Betrachter (roles/storage.objectViewer)

  • Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin), wenn die BigQuery-Standardverbindung verwendet wird, oder Browser (Rollen/Browser), wenn eine vorkonfigurierte Verbindung verwendet wird. 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, achten Sie darauf, dass die Verbindung am richtigen Standort erstellt wird und das zugehörige Dienstkonto die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker) für das Projekt hat.

Beschränkungen

  • Es dauert etwa 90 Sekunden, bis Remote-Funktionen nach ihrer Erstellung verfügbar sind.

  • Einfache Änderungen im Notebook, wie das Einfügen einer neuen Zelle oder das Umbenennen einer Variablen, kann dazu führen, dass die Remote-Funktion neu erstellt wird, auch wenn diese Änderungen keinen Bezug auf den Remote-Funktionscode haben.

  • BigQuery DataFrames unterscheidet keine personenbezogenen Daten, die Sie in den Code der Remote-Funktion aufnehmen. Der Remote-Funktionscode ist als undurchsichtiges Feld serialisiert, um ihn als Cloud Run Functions-Funktion bereitzustellen.

  • Cloud Run Functions-Funktionen (2. Generation), BigQuery-Verbindungen und von BigQuery DataFrames erstellte BigQuery-Remote-Funktionen bleiben inGoogle Clouderhalten. Wenn Sie diese Ressourcen nicht behalten möchten, müssen Sie sie separat mit einer entsprechenden Cloud Run-Funktion oder BigQuery-Oberfläche löschen.

  • Ein Projekt kann bis zu 1.000 Cloud Run Functions-Funktionen (2. Generation) gleichzeitig haben. Weitere Informationen finden Sie unter Kontingente für Cloud Run-Funktionen für alle Limits.

Beispiele für bigframes.pandas

Die folgenden Beispiele zeigen gängige Methoden zur Verwendung von bigframes.pandas.

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

Daten prüfen und bearbeiten

Sie können bigframes.pandas für Datenprüfungs- und Berechnungsvorgänge verwenden.
Das folgende Codebeispiel zeigt, wie Sie mit bigframes.pandas die Spalte body_mass_g prüfen, den Mittelwert body_mass berechnen und den Mittelwert body_mass nach species 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)
)

Bibliothek bigframes.bigquery verwenden

Neben den pandas-ähnlichen APIs bietet BigQuery DataFrames die bigframes.bigquery-Bibliothek. Diese Bibliothek bietet viele BigQuery-SQL-Funktionen, für die es möglicherweise kein Pandas-Äquivalent gibt.

Die folgenden Beispiele zeigen gängige Methoden zur Verwendung der bigframes.bigquery-Bibliothek.

Arraywerte verarbeiten

Mit der Funktion bigframes.bigquery.array_agg() 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() 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() 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

Verwenden Sie die Funktion bigframes.bigquery.sql_scalar(), um auf beliebige SQL-Syntax zuzugreifen, 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

Bibliothek bigframes.ml verwenden

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.

ML-Speicherorte

bigframes.ml 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 des Moduls bigframes.ml.preprocessing und des Moduls 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 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

Erstellen Sie Estimatoren zum Trainieren von Modellen in BigQuery DataFrames.

Clustering-Modelle

Erstellen Sie Estimatoren für Clustering-Modelle mit dem bigframes.ml.cluster-Modul.

  • 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

Erstellen Sie Estimatoren für Zerlegungsmodelle mit dem bigframes.ml.decomposition-Modul.

  • 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

Erstellen Sie Estimatoren für Ensemble-Modelle mit dem bigframes.ml.ensemble-Modul.

  • 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 Regressionsmodelle vom Typ „Zufalls-Gesamtstruktur“ 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

Erstellen Sie Estimatoren für Prognosemodelle mit dem bigframes.ml.forecasting-Modul.

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

Importierte Modelle

Erstellen Sie Estimatoren für importierte Modelle mit dem bigframes.ml.imported-Modul.

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

Erstellen Sie Estimatoren für LLMs mithilfe des bigframes.ml.llm-Moduls.

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

  • Verwenden Sie die PaLM2TextGenerator-Klasse, um PaLM2-Textgenerator-Modelle zu erstellen. Verwenden Sie diese Modelle für Aufgaben zur Textgenerierung.

  • Verwenden Sie die PaLM2TextEmbeddingGenerator-Klasse, um Modelle für PaLM2-Texteinbettungen zu erstellen. Verwenden Sie diese Modelle für Aufgaben zur Generierung von Texteinbettungen.

Sie können die

bigframes.ml.llm-Modul zum Erstellen von Estimatoren für Remote-Großsprachmodelle (LLMs).
Das folgende Codebeispiel zeigt die Verwendung der bigframes.ml.llm

GeminiTextGenerator-Klasse, 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-1.5-flash-002"
)

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:

Sie benötigen außerdem die folgenden IAM-Rollen im Projekt:

  • BigQuery Connection Admin (roles/bigquery.connectionAdmin)
  • Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin), wenn die BigQuery-Standardverbindung verwendet wird, oder Browser (Rollen/Browser), wenn eine vorkonfigurierte Verbindung verwendet wird. 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, achten Sie darauf, dass die Verbindung am richtigen Standort erstellt wird und das Dienstkonto die Rolle „Vertex AI-Nutzer“ (roles/aiplatform.user) für das Projekt hat.

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 IAM-Rolle „Vertex AI-Nutzer“ (roles/aiplatform.user) zugewiesen.

Pipelines erstellen

Erstellen Sie ML-Pipelines mit dem bigframes.ml.pipeline-Modul. 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.

Nächste Schritte