Python-Funktionen für BigQuery DataFrames anpassen

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. Diese Unterstützung für die Erweiterbarkeit ermöglicht Ihnen Vorgänge, die mit BigQuery DataFrames und SQL-APIs nicht möglich sind. So können Sie möglicherweise Open-Source-Bibliotheken nutzen.

Es gibt zwei Varianten dieses Erweiterungsmechanismus: benutzerdefinierte Funktionen und Remote-Funktionen.

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.

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 bigframes.pandas.udf.

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.

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 Befehl bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) bereinigen.

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 zugehörigen 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.

Voraussetzungen

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

Wenn Sie Remote-Funktionen von BigQuery DataFrames verwenden, benötigen Sie 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. Sie können diese Anforderung vermeiden, indem Sie die Option bigframes.pandas.options.bigquery.skip_bq_connection_check auf True setzen. In diesem Fall wird die Verbindung (Standard oder vorkonfiguriert) unverändert verwendet, ohne dass geprüft wird, ob sie besteht oder eine Berechtigung vorhanden ist. Wenn Sie die vorkonfigurierte Verbindung verwenden und die Verbindungsprüfung überspringen, prüfen Sie Folgendes:

  • Die Verbindung wird am richtigen Ort erstellt.
  • Wenn Sie Remote-Funktionen von BigQuery DataFrames verwenden, hat das Dienstkonto die Cloud Run-Aufruferrolle (roles/run.invoker) für das Projekt.

Verbindungen ansehen und verwalten

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. Klicken Sie im linken Bereich auf  Explorer:

    Hervorgehobener Button für den Explorer-Bereich.

  4. Maximieren Sie im Bereich Explorer das Projekt und klicken Sie dann auf 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. Klicken Sie im linken Bereich auf  Explorer:

    Hervorgehobener Button für den Explorer-Bereich.

  4. Maximieren Sie im Bereich Explorer das Projekt und klicken Sie dann auf Datasets.

  5. Klicken Sie auf das Dataset, in dem Sie die Remote-Funktion erstellt haben.

  6. Klicken Sie auf den Tab 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 (Bereitstellungstyp für Funktionen).

  4. Funktionen, die von BigQuery DataFrames erstellt wurden, erkennen Sie am Präfix bigframes im Funktionsnamen.

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.

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 vertrauliche Inhalte nur mit Vorsicht einfügen.
  • Ein Projekt kann bis zu 1.000 Cloud Run-Funktionen gleichzeitig in einer Region haben. Weitere Informationen finden Sie unter Kontingente.

Nächste Schritte