Mit benutzerdefinierten Funktionen in Python arbeiten

Mit einer benutzerdefinierten Python-Funktion (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 eine Python-UDF nicht mit einer materialisierten Ansicht verwenden.
  • Die Ergebnisse einer Abfrage, die eine Python-UDF aufruft, werden nicht im Cache gespeichert, da davon ausgegangen wird, dass der Rückgabewert einer Python-UDF immer nicht deterministisch ist.
  • Assured Workloads werden nicht unterstützt.
  • Diese Datentypen werden nicht unterstützt: JSON, RANGE, INTERVAL und GEOGRAPHY.
  • Container, in denen Python-UDFs ausgeführt werden, können nur mit maximal 4 vCPUs und 16 GiB konfiguriert werden.
  • Das Verschlüsseln von Python-UDF-Code mit kundenverwalteten Verschlüsselungsschlüsseln (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 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 Ihre UDF die WITH CONNECTION-Klausel für den Zugriff auf einen externen Dienst verwendet.

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:

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:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen oder Aktualisieren einer Python-UDF erforderlich:

  • Erstellen Sie eine Python-UDF mit der Anweisung CREATE FUNCTION: bigquery.routines.create für das Dataset
  • Aktualisieren Sie eine Python-UDF mit der Anweisung CREATE FUNCTION: bigquery.routines.update für das Dataset.
  • Führen Sie einen Abfragejob mit einer CREATE FUNCTION-Anweisung aus: bigquery.jobs.create für das Projekt
  • Neue Cloud-Ressourcenverbindung erstellen: bigquery.connections.create für das Projekt
  • Verwenden Sie eine Verbindung in der CREATE FUNCTION-Anweisung: bigquery.connections.delegate für die Verbindung

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 von einer anderen Person erstellte UDF auf. 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:

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:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um eine von einer anderen Person erstellte Python-UDF aufzurufen:

  • So führen Sie einen Abfragejob aus, der auf eine Python-UDF verweist: bigquery.jobs.create für das Projekt
  • So rufen Sie eine von einer anderen Person erstellte Python-UDF auf: bigquery.routines.get für das Dataset
  • So führen Sie eine Python-UDF aus, die auf eine Cloud-Ressourcenverbindung verweist: bigquery.connections.use für die Verbindung

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 Text der Python-UDF muss ein Stringliteral in Anführungszeichen sein, das den Python-Code darstellt. Weitere Informationen zu Stringliteralen in Anführungszeichen finden Sie unter Formate für Literale in Anführungszeichen.

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

  • In der Option runtime_version muss eine Python-Laufzeitversion 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 Anweisung CREATE FUNCTION.

Verwenden Sie zum Erstellen einer nichtflüchtigen Python-UDF die Anweisung CREATE FUNCTION ohne das Schlüsselwort TEMP oder TEMPORARY. Verwenden Sie zum Löschen einer persistenten Python-UDF die Anweisung DROP FUNCTION.

Beispiel

Wählen Sie eine der folgenden Optionen aus, um ein Beispiel für das Erstellen einer persistenten Python-UDF aufzurufen:

Console

Im folgenden Beispiel wird eine persistente Python-UDF mit dem Namen multiplyInputs erstellt und die UDF aus einer SELECT-Anweisung aufgerufen:

  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`.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(runtime_version="python-3.11", entry_point="multiply")
AS r'''

def multiply(x, y):
    return x * y

''';

-- Call the Python UDF.
WITH numbers AS
    (SELECT 1 AS x, 5 as y
    UNION ALL
    SELECT 2 AS x, 10 as y
    UNION ALL
    SELECT 3 as x, 15 as y)
SELECT x, y,
`PROJECT_ID.DATASET_ID`.multiplyInputs(x, y) AS product
FROM numbers;

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

  3. Klicken Sie auf  Ausführen.

    Dieses Beispiel liefert folgende Ausgabe:

    +-----+-----+--------------+
| x   | y   | product      |
+-----+-----+--------------+
| 1   | 5   |  5.0         |
| 2   | 10  | 20.0         |
| 3   | 15  | 45.0         |
+-----+-----+--------------+

BigQuery DataFrames

Im folgenden Beispiel wird BigQuery DataFrames verwendet, um eine benutzerdefinierte Funktion in eine Python-UDF umzuwandeln:

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 Anweisung CREATE FUNCTION 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 Prozess. Die erste Abfrage nach dem Ausführen der CREATE FUNCTION-Anweisung wartet, 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 Container-Build schlägt fehl, wenn Ihr Projekt das Kontingent erreicht hat.

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

Console

  1. Rufen Sie die BigQuery-Seite Studio auf.

    Zu Studio

  2. Maximieren Sie im linken Bereich Ihr Projekt und klicken Sie dann auf Datasets.

  3. Klicken Sie auf den Link, um das Dataset mit Ihrer Python-UDF zu öffnen.

  4. Klicken Sie auf der Dataset-Seite auf den Tab Routinen.

  5. Klicken Sie in der Spalte Routine-ID auf Ihre Python-UDF.

  6. Auf der Seite Informationen zur persistenten Funktion können Sie den Build-Status, die Build-Dauer und die Image-Größe einsehen. Der Build-Status ist einer der folgenden:

    • In Bearbeitung
    • Erfolgreich
    • Fehlgeschlagen

    Wenn ein Build fehlschlägt, finden Sie auf der Seite mit den Funktionsinformationen detaillierte Fehlermeldungen, mit denen Sie Probleme wie Syntaxfehler oder Probleme bei der Installation externer Pakete beheben können.

    Die Seite „Informationen zur persistenten Funktion“ in der Console.

SQL

So fragen Sie die Build-Statusfelder in der Ansicht INFORMATION_SCHEMA.ROUTINES ab:

  1. Rufen Sie die BigQuery-Seite Studio auf.

    Zu Studio

  2. Wechseln Sie zum Abfrageeditor oder klicken Sie auf SQL-Abfrage.

  3. Geben Sie die folgende Abfrage ein, um die BUILD_STATUS-Felder aus der Ansicht INFORMATION_SCHEMA.ROUTINES abzurufen. Die Spalte BUILD_STATUS ist in GoogleSQL ein STRUCT-Typ:

    SELECT
  build_status.*
FROM
  `PROJECT_ID.DATASET_ID`.INFORMATION_SCHEMA.ROUTINES;

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

    Die Ausgabe sollte so aussehen: Fehlerfelder werden weggelassen:

    +---------------+--------------------------------+------------------------+------------------+
| build_state   | build_state_update_time        | build_duration_seconds | image_size_bytes |
+---------------+--------------------------------+------------------------+------------------+
| SUCCEEDED     | 2026-05-14 17:21:49.736000 UTC |                     11 |             3167 |
+---------------+--------------------------------+------------------------+------------------+

API

Rufen Sie den Container-Build-Status mit RoutineBuildStatus in der API auf.

Vektorisierte Python-UDF erstellen

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

Wenn Sie das Batching-Verhalten steuern möchten, geben Sie die maximale Anzahl von Zeilen in jedem Batch mit der Option max_batching_rows in der Optionsliste CREATE OR REPLACE FUNCTION an. 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 bestimmt.

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 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 und den beiden Parametern x und y erstellt:

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

    Der Aufruf der UDF ist derselbe wie in den vorherigen Beispielen.

  3. Klicken Sie auf  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 mit dem Namen cw_xml_extract in einem anderen Projekt aufrufen möchten, führen Sie die folgenden Schritte aus.

Console

  1. Rufen Sie die Seite BigQuery auf.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor das folgende Beispiel ein:

    SELECT
  `PROJECT_ID.DATASET_ID`.`cw_xml_extract`(xml, '//title/text()') AS `title`
FROM UNNEST([
  STRUCT('''<book id="1">
    <title>The Great Gatsby</title>
    <author>F. Scott Fitzgerald</author>
  </book>''' AS xml),
  STRUCT('''<book id="2">
    <title>1984</title>
    <author>George Orwell</author>
  </book>''' AS xml),
  STRUCT('''<book id="3">
    <title>Brave New World</title>
    <author>Aldous Huxley</author>
  </book>''' AS xml)
])

  3. Klicken Sie auf  Ausführen.

    Dieses Beispiel liefert folgende Ausgabe:

    +--------------------------+
| title                    |
+--------------------------+
| The Great Gatsby         |
| 1984                     |
| Brave New World          |
+--------------------------+

BigQuery DataFrames

Im folgenden Beispiel werden die BigQuery DataFrames-Methoden sql_scalar, read_gbq_function und apply verwendet, um eine Python-UDF aufzurufen:

import textwrap
from typing import Tuple

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

# Set partial ordering mode for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def call_python_udf(
    project_id: str = "your-project-id",
    location: str = "US",
) -> Tuple[pd.Series, bpd.Series]:
    """Demonstrates calling a Python UDF using pandas and BigQuery DataFrames."""
    # 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

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

    # 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


# Run the sample:
# titles_pandas, titles_bigframes = call_python_udf("your-project-id", "US")

Von Python-UDFs unterstützte Datentypen

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

BigQuery-Datentyp Integrierter Python-Datentyp, der von der Standard-UDF verwendet wird Von der vektorisierten UDF verwendeter Pandas-Datentyp PyArrow-Datentyp, der für ARRAY und STRUCT in vektorisierten UDFs verwendet wird
BOOL bool BooleanDtype DataType(bool)
INT64 int Int64Dtype DataType(int64)
FLOAT64 float FloatDtype DataType(double)
STRING str StringDtype DataType(string)
BYTES bytes binary[pyarrow] DataType(binary)
TIMESTAMP

Funktionsparameter: datetime.datetime (mit UTC-Zeitzone)

Rückgabewert der Funktion: datetime.datetime (mit beliebiger Zeitzone)

Funktionsparameter: timestamp[us, tz=UTC][pyarrow]

Rückgabewert der Funktion: timestamp[us, tz=*][pyarrow]\(any timezone\)

 TimestampType(timestamp[us]), mit Zeitzone
DATE datetime.date date32[pyarrow] DataType(date32[day])
TIME datetime.time time64[pyarrow] Time64Type(time64[us])
DATETIME datetime.datetime (ohne Zeitzone) timestamp[us][pyarrow] TimestampType(timestamp[us]), ohne Zeitzone
ARRAY list list<...>[pyarrow], wobei der Elementdatentyp ein pandas.ArrowDtype ist ListType
STRUCT dict struct<...>[pyarrow], wobei der Felddatentyp ein pandas.ArrowDtype ist StructType

Unterstützte Laufzeitversionen

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

Laufzeitversion Python-Version Enthält
python-3.11 Python 3.11 numpy 1.26.3
pyarrow 14.0.2
pandas 2.1.4
python-dateutil 2.8.2
absl-py 2.0.0
pytz 2023.3.post1
tzdata 2023.4
six 1.16.0

Pakete von Drittanbietern 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 Package Index (PyPI) installieren oder Python-Dateien aus Cloud Storage importieren.

Paket aus dem Python Package Index installieren

Wenn Sie ein Paket installieren, müssen Sie den Paketnamen angeben. Optional können Sie die Paketversion mit Python-Paketversionsspezifizierern angeben.

Wenn das Paket in der Laufzeit vorhanden ist, wird es verwendet, es sei denn, in der Optionsliste CREATE FUNCTION ist eine bestimmte Version angegeben. 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ärformat „wheels“ unterstützt.

Im folgenden Beispiel wird gezeigt, wie Sie eine Python-UDF erstellen, die das Paket scipy mithilfe 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  Ausführen.

Zusätzliche Python-Dateien als Bibliotheken importieren

Sie können Ihre Python-UDFs mithilfe der Liste der Funktionsoptionen 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 Ihre Importanweisung import path.to.lib1.

Der Python-Dateiname muss ein Python-Bezeichner sein. Jeder folder-Name im Objektnamen (nach dem /) muss eine gültige Python-ID sein. Innerhalb des ASCII-Bereichs (U+0001..U+007F) können die folgenden Zeichen in Kennungen verwendet werden:

  • Groß- und Kleinbuchstaben von A bis Z.
  • Unterstriche
  • Die Ziffern null bis neun, wobei eine Zahl nicht als erstes Zeichen in der Kennung erscheinen darf.

Im folgenden Beispiel wird gezeigt, wie Sie eine Python-UDF erstellen, die das Clientbibliothekspaket 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  Ausführen.

Containerlimits für Python-UDFs konfigurieren

Mit der Optionsliste CREATE FUNCTION können Sie CPU-, Arbeitsspeicher- und Containeranfrage-Gleichzeitigkeitslimits 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 mit der Optionsliste CREATE FUNCTION erstellt, um Containerlimits anzugeben:

  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 CPU-Werte mit Nachkommastellen zwischen 0.33 und 1.0 sowie CPU-Werte ohne Nachkommastellen von 1, 2 und 4.
    • CONTAINER_REQUEST_CONCURRENCY: die maximale Anzahl gleichzeitiger Anfragen pro Python-UDF-Containerinstanz. Der Wert muss eine Ganzzahl von 1 bis 1000 sein.

  3. Klicken Sie auf  Ausführen.

Unterstützte CPU-Werte

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

Unterstützte Arbeitsspeicherwerte

Python-UDF-Container unterstützen Arbeitsspeicherwerte 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 maximale Arbeitsspeichermenge, die Sie konfigurieren können, beträgt 16Gi.

Basierend auf dem von Ihnen ausgewählten Arbeitsspeicherwert müssen Sie auch eine entsprechende CPU-Menge angeben. In der folgenden Tabelle sind die minimalen und maximalen CPU-Werte für jeden Arbeitsspeicherwert aufgeführt:

Arbeitsspeicher Mindestanforderung CPU Maximale CPU-Auslastung
256Mi bis 512Mi 0.33 2
Größer als 512Mi und kleiner als oder gleich 1Gi 0.5 2
Größer als 1Gi und kleiner als 2Gi 1 2
2Gi bis 4Gi 1 4
Mehr als 4Gi und bis zu 8Gi 2 4
Mehr als 8Gi und bis zu 16Gi 4 4

Wenn Sie die Menge an CPU festgelegt haben, die Sie zuweisen, können Sie alternativ die folgende Tabelle verwenden, um den geeigneten Speicherbereich zu bestimmen:

CPU Mindestspeicher Maximaler Arbeitsspeicher
Weniger als 0.5 256Mi 512Mi
0.5 bis weniger als 1 256Mi 1Gi
1 256Mi 4Gi
2 256Mi 8Gi
4 2Gi 16Gi

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 gewährt werden. Die erforderlichen Berechtigungen variieren je nach dem Dienst, auf den zugegriffen wird, und den APIs, die über Ihren Python-Code aufgerufen werden.

Wenn Sie eine Python-UDF ohne Cloud-Ressourcenverbindung erstellen, wird die Funktion in einer Umgebung ausgeführt, die den Netzwerkzugriff blockiert. Wenn Ihre UDF auf Onlinedienste zugreift, müssen Sie die UDF mit einer Cloud-Ressourcenverbindung erstellen. Andernfalls wird die UDF am Zugriff auf das Netzwerk gehindert, bis ein internes Verbindungszeitlimit erreicht ist. Wenn Sie eine Cloud-Ressourcenverbindung verwenden, implementieren Sie Folgendes:

  • 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 hängen bleibt, wenn der externe Dienst langsam reagiert oder nicht erreichbar ist.

  • Fehlerbehandlung verwenden Fassen Sie den Code für den Netzwerkaufruf in einem try...except-Block zusammen, um potenzielle Fehler wie Verbindungsfehler, Zeitüberschreitungen oder HTTP-Statuscodes 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 die Cloud Translation ausführen.

Cloud-Ressourcenverbindung erstellen

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

Wählen Sie eine der folgenden Optionen aus:

Console

  1. Rufen Sie die Seite BigQuery auf.

    BigQuery aufrufen

  2. Klicken Sie im linken Bereich auf Explorer:

    Hervorgehobener Button für den Explorer-Bereich.

    Wenn der linke Bereich nicht angezeigt wird, klicken Sie auf Linken Bereich maximieren, um ihn zu öffnen.

  3. Maximieren Sie im Bereich Explorer den Namen Ihres Projekts und klicken Sie dann auf Verbindungen.

  4. Klicken Sie auf der Seite Verbindungen auf Verbindung erstellen.

  5. Wählen Sie als Verbindungstyp die Option Vertex AI-Remote-Modelle, Remote-Funktionen, BigLake und Cloud Spanner (Cloud-Ressource) aus.

  6. Geben Sie im Feld Verbindungs-ID einen Namen für die Verbindung ein.

  7. Wählen Sie unter Standorttyp einen Standort für die Verbindung aus. Die Verbindung sollte sich am selben Ort wie Ihre anderen Ressourcen, z. B. Datasets, befinden.

  8. Klicken Sie auf Verbindung erstellen.

  9. Klicken Sie auf Zur Verbindung.

  10. Kopieren Sie im Bereich Verbindungsinformationen die Dienstkonto-ID zur Verwendung in einem späteren Schritt.

SQL

Verwenden Sie die Anweisung CREATE CONNECTION:

  1. Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
OPTIONS (
  connection_type = "CLOUD_RESOURCE",
  friendly_name = "FRIENDLY_NAME",
  description = "DESCRIPTION"
  );

    Ersetzen Sie Folgendes:

    • CONNECTION_NAME: der Name der Verbindung im Format PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID oder CONNECTION_ID. Wenn das Projekt oder der Standort weggelassen wird, werden sie aus dem Projekt und dem Standort abgeleitet, an dem die Anweisung ausgeführt wird.
    • FRIENDLY_NAME (optional): Ein beschreibender Name für die Verbindung.
    • DESCRIPTION (optional): Eine Beschreibung der Verbindung.

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

  1. Erstellen Sie in einer Befehlszeilenumgebung eine Verbindung:

    bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID

    Der Parameter --project_id überschreibt das Standardprojekt.

    Ersetzen Sie dabei Folgendes:

    • REGION: Ihre Verbindungsregion
    • PROJECT_ID: Ihre Projekt-ID in Google Cloud
    • CONNECTION_ID: eine ID für Ihre Verbindung

    Wenn Sie eine Verbindungsressource herstellen, erstellt BigQuery ein eindeutiges Systemdienstkonto und ordnet es der Verbindung zu.

    Fehlerbehebung:Wird der folgende Verbindungsfehler angezeigt, aktualisieren Sie das Google Cloud SDK:

    Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...

  2. Rufen Sie die Dienstkonto-ID ab und kopieren Sie sie zur Verwendung in einem späteren Schritt:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    Die Ausgabe sieht etwa so aus:

    name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel."}

Python

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

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

Node.js

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

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}`);
    }
  }
}

Java

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

Verwenden Sie die Ressource google_bigquery_connection:

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Im folgenden Beispiel wird eine Cloud-Ressourcenverbindung mit dem Namen my_cloud_resource_connection in der Region US erstellt:


# 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 {}
}

Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud -Projekt anzuwenden.

Cloud Shell vorbereiten

  1. Rufen Sie Cloud Shell auf.

  2. Legen Sie das Google Cloud -Standardprojekt fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.

    Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.

Verzeichnis vorbereiten

Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).

  1. Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung .tf haben, z. B. main.tf. In dieser Anleitung wird die Datei als main.tf bezeichnet. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.

    Kopieren Sie den Beispielcode in das neu erstellte main.tf.

    Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.

  3. Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
  4. Speichern Sie die Änderungen.
  5. Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich. 
    terraform init

    Fügen Sie optional die Option -upgrade ein, um die neueste Google-Anbieterversion zu verwenden: 

    terraform init -upgrade

Änderungen anwenden

  1. Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen: 
    terraform plan

    Korrigieren Sie die Konfiguration nach Bedarf.

  2. Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie yes an der Eingabeaufforderung ein: 
    terraform apply

    Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.

  3. Öffnen Sie Ihr Google Cloud -Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.

Dem Dienstkonto der Verbindung Zugriff gewähren

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

Wenn Sie dem Dienstkonto für die Cloud-Ressourcenverbindung Zugriff auf Ihre Projekte gewähren möchten, weisen Sie dem Dienstkonto die Rolle Service Usage-Nutzer (roles/serviceusage.serviceUsageConsumer) in my_query_project und die Rolle Cloud Translation API-Nutzer (roles/cloudtranslate.user) in my_translate_project zu.

Console

  1. Rufen Sie die IAM-Seite auf.

    IAM aufrufen

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

  3. Klicken Sie auf Zugriff 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 Zugriff 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.

SQL

Verwenden Sie die Anweisung GRANT, um dem Dienstkonto in my_query_project die Rolle „Service Usage Consumer“ (roles/serviceusage.serviceUsageConsumer) zuzuweisen:

  1. Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

      GRANT `roles/serviceusage.serviceUsageConsumer`
  ON PROJECT `my_query_project`
  TO "connection:SERVICE_ACCOUNT_ID";

    Ersetzen Sie SERVICE_ACCOUNT_ID durch die zuvor kopierte Dienstkonto-ID.

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

Verwenden Sie die Anweisung GRANT, um die Nutzerrolle „Cloud Translation API“ (roles/cloudtranslate.user) in my_translate_project zu gewähren:

  1. Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

      GRANT `roles/cloudtranslate.user`
  ON PROJECT `my_translate_project`
  TO "connection:SERVICE_ACCOUNT_ID";

    Ersetzen Sie SERVICE_ACCOUNT_ID durch die zuvor kopierte Dienstkonto-ID.

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

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 Google Cloud 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  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 dafür, dass Dienstinteraktionen sicher sind.

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-UDFs, die eine Cloud-Ressourcenverbindung verwenden, sind für den öffentlichen Internetzugriff gesperrt. Python-UDFs können nur auf Google Cloud -Dienste zugreifen, die VPC Service Controls unterstützen. Ausgehender Traffic zu anderen Zielen als restricted.googleapis.com wird blockiert.

Python-UDFs für den sicheren Zugriff auf Google Cloud -Dienste innerhalb von VPC Service Controls konfigurieren

So greifen Sie von Python-UDFs auf Google Cloud -Dienste zu, während VPC Service Controls erzwungen wird:

  1. Erstellen Sie die Python-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 Zieldienstprojekt in den Dienstperimeter ein. Alternativ können Sie eine Perimeter-Bridge konfigurieren.
  3. Fügen Sie die API des Zieldienstes der Perimeterkonfiguration hinzu. Beispiel: translate.googleapis.com, wenn Sie eine Verbindung zur Cloud Translation API herstellen.

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

Logging verwenden

Wenn Sie das Logging aktivieren, können Sie sich in Cloud Logging Echtzeitlogs ansehen, die von Ihren Python-UDFs generiert wurden. So können Sie Probleme in Ihrem Code leichter identifizieren und beheben. Um eine versehentliche Daten-Exfiltration zu verhindern, ist das Logging von benutzerdefinierten Python-Funktionen standardmäßig deaktiviert.

Logging aktivieren

Führen Sie die folgende Anweisung aus, bevor Sie Ihre Abfrage ausführen, um das Logging für Ihre Sitzung zu aktivieren:

SET @@udf.properties = JSON '{"enableDebugOutput": true}';

Verwenden Sie zum Protokollieren von Informationen Funktionen in der Python-Bibliothek logging, z. B. logging.info oder logging.error. Die Funktion print() wird nicht unterstützt.

Logs werden in Logging in die Ressource bigquery.googleapis.com/ManagedRoutineInvocation geschrieben. Für diese Ressource sind die folgenden Labels zum Filtern verfügbar:

  • resource_container: die ID des Projekts, in dem der Abfragejob ausgeführt wurde.
  • location: der Standort, an dem der Abfragejob ausgeführt wurde.
  • query_job_id: Die ID des Abfragejobs, der die Python-UDF aufgerufen hat.
  • routine_project_id: die Projekt-ID, in der die aufgerufene Routine gespeichert ist.
  • routine_dataset_id: die Dataset-ID, unter der die aufgerufene Routine gespeichert ist.
  • routine_id: die ID der aufgerufenen Routine.

Für in Cloud Logging protokollierte Daten gelten die Preise für Google Cloud Observability.

Beispiel

Im folgenden Beispiel wird gezeigt, wie Sie Logging verwenden, um Fehler in einer Python-UDF zu beheben, ohne dass die Abfrage fehlschlägt.

Die Python-UDF extract_user_email extrahiert E-Mail-Adressen aus JSON-Strings. Da eine nicht behandelte Ausnahme in einer UDF dazu führen kann, dass eine gesamte Abfrage fehlschlägt, fängt die Funktion Ausnahmen ab und gibt None zurück, was in BigQuery zu einem NULL-Wert wird. Damit Sie die ungültigen Eingaben identifizieren können, die nicht geparst werden konnten, protokolliert die Funktion die problematische Nutzlast selektiv in Cloud Logging:

CREATE OR REPLACE FUNCTION `PROJECT_ID.DATASET_ID`.extract_user_email(payload STRING)
RETURNS STRING
LANGUAGE python
OPTIONS (entry_point='parse_email', runtime_version='python-3.11')
AS
r"""
import json
import logging
def parse_email(payload):
  try:
    # Attempt to parse the JSON and extract the email
    data = json.loads(payload)
    return data.get('email')
  except Exception as e:
    # Log the exact bad data and the error to Cloud Logging
    logging.info(f"Failed to parse payload: '{payload}'. Error: {e}")
    # Return None (NULL in BigQuery) to prevent the query from failing.
    return None
""";

-- The query completes successfully, returning NULL for the invalid row.
-- The info log for 'corrupted_payload_string' is sent to Cloud Logging.
SET @@udf.properties = JSON '{"enableDebugOutput": true}';
SELECT `PROJECT_ID.DATASET_ID`.extract_user_email(raw_data) AS email
FROM UNNEST([
    '{"email": "cloudysanfrancisco@gmail.com", "event": "click"}',
    'corrupted_payload_string',
    '{"email": "baklavainthebalkans@gmail.com", "event": "view"}'
]) AS raw_data;

Die Logs, die die Eingabe corrupted_payload_string enthalten, sind in Logging zugänglich.

Logs ansehen

Wählen Sie eine der Optionen in den folgenden Abschnitten aus, um die Logs für Ihre Python-UDFs aufzurufen.

Jobinformationen

So rufen Sie Python-UDF-Logs für einen Abfragejob auf dem Tab Jobinformationen auf:

  1. Klicken Sie im Bereich Abfrageergebnisse auf den Tab Jobinformationen.

  2. Klicken Sie im Feld Log auf Log. Der Log-Explorer wird geöffnet und ist mit einer Abfrage vorausgefüllt, die die Logs für Ihren Python-UDF-Aufruf enthält.

Log-Explorer

Sie können auch direkt zum Log-Explorer wechseln und selbst eine Abfrage erstellen, um Python-UDF-Logs aufzurufen:

  1. Rufen Sie in Cloud Logging die Seite Log-Explorer auf.

    Zum Log-Explorer

  2. Erstellen Sie im Abfrageeditor eine Abfrage mit dem Ressourcentyp bigquery.googleapis.com/ManagedRoutineInvocation und allen relevanten Ressourcenlabels. Mit der folgenden Abfrage können Sie beispielsweise Python-UDF-Logs aufrufen, die von einem Abfragejob stammen:

    resource.type="bigquery.googleapis.com/ManagedRoutineInvocation"
resource.labels.query_job_id="QUERY_JOB_ID"

    Ersetzen Sie QUERY_JOB_ID durch die ID des Abfragejobs, der die Python-UDF aufgerufen hat.

Python-UDF-Messwerte ansehen

Python-UDFs exportieren Messwerte nach Cloud Monitoring. Mit diesen Messwerten können Sie verschiedene Aspekte des Betriebszustands und des Ressourcenverbrauchs Ihrer UDF überwachen und erhalten Einblicke in die Leistung und das Verhalten Ihrer UDF-Instanzen.

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 Standort, an dem der Abfragejob ausgeführt wurde.
    • query_job_id: Die ID des Abfragejobs, der die Python-UDF aufgerufen hat.
    • routine_project_id: die Projekt-ID, in der die aufgerufene Routine gespeichert ist.
    • routine_dataset_id: die Dataset-ID, unter der die aufgerufene Routine gespeichert ist.
    • routine_id: die ID der aufgerufenen Routine.

Messwerte

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

Messwert Beschreibung Einheit Werttyp
bigquery.googleapis.com/managed_routine/python/cpu_utilizations Wenn eine Python-UDF aufgerufen wird, zeigt dieser Messwert die Verteilung der CPU-Auslastung auf alle Python-UDF-Instanzen für den Abfragejob. Ein Prozentwert DISTRIBUTION
bigquery.googleapis.com/managed_routine/python/memory_utilizations Wenn eine Python-UDF aufgerufen wird, zeigt dieser Messwert die Verteilung der Arbeitsspeicherauslastung auf alle Python-UDF-Instanzen für den Abfragejob. Ein Prozentwert DISTRIBUTION
bigquery.googleapis.com/managed_routine/python/max_request_concurrencies Dieser Messwert zeigt die Verteilung der maximalen Anzahl gleichzeitiger Anfragen, die von jeder Python-UDF-Instanz verarbeitet werden. Anzahl DISTRIBUTION

Messwerte aufrufen

Wählen Sie eine der Optionen in den folgenden Abschnitten aus, um die Messwerte für Ihre Python-UDFs aufzurufen.

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 Abfragejob-ID.

  4. Klicken Sie auf der Seite Abfragejobdetails auf Cloud Monitoring-Dashboard. Über diesen Link wird ein Dashboard angezeigt, das so gefiltert ist, dass die Python-UDF-Messwerte 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 den Wert 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 von Instanzen
    • Maximale Anzahl gleichzeitiger Anfragen

  5. Klicken Sie auf Übernehmen.

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

  6. Sie können die Messwerte mithilfe der Labels filtern und gruppieren, die in den Monitoring-Ressourcentypen definiert sind. 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 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.

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

  3. So filtern Sie dieses Dashboard:

    1. Klicken Sie auf Filter.

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

Best Practices

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

  • Optimieren Sie Ihre Abfragelogik für die Batchverarbeitung. Komplexe Abfragestrukturen können die Batchverarbeitung deaktivieren. Dies führt zu einer langsamen, zeilenweisen Verarbeitung, was die Latenz bei großen Datasets erheblich erhöht.
  • Optimieren Sie die Datennutzlast. Die Größe einzelner Zeilen kann sich auf die Effizienz der Batchfunktion auswirken. Halten Sie jede Zeile so klein wie möglich, um die Anzahl der Zeilen zu maximieren, die in einem einzelnen Batch verarbeitet werden können.
  • Containerlimits effizient konfigurieren Die Skalierbarkeit ist eine Funktion von CPU, Arbeitsspeicher und Anfrage-Nebenläufigkeit. Überwachen Sie die Messwerte, um die Containerkonfiguration anzupassen. Wenn die CPU-Auslastung hoch ist, erhöhen Sie die CPU-Zuweisung mit dem Limit container_cpu oder reduzieren Sie die Nebenläufigkeit von Containeranfragen mit dem Limit container_request_concurrency.
  • Wenn Sie die iterative Abstimmung verwenden, beginnen Sie mit den Standardwerten. Wenn die Leistung nicht optimal ist, analysieren Sie die Monitoring-Messwerte, um bestimmte Engpässe zu identifizieren.
  • Implementieren Sie API-Zeitlimits. Wenn Ihre Python-UDF auf das Internet zugreift, legen Sie ein Zeitlimit für den API-Aufruf fest, um unerwartetes Verhalten zu vermeiden. Ein Beispiel für Internetzugriff ist das Lesen aus einem Cloud Storage-Bucket.
  • Um die Kosten zu senken und die Lesbarkeit zu verbessern, sollten Sie das Logging auf Ausnahmen, Datenanomalien oder bestimmte Debugging-Fenster beschränken.

Unterstützte Standorte

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

Preise

Python-UDF-Gebühren 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 für das 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 Ansicht INFORMATION_SCHEMA.ROUTINES aufrufen.
    • Wenn Sie die Gesamtkosten für Builds pro Projekt aufrufen möchten, können Sie den Abrechnungsbericht so filtern:
      • Key: goog-bq-feature-type
      • Wert: MANAGED_ROUTINE_BUILD

  • Kunden, die Python-UDFs verwenden, 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 wird.

    • 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 Abfrage auch in der Spalte external_service_costs in der Ansicht INFORMATION_SCHEMA.JOBS aufrufen und den folgenden Filter anwenden: '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 so filtern:
      • Key: goog-bq-feature-type
      • Wert: MANAGED_ROUTINE_EXECUTION

  • Wenn Python-UDFs zu ausgehendem Traffic in externe oder Internetnetzwerke führen, wird Ihnen außerdem eine Gebühr für ausgehenden Internet-Traffic der Premium-Stufe basierend auf den BigQuery-SKUs für ausgehenden Traffic in Rechnung gestellt.

Kontingente

Siehe UDF-Kontingente und -Limits.