Benutzerdefinierte Funktionen in Python

Mit einer benutzerdefinierten Python-Funktion (User-defined Function, UDF) können Sie eine skalare Funktion in Python implementieren und in einer SQL-Abfrage verwenden. Python-UDFs ähneln SQL- und JavaScript-UDFs, bieten aber zusätzliche Funktionen. Mit Python-UDFs können Sie Drittanbieterbibliotheken aus dem Python Package Index (PyPI) installieren und über eine Cloud-Ressourcenverbindung auf externe Dienste zugreifen.

Python-UDFs werden auf von BigQuery verwalteten Ressourcen erstellt und ausgeführt.

Beschränkungen

• python-3.11 ist die einzige unterstützte Laufzeit.
• Sie können keine temporäre Python-UDF erstellen.
• Sie können keine Python-UDF mit einer materialisierten Ansicht verwenden.
• Die Ergebnisse einer Abfrage, die eine Python-UDF aufruft, werden nicht im Cache gespeichert, da der Rückgabewert einer Python-UDF immer als nicht deterministisch angenommen wird.
• Python-UDFs werden in INFORMATION_SCHEMA-Ansichten nicht vollständig unterstützt.
• Sie können keine Python-UDF mit der Routine API erstellen oder aktualisieren.
• VPC Service Controls werden nicht unterstützt.
• Vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK) werden nicht unterstützt.
• Die folgenden Datentypen werden nicht unterstützt: JSON, RANGE, INTERVAL und GEOGRAPHY.
• Container, in denen Python-UDFs ausgeführt werden, können nur mit bis zu 2 vCPUs und 8 GiB konfiguriert werden.

Erforderliche IAM-Rollen

Die erforderlichen IAM-Rollen hängen davon ab, ob Sie Inhaber oder Nutzer einer benutzerdefinierten Python-Funktion sind. Ein Python-UDF-Inhaber erstellt oder aktualisiert in der Regel eine UDF. Ein Python-UDF-Nutzer ruft eine UDF auf, die von einer anderen Person erstellt wurde.

Zusätzliche Rollen sind auch erforderlich, wenn Sie eine Python-UDF erstellen oder ausführen, die auf eine Cloud-Ressourcenverbindung verweist.

UDF-Inhaber

Wenn Sie eine Python-UDF erstellen oder aktualisieren, sollten die folgenden vordefinierten IAM-Rollen für die entsprechende Ressource gewährt werden:

UDF-Nutzer

Wenn Sie eine Python-UDF aufrufen, sollten die folgenden vordefinierten IAM-Rollen für die entsprechende Ressource gewährt werden:

Weitere Informationen zu Rollen in BigQuery finden Sie unter Vordefinierte IAM-Rollen.

Nichtflüchtige Python-UDF erstellen

Beachten Sie beim Erstellen einer Python-UDF die folgenden Regeln:

• Der Hauptteil der Python-UDF muss ein in Anführungszeichen gesetztes Stringliteral sein, das den Python-Code darstellt. Weitere Informationen zu Stringliteralen in Anführungszeichen finden Sie unter Formate für Literale in Anführungszeichen.

• Der Hauptteil der Python-UDF muss eine Python-Funktion enthalten, die im entry_point-Argument in der Optionsliste der Python-UDF verwendet wird.

• Eine Python-Laufzeitversion muss in der Option runtime_version angegeben werden. Die einzige unterstützte Python-Laufzeitversion ist python-3.11. Eine vollständige Liste der verfügbaren Optionen finden Sie in der Liste der Funktionsoptionen für die CREATE FUNCTION-Anweisung.

Verwenden Sie zum Erstellen einer persistenten Python-UDF die CREATE FUNCTION-Anweisung ohne das Schlüsselwort TEMP oder TEMPORARY. Verwenden Sie die Anweisung DROP FUNCTION, um eine persistente Python-UDF zu löschen.

Wenn Sie eine Python-UDF mit der CREATE FUNCTION-Anweisung erstellen, erstellt oder aktualisiert BigQuery ein Container-Image, das auf einem Basis-Image basiert. Der Container wird auf dem Basis-Image mit Ihrem Code und allen angegebenen Paketabhängigkeiten erstellt. Das Erstellen des Containers ist ein langwieriger Vorgang. Die erste Abfrage nach dem Ausführen der CREATE FUNCTION-Anweisung wartet möglicherweise automatisch, bis das Bild fertig ist. Ohne externe Abhängigkeiten sollte das Container-Image in der Regel in weniger als einer Minute erstellt werden.

Beispiel

Wenn Sie ein Beispiel für das Erstellen einer persistenten Python-UDF sehen möchten, wählen Sie eine der folgenden Optionen aus:

import bigframes.pandas as bpd

# Set BigQuery DataFrames options
bpd.options.bigquery.project = your_gcp_project_id
bpd.options.bigquery.location = "US"

# BigQuery DataFrames gives you the ability to turn your custom functions
# into a BigQuery Python UDF. One can find more details about the usage and
# the requirements via `help` command.
help(bpd.udf)

# Read a table and inspect the column of interest.
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
df["body_mass_g"].peek(10)

# Define a custom function, and specify the intent to turn it into a
# BigQuery Python UDF. Let's try a `pandas`-like use case in which we want
# to apply a user defined function to every value in a `Series`, more
# specifically bucketize the `body_mass_g` value of the penguins, which is a
# real number, into a category, which is a string.
@bpd.udf(
    dataset=your_bq_dataset_id,
    name=your_bq_routine_id,
)
def get_bucket(num: float) -> str:
    if not num:
        return "NA"
    boundary = 4000
    return "at_or_above_4000" if num >= boundary else "below_4000"

# Then we can apply the udf on the `Series` of interest via
# `apply` API and store the result in a new column in the DataFrame.
df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket))

# This will add a new column `body_mass_bucket` in the DataFrame. You can
# preview the original value and the bucketized value side by side.
df[["body_mass_g", "body_mass_bucket"]].peek(10)

# The above operation was possible by doing all the computation on the
# cloud through an underlying BigQuery Python UDF that was created to
# support the user's operations in the Python code.

# The BigQuery Python UDF created to support the BigQuery DataFrames
# udf can be located via a property `bigframes_bigquery_function`
# set in the udf object.
print(f"Created BQ Python UDF: {get_bucket.bigframes_bigquery_function}")

# If you have already defined a custom function in BigQuery, either via the
# BigQuery Google Cloud Console or with the `udf` decorator,
# or otherwise, you may use it with BigQuery DataFrames with the
# `read_gbq_function` method. More details are available via the `help`
# command.
help(bpd.read_gbq_function)

existing_get_bucket_bq_udf = get_bucket.bigframes_bigquery_function

# Here is an example of using `read_gbq_function` to load an existing
# BigQuery Python UDF.
df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
get_bucket_function = bpd.read_gbq_function(existing_get_bucket_bq_udf)

df = df.assign(body_mass_bucket=df["body_mass_g"].apply(get_bucket_function))
df.peek(10)

# Let's continue trying other potential use cases of udf. Let's say we
# consider the `species`, `island` and `sex` of the penguins sensitive
# information and want to redact that by replacing with their hash code
# instead. Let's define another scalar custom function and decorate it
# as a udf. The custom function in this example has external package
# dependency, which can be specified via `packages` parameter.
@bpd.udf(
    dataset=your_bq_dataset_id,
    name=your_bq_routine_id,
    packages=["cryptography"],
)
def get_hash(input: str) -> str:
    from cryptography.fernet import Fernet

    # handle missing value
    if input is None:
        input = ""

    key = Fernet.generate_key()
    f = Fernet(key)
    return f.encrypt(input.encode()).decode()

# We can use this udf in another `pandas`-like API `map` that
# can be applied on a DataFrame
df_redacted = df[["species", "island", "sex"]].map(get_hash)
df_redacted.peek(10)

# If the BigQuery routine is no longer needed, we can clean it up
# to free up any cloud quota
session = bpd.get_global_session()
session.bqclient.delete_routine(f"{your_bq_dataset_id}.{your_bq_routine_id}")

Vektorisierte Python-UDF erstellen

Sie können Ihre Python-UDF so implementieren, dass sie mithilfe der Vektorisierung einen Batch von Zeilen anstelle einer einzelnen Zeile verarbeitet. Die Vektorisierung kann die Abfrageleistung verbessern.

Wenn Sie das Batching-Verhalten steuern möchten, geben Sie mit der Option max_batching_rows in der Optionsliste die maximale Anzahl von Zeilen in jedem Batch an.CREATE OR REPLACE FUNCTION Wenn Sie max_batching_rows angeben, bestimmt BigQuery die Anzahl der Zeilen in einem Batch bis zum Limit von max_batching_rows. Wenn max_batching_rows nicht angegeben ist, wird die Anzahl der Zeilen für den Batch automatisch festgelegt.

Eine vektorisierte Python-UDF hat ein einzelnes pandas.DataFrame-Argument, das annotiert werden muss. Das pandas.DataFrame-Argument hat dieselbe Anzahl von Spalten wie die Python-UDF-Parameter, die in der CREATE FUNCTION-Anweisung definiert sind. Die Spaltennamen im Argument pandas.DataFrame haben dieselben Namen wie die Parameter der UDF.

Ihre Funktion muss entweder ein pandas.Series oder ein einspaltiges pandas.DataFrame mit derselben Anzahl von Zeilen wie die Eingabe zurückgeben.

Im folgenden Beispiel wird eine vektorisierte Python-UDF mit dem Namen multiplyInputs mit zwei Parametern erstellt: x und y.

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende CREATE FUNCTION-Anweisung ein:

   CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyVectorized(x FLOAT64, y FLOAT64)
   RETURNS FLOAT64
   LANGUAGE python
   OPTIONS(runtime_version="python-3.11", entry_point="vectorized_multiply")
   AS r'''
   import pandas as pd
   
   def vectorized_multiply(df: pd.DataFrame):
     return df['x'] * df['y']
   
   ''';

   Ersetzen Sie PROJECT_ID.DATASET_ID durch Ihre Projekt-ID und Dataset-ID.

   Der Aufruf der UDF ist derselbe wie im vorherigen Beispiel.

3. Klicken Sie auf play_circle_filled Ausführen.

Von Python-UDFs unterstützte Datentypen

In der folgenden Tabelle wird die Zuordnung zwischen BigQuery-Datentypen, Python-Datentypen und Pandas-Datentypen definiert:

Unterstützte Laufzeitversionen

BigQuery-Python-UDFs unterstützen die python-3.11-Laufzeit. Diese Python-Version enthält einige zusätzliche vorinstallierte Pakete. Bei Systembibliotheken prüfen Sie das Laufzeit-Basis-Image.

Drittanbieterpakete verwenden

Mit der Optionsliste CREATE FUNCTION können Sie andere Module als die, die von der Python-Standardbibliothek und vorinstallierten Paketen bereitgestellt werden, verwenden. Sie können Pakete aus dem Python-Paketindex (PyPI) installieren oder Python-Dateien aus Cloud Storage importieren.

Paket aus dem Python-Paketindex installieren

Wenn Sie ein Paket installieren, müssen Sie den Paketnamen angeben. Optional können Sie die Paketversion mit Python-Paketversionsspezifizierern angeben. Wenn sich das Paket in der Laufzeit befindet, wird es verwendet, sofern in der Optionsliste CREATE FUNCTION keine bestimmte Version angegeben ist. Wenn keine Paketversion angegeben ist und das Paket nicht in der Laufzeitumgebung enthalten ist, wird die neueste verfügbare Version verwendet. Es werden nur Pakete mit dem binären Format „Wheels“ unterstützt.

Im folgenden Beispiel wird gezeigt, wie Sie eine Python-UDF erstellen, die das Paket scipy mit der Optionsliste CREATE OR REPLACE FUNCTION installiert:

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende CREATE FUNCTION-Anweisung ein:

   CREATE FUNCTION `PROJECT_ID.DATASET_ID`.area(radius FLOAT64)
   RETURNS FLOAT64 LANGUAGE python
   OPTIONS (entry_point='area_handler', runtime_version='python-3.11', packages=['scipy==1.15.3'])
   AS r"""
   import scipy
   
   def area_handler(radius):
     return scipy.constants.pi*radius*radius
   """;
   
   SELECT `PROJECT_ID.DATASET_ID`.area(4.5);

   Ersetzen Sie PROJECT_ID.DATASET_ID durch Ihre Projekt-ID und Dataset-ID.

3. Klicken Sie auf play_circle_filled Ausführen.

Zusätzliche Python-Dateien als Bibliotheken importieren

Sie können Ihre Python-UDFs mit der Funktionsoptionsliste erweitern, indem Sie Python-Dateien aus Cloud Storage importieren.

Im Python-Code Ihrer UDF können Sie die Python-Dateien aus Cloud Storage als Module importieren. Verwenden Sie dazu die Importanweisung, gefolgt vom Pfad zum Cloud Storage-Objekt. Wenn Sie beispielsweise gs://BUCKET_NAME/path/to/lib1.py importieren, lautet die Importanweisung import path.to.lib1.

Der Python-Dateiname muss eine Python-Kennzeichnung sein. Jeder folder-Name im Objektnamen (nach dem /) sollte eine gültige Python-Kennzeichnung sein. Im ASCII-Bereich (U+0001..U+007F) können die folgenden Zeichen in Bezeichnern verwendet werden:

• Groß- und Kleinbuchstaben A bis Z.
• Unterstriche.
• Die Ziffern 0 bis 9, aber eine Zahl darf nicht als erstes Zeichen in der Kennung stehen.

Im folgenden Beispiel wird gezeigt, wie Sie eine Python-UDF erstellen, die das Clientbibliotheks-Paket lib1.py aus einem Cloud Storage-Bucket mit dem Namen my_bucket importiert:

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende CREATE FUNCTION-Anweisung ein:

   CREATE FUNCTION `PROJECT_ID.DATASET_ID`.myFunc(a FLOAT64, b STRING)
   RETURNS STRING LANGUAGE python
   OPTIONS (
   entry_point='compute', runtime_version='python-3.11',
   library=['gs://my_bucket/path/to/lib1.py'])
   AS r"""
   import path.to.lib1 as lib1
   
   def compute(a, b):
     # doInterestingStuff is a function defined in
     # gs://my_bucket/path/to/lib1.py
     return lib1.doInterestingStuff(a, b);
   
   """;

   Ersetzen Sie PROJECT_ID.DATASET_ID durch Ihre Projekt-ID und Dataset-ID.

3. Klicken Sie auf play_circle_filled Ausführen.

Containerlimits für Python-UDFs konfigurieren

Mit der Optionsliste CREATE FUNCTION können Sie CPU- und Arbeitsspeicherlimits für Container festlegen, in denen Python-UDFs ausgeführt werden.

Standardmäßig beträgt der jeder Containerinstanz zugewiesene Speicher 512 MiB und die zugewiesene CPU 0,33 vCPU.

Im folgenden Beispiel wird eine Python-UDF erstellt, in der mit der Optionsliste CREATE FUNCTION Containerlimits angegeben werden:

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Geben Sie im Abfrageeditor die folgende CREATE FUNCTION-Anweisung ein:

   CREATE FUNCTION `PROJECT_ID.DATASET_ID`.resizeImage(image BYTES)
   RETURNS BYTES LANGUAGE python
   OPTIONS (entry_point='resize_image', runtime_version='python-3.11',
   packages=['Pillow==11.2.1'], container_memory='2Gi', container_cpu=1)
   AS r"""
   import io
   from PIL import Image
   
   def resize_image(image_bytes):
     img = Image.open(io.BytesIO(image_bytes))
   
     resized_img = img.resize((256, 256), Image.Resampling.LANCZOS)
     output_stream = io.BytesIO()
     resized_img.convert('RGB').save(output_stream, format='JPEG')
     return output_stream.getvalue()
   """;

   Ersetzen Sie PROJECT_ID.DATASET_ID durch Ihre Projekt-ID und Dataset-ID.

3. Klicken Sie auf play_circle_filled Ausführen.

Unterstützte CPU-Werte

Python-UDFs unterstützen CPU-Bruchteilwerte zwischen 0.33 und 1.0 sowie nicht fraktionierte CPU-Werte von 1 und 2. Gleitkomma-Eingabewerte werden auf zwei Dezimalstellen gerundet, bevor sie auf den Container angewendet werden.

Unterstützte Erinnerungswerte

Python-UDF-Container unterstützen Speicherwerte im folgenden Format: <integer_number><unit>. Die Einheit muss einer der folgenden Werte sein: Mi, M, Gi, G. Die Mindestspeichermenge, die Sie konfigurieren können, beträgt 256 Mebibyte (256 Mi). Sie können maximal 8 Gibibyte (8 Gi) Arbeitsspeicher konfigurieren.

Je nach ausgewähltem Arbeitsspeicherwert müssen Sie auch die Mindestanzahl an CPUs angeben. In der folgenden Tabelle sind die Mindest-CPU-Werte für die einzelnen Speicherwerte aufgeführt:

Google Cloud oder Onlinedienste in Python-Code aufrufen

Eine Python-UDF greift über das Dienstkonto der Cloud-Ressourcenverbindung auf einen Google Cloud -Dienst oder einen externen Dienst zu. Dem Dienstkonto der Verbindung müssen Berechtigungen für den Zugriff auf den Dienst erteilt werden. Die erforderlichen Berechtigungen hängen vom Dienst ab, auf den zugegriffen wird, und von den APIs, die von Ihrem Python-Code aufgerufen werden.

Wenn Sie eine Python-UDF ohne Verwendung einer Cloud-Ressourcenverbindung erstellen, wird die Funktion in einer Umgebung ausgeführt, die den Netzwerkzugriff blockiert. Wenn Ihre UDF auf Onlinedienste zugreift, müssen Sie sie mit einer Cloud-Ressourcenverbindung erstellen. Andernfalls wird der Zugriff der UDF auf das Netzwerk blockiert, bis ein internes Zeitlimit für die Verbindung erreicht ist.

Im folgenden Beispiel wird gezeigt, wie Sie über eine Python-UDF auf den Cloud Translation-Dienst zugreifen. In diesem Beispiel gibt es zwei Projekte: ein Projekt mit dem Namen my_query_project, in dem Sie die UDF und die Cloud-Ressourcenverbindung erstellen, und ein Projekt mit dem Namen my_translate_project, in dem Sie Cloud Translation ausführen.

Cloud-Ressourcen-Verbindung erstellen

Zuerst erstellen Sie eine Cloud-Ressourcenverbindung in my_query_project. Folgen Sie zum Erstellen der Cloud-Ressourcenverbindung der Anleitung auf der Seite Cloud-Ressourcenverbindung erstellen.

Nachdem Sie die Verbindung erstellt haben, öffnen Sie sie und kopieren Sie im Bereich Verbindungsinformationen die Dienstkonto-ID. Sie benötigen diese ID, wenn Sie Berechtigungen für die Verbindung konfigurieren. Wenn Sie eine Verbindungsressource erstellen, erstellt BigQuery ein eindeutiges Systemdienstkonto und ordnet es der Verbindung zu.

Dem Dienstkonto der Verbindung Zugriff gewähren

Damit das Dienstkonto für die Verbindung von Cloud-Ressourcen auf Ihre Projekte zugreifen kann, weisen Sie dem Dienstkonto die Rolle Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) in my_query_project und die Rolle Cloud Translation API User (roles/cloudtranslate.user) in my_translate_project zu.

1. Rufen Sie die IAM-Seite auf.

   IAM aufrufen

2. Prüfen Sie, ob my_query_project ausgewählt ist.

3. Klicken Sie auf person_addZugriff gewähren.

4. Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID der Cloud-Ressourcenverbindung ein, die Sie zuvor kopiert haben.

5. Wählen Sie im Feld Rolle auswählen die Option Dienstnutzung und dann Nutzer der Dienstnutzung aus.

6. Klicken Sie auf Speichern.

7. Wählen Sie in der Projektauswahl my_translate_project aus.

8. Rufen Sie die IAM-Seite auf.

   IAM aufrufen

9. Klicken Sie auf person_addZugriff gewähren.

10. Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID der Cloud-Ressourcenverbindung ein, die Sie zuvor kopiert haben.

11. Wählen Sie im Feld Rolle auswählen die Option Cloud Translation und dann Cloud Translation API-Nutzer aus.

12. Klicken Sie auf Speichern.

Python-UDF erstellen, die den Cloud Translation-Dienst aufruft

Erstellen Sie in my_query_project eine Python-UDF, die den Cloud Translation-Dienst über Ihre Cloud-Ressourcenverbindung aufruft.

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Geben Sie die folgende CREATE FUNCTION-Anweisung in den Abfrageeditor ein:

   CREATE FUNCTION `PROJECT_ID.DATASET_ID`.translate_to_es(x STRING)
   RETURNS STRING LANGUAGE python
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (entry_point='do_translate', runtime_version='python-3.11', packages=['google-cloud-translate>=3.11', 'google-api-core'])
   AS r"""
   
   from google.api_core.retry import Retry
   from google.cloud import translate
   
   project = "my_translate_project"
   translate_client = translate.TranslationServiceClient()
   
   def do_translate(x : str) -> str:
   
       response = translate_client.translate_text(
           request={
               "parent": f"projects/{project}/locations/us-central1",
               "contents": [x],
               "target_language_code": "es",
               "mime_type": "text/plain",
           },
           retry=Retry(),
       )
       return response.translations[0].translated_text
   
   """;
   
   -- Call the UDF.
   WITH text_table AS
     (SELECT "Hello" AS text
     UNION ALL
     SELECT "Good morning" AS text
     UNION ALL
     SELECT "Goodbye" AS text)
   SELECT text,
   `PROJECT_ID.DATASET_ID`.translate_to_es(text) AS translated_text
   FROM text_table;

   Ersetzen Sie Folgendes:

   • PROJECT_ID.DATASET_ID: Ihre Projekt-ID und Dataset-ID
   • REGION.CONNECTION_ID: die Region und Verbindungs-ID Ihrer Verbindung

3. Klicken Sie auf play_circle_filled Ausführen.

   Die Ausgabe sollte so aussehen:

   +--------------------------+-------------------------------+
   | text                     | translated_text               |
   +--------------------------+-------------------------------+
   | Hello                    | Hola                          |
   | Good morning             | Buen dia                      |
   | Goodbye                  | Adios                         |
   +--------------------------+-------------------------------+
   

Unterstützte Standorte

Python-UDFs werden in allen multiregionalen und regionalen BigQuery-Standorten unterstützt.

Preise

Python-UDFs werden ohne zusätzliche Gebühren angeboten.

Wenn die Abrechnung aktiviert ist, gilt Folgendes:

• Gebühren für Python-UDFs werden über die BigQuery Services-Artikelnummer abgerechnet.
• Die Gebühren sind proportional zur Menge an Rechenleistung und Arbeitsspeicher, die beim Aufrufen der Python-UDF verbraucht werden.
• Kunden, die Python-UDFs verwenden, werden auch die Kosten für das Erstellen oder Neuerstellen des UDF-Container-Images in Rechnung gestellt. Diese Gebühr ist proportional zu den Ressourcen, die zum Erstellen des Images mit Kundencode und Abhängigkeiten verwendet werden.
• Wenn Python-UDFs zu ausgehendem Traffic in externen oder Internetnetzwerken führen, wird Ihnen auch eine Gebühr für ausgehenden Internettraffic der Premium-Stufe von Cloud Networking in Rechnung gestellt.