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 Umfang für BigQuery DataFrames-Objekte ausführen können. Diese 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 Erweiterbarkeitsmechanismus: 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 (Vorschau), können Sie Ihre benutzerdefinierte Python-Funktion in eine Python-UDF umwandeln. Ein Beispiel für die Verwendung finden Sie unter Permanente 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 bigquery_connection Parameter in Ihrem Projekt angeben, müssen Sie auch die BigQuery Connection API aktivieren.

Bereinigen

Sie können die Cloud-Artefakte nicht nur direkt in der Google Cloud Console oder mit anderen Tools bereinigen, sondern auch die BigQuery DataFrames-UDFs, die mit einem expliziten Namensargument erstellt wurden, mit dem bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) Befehl bereinigen.

Beschränkungen

  • Der Code in der UDF muss in sich geschlossen sein. Das bedeutet, er darf keine Verweise auf einen Import oder eine Variable enthalten, die außerhalb des Funktionskörpers 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 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. Das gilt auch dann, 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 sensible Inhalte nur mit Vorsicht einfügen.
  • Ein Projekt kann an einem BigQuery-Standort bis zu 1.000 Cloud Run-Funktionen gleichzeitig haben.

Die BigQuery DataFrames-UDF stellt eine benutzerdefinierte BigQuery-Python-Funktion bereit. Es gelten die entsprechenden Beschrä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 Standard verbindung 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 BigQuery DataFrames-Remote-Funktionen 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 wurde am richtigen Standort erstellt.
  • Wenn Sie BigQuery DataFrames-Remote-Funktionen verwenden, hat das Dienstkonto die Rolle „Cloud Run Invoker“ (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 erstellt, oder sie werden in einem anonymen Dataset, einer Art verborgenem Dataset, erstellt. 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-Funktionen auf und verwalten sie:

  1. Rufen Sie die Seite Cloud Run auf.

    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 Bereitstellungstyp der Funktion.

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

Bereinigen

Sie können die Cloud-Artefakte nicht nur direkt in der Google Cloud Konsole oder mit anderen Tools bereinigen, sondern auch 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 frühere Sitzung mit session_id den bigframes.pandas.clean_up_by_session_id(session_id) Befehl.

Sie können auch die BigQuery-Remote-Funktionen, die mit einem expliziten Namensargument erstellt wurden, und die zugehörigen Cloud Run-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 geringfügigen Änderungen am und um den Funktionscode 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, wird die Remote-Funktion möglicherweise neu erstellt. Das gilt auch dann, 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 sensible Inhalte nur mit Vorsicht einfügen.
  • Ein Projekt kann in einer Region bis zu 1.000 Cloud Run-Funktionen gleichzeitig haben. Weitere Informationen finden Sie unter Kontingente.

Nächste Schritte