Python-Funktionen für BigQuery DataFrames anpassen

Wenn Sie Python-Funktionen für BigQuery DataFrames anpassen, können Sie Ihren Code in skalierbare BigQuery-Artefakte wie benutzerdefinierte Funktionen (UDFs) oder Remote-Funktionen umwandeln. Sie können diese benutzerdefinierten Funktionen bereitstellen, um Open-Source-Bibliotheken zu nutzen und Vorgänge auszuführen, die über die Funktionen von Standard-SQL-APIs hinausgehen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen für die Aufgaben in diesem Dokument haben:

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 Nichtflüchtige 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 Console 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 eigenständig sein, d. h., er darf keine Verweise auf einen Import oder eine Variable enthalten, die außerhalb des Funktionsrumpfs definiert sind.
  • Der Code in der UDF muss mit Python 3.11 kompatibel sein, da dies die Umgebung ist, in der der Code in der Cloud ausgeführt wird.
  • Wenn Sie den UDF-Definitionscode nach einfachen Änderungen am Funktionscode noch einmal ausführen, z. B. nach dem Umbenennen einer Variablen oder dem Einfügen einer neuen Zeile, 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 vertrauliche Inhalte nur mit Vorsicht einfügen.
  • Ein Projekt kann bis zu 1.000 Cloud Run-Funktionen 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.

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, 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 Standort erstellt.
  • Wenn Sie BigQuery DataFrames-Remote-Funktionen verwenden, hat das Dienstkonto die Rolle „Cloud Run-Aufrufer“ (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, das ein Typ von verborgenem Dataset ist. Wenn Sie beim Erstellen einer Remote-Funktion keinen Namen festlegen, verwendet BigQuery DataFrames einen Standardnamen, 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. Klicke auf den Tab Abläufe.

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

  1. Zur Seite „Cloud Run“

    Zu Cloud Run

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

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

  4. Suchen Sie nach Funktionsnamen mit dem Präfix bigframes, um von BigQuery DataFrames erstellte Funktionen zu identifizieren.

Bereinigen

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

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

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 verfügbar sind. Zusätzliche Paketabhängigkeiten können die Latenz erhöhen.
  • Wenn Sie den Code für die Definition der Remote-Funktion nach einfachen Änderungen im und um den Funktionscode herum noch einmal ausführen, z. B. nach dem Umbenennen einer Variablen, dem Einfügen einer neuen Zeile oder dem Einfügen einer neuen Zelle im Notebook, kann dies dazu führen, 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 vorsichtig sein, wenn Sie 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.

Nächste Schritte