Mit benutzerdefinierten Funktionen in Python arbeiten

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.
• Assured Workloads 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 4 vCPUs und 16 GiB konfiguriert werden.
• Das Verschlüsseln von Python-UDF-Code mit vom Kunden verwalteten Verschlüsselungsschlüsseln (Customer-Managed Encryption Keys, CMEK) wird nicht unterstützt.
• Python-UDFs unterstützen VPC Service Controls, aber VPC-Netzwerke werden nicht unterstützt.

Erforderliche Rollen

Die erforderlichen IAM-Rollen hängen davon ab, ob Sie Inhaber oder Nutzer einer benutzerdefinierten Python-Funktion (UDF) sind.

UDF-Inhaber

Ein Python-UDF-Inhaber erstellt oder aktualisiert in der Regel eine UDF. Zusätzliche Rollen sind auch erforderlich, wenn Sie eine Python-UDF erstellen, die auf eine Cloud-Ressourcenverbindung verweist. Diese Verbindung ist nur erforderlich, wenn in Ihrer UDF die Klausel WITH CONNECTION verwendet wird, um auf einen externen Dienst zuzugreifen.

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen oder Aktualisieren einer Python-UDF benötigen:

• BigQuery-Datenbearbeiter (roles/bigquery.dataEditor) für das Dataset
• BigQuery-Jobnutzer (roles/bigquery.jobUser) für das Projekt
• BigQuery-Verbindungsadministrator (roles/bigquery.connectionAdmin) für das Projekt

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Erstellen oder Aktualisieren einer Python-UDF erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

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

UDF-Nutzer

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 aufrufen, die auf eine Cloud-Ressourcenverbindung verweist.

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen einer von einer anderen Person erstellten Python-UDF benötigen:

• BigQuery-Nutzer (roles/bigquery.user) für das Projekt
• BigQuery Data Viewer (roles/bigquery.dataViewer) für das Dataset
• BigQuery-Verbindungsnutzer (roles/bigquery.connectionUser) für die Verbindung

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Aufrufen einer von einer anderen Person erstellten Python-UDF erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

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.

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}")

Container-Build-Status

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. Bei der ersten Abfrage nach dem Ausführen der CREATE FUNCTION-Anweisung wird gewartet, bis der Image-Build abgeschlossen ist. Wenn keine externen Abhängigkeiten vorhanden sind, wird das Container-Image in der Regel in weniger als einer Minute erstellt.

Die Größe aller Python-UDF-Container pro Projekt und Region ist auf insgesamt 10 GiB beschränkt. Weitere Informationen finden Sie unter Limits für benutzerdefinierte Funktionen für persistente UDFs. Der Containerbuild schlägt fehl, wenn Ihr Projekt das Kontingent erreicht hat.

Wählen Sie eine der folgenden Optionen aus, um den Status Ihres Container-Builds aufzurufen:

Vektorisierte Python-UDF erstellen

Sie können Ihre Python-UDF so implementieren, dass sie einen Batch von Zeilen anstelle einer einzelnen Zeile verarbeitet. Dazu verwenden Sie die Vektorisierung. Die Vektorisierung kann die Abfrageleistung verbessern. Sie können eine vektorisierte UDF mit Pandas oder Apache Arrow erstellen.

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 ermittelt.

Pandas verwenden

Eine vektorisierte Python-UDF hat ein einzelnes pandas.DataFrame-Argument, das annotiert werden muss. Das Argument pandas.DataFrame hat dieselbe Anzahl von Spalten wie die Python-UDF-Parameter, die in der CREATE FUNCTION-Anweisung definiert sind. Die Spaltennamen im pandas.DataFrame-Argument 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.

Apache Arrow verwenden

Im folgenden Beispiel wird die RecordBatch-Schnittstelle von Apache Arrow verwendet. Wenn Sie die RecordBatch-Schnittstelle verwenden, übergibt die Funktion einen Batch von Zeilen mit Spalten gleicher Länge an den Einstiegspunkt. Im folgenden Beispiel wird Apache Arrow verwendet, um eine vektorisierte Python-UDF mit dem Namen multiplyVectorizedArrow zu erstellen.

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`.multiplyVectorizedArrow(x FLOAT64, y FLOAT64)
   RETURNS FLOAT64
   LANGUAGE python
   OPTIONS(
     runtime_version="python-3.11",
     entry_point="vectorized_multiply_arrow"
   )
   AS r'''
   import pyarrow as pa
   import pyarrow.compute as pc
   
   def vectorized_multiply_arrow(batch: pa.RecordBatch):
       # Access columns directly from the Arrow RecordBatch
       x = batch.column('x')
       y = batch.column('y')
   
       # Use pyarrow.compute for vectorized operations
       return pc.multiply(x, y)
   ''';

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

   Das Aufrufen der UDF ist dasselbe wie in den vorherigen Beispielen.

3. Klicken Sie auf play_circle_filled Ausführen.

Python-UDF aufrufen

Wenn Sie die Berechtigung zum Aufrufen einer Python-UDF haben, können Sie sie wie jede andere Funktion aufrufen. Wenn Sie eine Funktion verwenden möchten, die in einem anderen Projekt definiert ist, verwenden Sie den vollständig qualifizierten Namen der Funktion. Wenn Sie beispielsweise eine XML-Extraktionsfunktion namens cw_xml_extract in einem anderen Projekt aufrufen möchten, führen Sie die folgenden Schritte aus.

import textwrap
from typing import Tuple

import bigframes.pandas as bpd
import pandas as pd
import pyarrow as pa


# Using partial ordering mode enables more efficient query optimizations.
bpd.options.bigquery.ordering_mode = "partial"


def call_python_udf(
    project_id: str, location: str,
) -> Tuple[pd.Series, bpd.Series]:
    # Set the billing project to use for queries. This step is optional, as the
    # project can be inferred from your environment in many cases.
    bpd.options.bigquery.project = project_id  # "your-project-id"

    # Since this example works with local data, set a processing location.
    bpd.options.bigquery.location = location  # "US"

    # Create a sample series.
    xml_series = pd.Series(
        [
            textwrap.dedent(
                """
                <book id="1">
                    <title>The Great Gatsby</title>
                    <author>F. Scott Fitzgerald</author>
                </book>
                """
            ),
            textwrap.dedent(
                """
                <book id="2">
                    <title>1984</title>
                    <author>George Orwell</author>
                </book>
                """
            ),
            textwrap.dedent(
                """
                <book id="3">
                    <title>Brave New World</title>
                    <author>Aldous Huxley</author>
                </book>
                """
            ),
        ],
        dtype=pd.ArrowDtype(pa.string()),
    )
    df = pd.DataFrame({"xml": xml_series})

    # Use the BigQuery Accessor, which is automatically registered on pandas
    # DataFrames when you import bigframes.  This example uses a function that
    # has been deployed to bigquery-utils for demonstration purposes. To use in
    # production, deploy the function at
    # https://github.com/GoogleCloudPlatform/bigquery-utils/blob/master/udfs/community/cw_xml_extract.sqlx
    # to your own project.
    titles_pandas = df.bigquery.sql_scalar(
        "`bqutil`.`fn`.cw_xml_extract({xml}, '//title/text()')",
    )

    # Alternatively, call read_gbq_function to get a pointer to the function
    # that can be applied on BigQuery DataFrames objects.
    cw_xml_extract = bpd.read_gbq_function("bqutil.fn.cw_xml_extract")
    xml_bigframes = bpd.read_pandas(xml_series)

    xpath_query = "//title/text()"
    titles_bigframes = xml_bigframes.apply(cw_xml_extract, args=(xpath_query,))
    return titles_pandas, titles_bigframes

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. Prüfen Sie bei Systembibliotheken das Laufzeit-Basis-Image.

Drittanbieterpakete verwenden

Mit der Optionsliste CREATE FUNCTION können Sie andere Module als die von der Python-Standardbibliothek bereitgestellten und vorinstallierten Pakete 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 Laufzeit 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 /) muss 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://BUCKET_NAME/PATH/lib1.py'])
   AS r"""
   import path.to.lib1 as lib1
   
   def compute(a, b):
     # doInterestingStuff is a function defined in
     # gs://BUCKET_NAME/PATH/lib1.py
     return lib1.doInterestingStuff(a, b);
   
   """;

   Ersetzen Sie Folgendes:

   • PROJECT_ID: Ihre Projekt-ID.
   • DATASET_ID: Ihre Dataset-ID.
   • BUCKET_NAME: Der Name des Cloud Storage-Bucket, der lib1.py enthält.
   • PATH: der Pfad zum Cloud Storage-Bucket.

3. Klicken Sie auf play_circle_filled Ausführen.

Containerlimits für Python-UDFs konfigurieren

Mit der Optionsliste für CREATE FUNCTION können Sie Grenzwerte für die Parallelität von CPU-, Arbeitsspeicher- und Containeranforderungen für Container angeben, in denen Python-UDFs ausgeführt werden.

Standardmäßig werden Containern die folgenden Ressourcen zugewiesen:

• Der zugewiesene Arbeitsspeicher beträgt 512Mi.
• Die zugewiesene CPU beträgt 1.0 vCPU.
• Das Limit für die Nebenläufigkeit von Containeranfragen beträgt 80.

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`.square_area(length FLOAT64)
   RETURNS FLOAT64 LANGUAGE python
   OPTIONS (entry_point='square_area', runtime_version='python-3.11',
   container_memory='CONTAINER_MEMORY', container_cpu=CONTAINER_CPU, container_request_concurrency=CONTAINER_REQUEST_CONCURRENCY)
   AS r"""
   def square_area(length):
     return length*length
   """;
   
   SELECT `PROJECT_ID.DATASET_ID`.square_area(4.5);

   Ersetzen Sie Folgendes:

   • PROJECT_ID.DATASET_ID: Ihre Projekt-ID und Dataset-ID.
   • CONTAINER_MEMORY: Der Arbeitsspeicherwert im folgenden Format: <integer_number><unit>. Die Einheit muss einer der folgenden Werte sein: Mi (MiB), M (MB), Gi (GiB) oder G (GB). Beispiel: 2Gi
   • CONTAINER_CPU: Der CPU-Wert. Python-UDFs unterstützen fraktionale CPU-Werte zwischen 0.33 und 1.0 sowie nicht fraktionale CPU-Werte von 1, 2 und 4.
   • CONTAINER_REQUEST_CONCURRENCY: Die maximale Anzahl gleichzeitiger Anfragen pro Containerinstanz der benutzerdefinierten Python-Funktion. Der Wert muss eine Ganzzahl zwischen 1 und 1000 sein.

3. Klicken Sie auf play_circle_filled Ausführen.

Unterstützte CPU-Werte

Python-UDFs unterstützen CPU-Werte mit Nachkommastellen zwischen 0.33 und 1.0 sowie CPU-Werte ohne Nachkommastellen von 1, 2 und 4. Container, in denen Python-UDFs ausgeführt werden, können mit bis zu 4 vCPUs konfiguriert werden. Der Standardwert ist 1.0. Gleitkomma-Eingabewerte werden auf zwei Dezimalstellen gerundet, bevor sie auf den Container angewendet werden.

Unterstützte Arbeitsspeicherwerte

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 256Mi. Die maximal konfigurierbare Arbeitsspeichermenge ist 16Gi.

Abhängig vom ausgewählten Speicherwert müssen Sie auch eine angemessene CPU-Menge angeben. Die folgende Tabelle zeigt die minimalen und maximalen CPU-Werte für jeden Arbeitsspeicherwert:

Wenn Sie die Menge an CPU, die Sie zuweisen, bereits ermittelt haben, können Sie die folgende Tabelle verwenden, um den entsprechenden Speicherbereich zu bestimmen:

Cloud de Confiance by S3NS oder Onlinedienste in Python-Code aufrufen

Eine Python-UDF greift über das Dienstkonto der Cloud-Ressourcenverbindung auf einen Cloud de Confiance by S3NS -Dienst oder einen externen Dienst zu. Dem Dienstkonto der Verbindung müssen Berechtigungen für den Zugriff auf den Dienst gewährt 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, in der der Netzwerkzugriff blockiert wird. 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. Wenn Sie eine Cloud-Ressourcenverbindung verwenden, müssen Sie Folgendes implementieren:

• Zeitüberschreitungen Wenn Sie Netzwerkaufrufe in Ihrer Python-UDF ausführen, sollten Sie immer ein angemessenes Zeitlimit festlegen. So wird verhindert, dass die UDF unbegrenzt lange hängt, wenn der externe Dienst langsam reagiert oder nicht erreichbar ist.

• Fehlerbehandlung verwenden Schließen Sie den Code für Netzwerkaufrufe in einen try...except-Block ein, um potenzielle Fehler wie Verbindungsfehler, Zeitüberschreitungen oder HTTP-Fehlerstatuscodes ordnungsgemäß zu verarbeiten. So kann Ihre UDF einen aussagekräftigen Fehler oder einen Fallback-Wert zurückgeben, anstatt dass die Abfrage fehlschlägt oder nicht mehr reagiert.

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-Ressourcenverbindung erstellen

Zuerst erstellen Sie eine Cloud-Ressourcenverbindung in my_query_project. So erstellen Sie die Cloud-Ressourcenverbindung:

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Dem Dienstkonto der Verbindung Zugriff gewähren

Sie benötigen die Dienstkonto-ID, die Sie zuvor kopiert haben, wenn Sie Berechtigungen für die Verbindung konfigurieren. Wenn Sie eine Verbindungsressource erstellen, erstellt BigQuery ein eindeutiges Systemdienstkonto und ordnet es der Verbindung zu.

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

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 in der Cloud de Confiance Console 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_ID/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: Projekt-ID.
   • DATASET_ID: Die Dataset-ID.
   • REGION: Die Region Ihrer Verbindung.
   • CONNECTION_ID: die Verbindungs-ID.

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                         |
   +--------------------------+-------------------------------+
   

VPC Service Controls verwenden

Python-UDFs übernehmen den VPC Service Controls-Perimeter des Projekts, in dem der Abfragejob ausgeführt wird. Dieser Perimeter schützt Ihre Jobs vor Daten-Exfiltration und sorgt für sichere Dienstinteraktionen.

Wenn Sie eine Python-UDF innerhalb des VPC Service Controls-Perimeters aufrufen, hat sie die folgende Netzwerkverbindung:

• Python-UDFs, die keine Cloud-Ressourcenverbindung verwenden, sind vollständig isoliert. Der gesamte ausgehende Traffic wird blockiert.
• Python-Nutzerdefinierte Funktionen, die eine Cloud-Ressourcenverbindung verwenden, sind für den öffentlichen Internetzugriff gesperrt. Python-UDFs können nur auf Cloud de Confiance by S3NS Dienste zugreifen, die VPC Service Controls unterstützen. Ausgehender Traffic zu anderen Zielen als restricted.googleapis.com wird blockiert.

Python-Nutzerdefinierte Funktionen für den sicheren Zugriff auf Cloud de Confiance by S3NS -Dienste in VPC Service Controls konfigurieren

So greifen Sie über Python-UDFs auf Cloud de Confiance by S3NS Dienste zu und erzwingen gleichzeitig VPC Service Controls:

1. Erstellen Sie die benutzerdefinierte Python-Funktion (UDF) mit der WITH CONNECTION-Klausel der CREATE FUNCTION-Anweisung.
2. Fügen Sie das BigQuery-Projekt, in dem der Abfragejob ausgeführt wird, und das Ziel-Dienstprojekt in den Dienstperimeter ein. Alternativ können Sie eine Perimeter-Bridge konfigurieren.
3. Fügen Sie die API des Zieldienstes der Perimeterkonfiguration hinzu. translate.googleapis.com, wenn Sie beispielsweise eine Verbindung zur Cloud Translation API herstellen.

Weitere Informationen zum Konfigurieren eines VPC Service Controls-Perimeters finden Sie unter:

• VPC Service Controls für BigQuery
• Übersicht über VPC Service Controls

Best Practices

Beachten Sie beim Erstellen von Python-UDFs die folgenden Best Practices:

• Abfragelogik für Batching optimieren Komplexe Abfragestrukturen können das Batching deaktivieren. Dadurch wird eine langsame, zeilenweise Verarbeitung erzwungen, was die Latenz bei großen Datasets erheblich erhöht.
• Daten-Payload optimieren Die Größe einzelner Zeilen kann sich auf die Effizienz der Batching-Funktion auswirken. Halten Sie jede Zeile so kurz wie möglich, um die Anzahl der Zeilen zu maximieren, die in einem einzelnen Batch verarbeitet werden können.
• Konfigurieren Sie Containerlimits effizient. Die Skalierbarkeit hängt von CPU, Arbeitsspeicher und der Nebenläufigkeit von Anfragen ab. Überprüfen Sie die Monitoring-Messwerte, um die Containerkonfiguration zu optimieren. Wenn die CPU-Auslastung hoch ist, erhöhen Sie die CPU-Zuweisung mit dem container_cpu-Limit oder verringern Sie die Nebenläufigkeit von Containeranfragen mit dem container_request_concurrency-Limit.
• Beginnen Sie bei der iterativen Optimierung mit den Standardwerten. Wenn die Leistung nicht optimal ist, analysieren Sie die Monitoring-Messwerte, um bestimmte Engpässe zu ermitteln.
• API-Timeouts implementieren Wenn Ihre Python-UDF auf das Internet zugreift, legen Sie für den API-Aufruf ein Zeitlimit fest, um unerwartetes Verhalten zu vermeiden. Ein Beispiel für den Internetzugriff ist das Lesen aus einem Cloud Storage-Bucket.

Python-UDF-Messwerte ansehen

Python-UDFs exportieren Messwerte nach Cloud Monitoring. Mithilfe dieser Messwerte können Sie verschiedene Aspekte des Betriebs und des Ressourcenverbrauchs Ihrer UDF überwachen und so Einblicke in die Leistung und das Verhalten Ihrer UDF-Instanzen erhalten.

Typ der überwachten Ressource

Die Messwerte für Python-UDFs werden unter dem folgenden Cloud Monitoring-Ressourcentyp gemeldet:

• Typ: bigquery.googleapis.com/ManagedRoutineInvocation
• Anzeigename: Von BigQuery verwalteter Aufruf von Abläufen
• Labels:
  • resource_container: die ID des Projekts, in dem der Abfragejob ausgeführt wurde.
  • location: der Ort, an dem der Abfragejob ausgeführt wurde.
  • query_job_id: die ID des Abfragejobs, mit dem die Python-UDF aufgerufen wurde.
  • routine_project_id: die Projekt-ID, in der die aufgerufene Routine gespeichert ist.
  • routine_dataset_id: die Dataset-ID, in der die aufgerufene Routine gespeichert ist.
  • routine_id: Die ID der aufgerufenen Routine.

Messwerte

Die folgenden Messwerte sind für den Ressourcentyp bigquery.googleapis.com/ManagedRoutineInvocation verfügbar:

Messwerte aufrufen

Wenn Sie die Messwerte für Ihre Python-UDFs aufrufen möchten, wählen Sie eine der Optionen in den folgenden Abschnitten aus.

Jobdetails

So rufen Sie Python-UDF-Messwerte für einen bestimmten Abfragejob auf:

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Klicken Sie auf Jobverlauf.

3. Klicken Sie in der Spalte Job-ID auf die Job-ID der Abfrage.

4. Klicken Sie auf der Seite Abfragejobdetails auf Cloud Monitoring-Dashboard. Über diesen Link wird ein Dashboard aufgerufen, das so gefiltert ist, dass die Messwerte für die Python-UDF für den Job angezeigt werden.

Metrics Explorer

So rufen Sie Python-UDF-Messwerte im Metrics Explorer auf:

1. Rufen Sie die Cloud Monitoring-Seite Metrics Explorer auf.

   Zu Metrics Explorer

2. Klicken Sie auf Messwert auswählen und geben Sie im Feld Filter BigQuery Managed Routine Invocation oder bigquery.googleapis.com/ManagedRoutineInvocation ein.

3. Wählen Sie Von BigQuery verwalteter Ablauf > Managed_routine aus.

4. Klicken Sie auf einen der verfügbaren Messwerte, z. B.:

   • CPU-Auslastung der Instanz
   • Arbeitsspeicherauslastung der Instanz
   • Maximale Anzahl gleichzeitiger Anfragen

5. Klicken Sie auf Übernehmen.

   Standardmäßig werden die Messwerte in einem Diagramm dargestellt.

6. Sie können die Messwerte mit den in den Monitoring-Ressourcentypen definierten Labels filtern und gruppieren. So filtern Sie die Messwerte:

   1. Wählen Sie im Feld Filter einen Ressourcentyp aus, z. B. query_job_id oder routine_id.

   2. Geben Sie im Feld Wert die Job-ID oder die Routine-ID ein oder wählen Sie eine aus der Liste aus.

Cloud Monitoring-Dashboards

So rufen Sie Python-UDF-Messwerte über die Monitoring-Dashboards auf:

1. Rufen Sie die Cloud Monitoring-Seite Dashboards auf.

   Dashboards aufrufen

2. Klicken Sie auf das Dashboard BigQuery Managed Routine Query Monitoring (Monitoring von Abfragen für von BigQuery verwaltete Routinen).

   Dieses Dashboard bietet einen Überblick über die wichtigsten Messwerte für Ihre UDFs.

3. So filtern Sie dieses Dashboard:

   1. Klicken Sie auf addFilter.

   2. Wählen Sie in der Liste Nach Ressource filtern eine Option wie Projekt-ID, Standort, Routine-ID oder Job-ID aus.

Unterstützte Standorte

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

Preise

Gebühren für Python-UDFs werden über die BigQuery Services-SKU abgerechnet.

Die Kosten umfassen Folgendes:

• Erstellen oder Neuerstellen des UDF-Container-Images. Diese Gebühr ist proportional zur Dauer, die zum Erstellen des entsprechenden Images mit Kundencode und Abhängigkeiten erforderlich ist.

  • Wenn Sie die Routines API verwenden, finden Sie die Dauer des letzten Builds im Feld BuildStatus. Sie können die Build-Dauer auch in der Spalte BuildStatus in der INFORMATION_SCHEMA.ROUTINES-Ansicht sehen.
  • Wenn Sie die Gesamtkosten für Builds pro Projekt aufrufen möchten, können Sie Ihren Abrechnungsbericht mit den folgenden Filtern filtern:
    • Key: goog-bq-feature-type
    • Wert: MANAGED_ROUTINE_BUILD

• Kunden mit Python-UDFs werden auch die Kosten für den Aufruf einer Python-UDF in Rechnung gestellt. Diese Gebühr ist proportional zur Menge an Rechenleistung und Arbeitsspeicher, die beim Aufrufen der Python-UDF verbraucht werden.

  • Wenn Sie die Kosten für Python-UDFs pro Abfrage aufrufen möchten, können Sie das Feld ExternalServiceCosts mit der Job API abfragen. Sie können die Kosten pro Anfrage auch in der INFORMATION_SCHEMA.JOBS-Ansicht in der Spalte external_service_costs sehen. Wenden Sie dazu den folgenden Filter an: 'external_service_costs.external_service="MANAGED_ROUTINE_EXECUTION"'.
  • Wenn Sie die Gesamtkosten für die Ausführung von Python-UDFs pro Projekt aufrufen möchten, können Sie den Abrechnungsbericht mit den folgenden Filtern filtern:
    • Key: goog-bq-feature-type
    • Wert: MANAGED_ROUTINE_EXECUTION

• Wenn Python-UDFs zu ausgehendem externen oder Internet-Netzwerktraffic führen, wird auch eine Gebühr für ausgehenden Internettraffic der Premium-Stufe basierend auf den BigQuery-SKUs für ausgehenden Traffic berechnet.

Kontingente

Weitere Informationen finden Sie unter UDF-Kontingente und ‑Limits.