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.
  • VPC-Netzwerke werden nicht unterstützt.
  • 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.
  • Kundenverwaltete Verschlüsselungsschlüssel (CMEK) 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:

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

Zum Erstellen oder Aktualisieren einer Python-UDF sind die folgenden Berechtigungen erforderlich:

  • Erstellen Sie eine Python-UDF mit der CREATE FUNCTION-Anweisung: bigquery.routines.create für das Dataset
  • Aktualisieren Sie eine Python-UDF mit der CREATE FUNCTION-Anweisung: bigquery.routines.update für das Dataset
  • So 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 in der 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 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:

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 Python-UDF aufzurufen, die von einer anderen Person erstellt wurde:

  • So führen Sie einen Abfragejob aus, der auf eine Python-UDF verweist: bigquery.jobs.create für das Projekt
  • So rufen Sie eine Python-UDF auf, die von einer anderen Person erstellt wurde: bigquery.routines.get für das Dataset
  • So führen Sie eine Python-UDF aus, die auf eine Cloud-Ressourcenverbindung verweist: bigquery.connections.use auf der 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.

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 die cw_xml_extract-Python-UDF aufrufen möchten, die als bigquery-utils-Community-UDF definiert ist, gehen Sie so vor:

Console

  1. Rufen Sie die Seite BigQuery auf.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor das folgende Beispiel ein:

    SELECT
  `bqutil`.`fn`.`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 wird eine Python-UDF mit den Methoden BigQuery DataFrames sql_scalar, read_gbq_function und apply aufgerufen:

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

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

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

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

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

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

Beispiel

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

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

Vektorisierte Python-UDF erstellen

Sie können Ihre Python-UDF so implementieren, dass sie mit Vektorisierung einen Batch von Zeilen anstelle einer einzelnen Zeile verarbeitet. 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  Ausführen.

Apache Arrow verwenden

Im folgenden Beispiel wird die Apache Arrow-Schnittstelle RecordBatch 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  Ausführen.

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 Standard-UDFs verwendet wird Von der vektorisierten UDF verwendeter Pandas-Datentyp PyArrow-Datentyp für ARRAY und STRUCT in vektorisierten UDFs
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 Datentyp des Elements ein pandas.ArrowDtype ist. ListType
STRUCT dict struct<...>[pyarrow], wobei der Datentyp des Felds pandas.ArrowDtype ist StructType

Unterstützte Laufzeitversionen

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

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
grpcio 1.76.0
grpcio-protobuf 6.33.5tools 1.76.0
typing-extensions 4.15.0

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  Ausführen.

Zusätzliche Python-Dateien als Bibliotheken importieren

Sie können Ihre Python-UDFs mithilfe 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://my_bucket/path/to/lib1.py'])
AS r"""
import path.to.lib1 as lib1

def compute(a, b):
  # doInterestingStuff is a function defined in
  # gs://my_bucket/path/to/lib1.py
  return lib1.doInterestingStuff(a, b);

""";

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

  3. Klicken Sie auf  Ausführen.

Containerlimits für Python-UDFs konfigurieren

Mit der Optionsliste 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`.resizeImage(image BYTES)
RETURNS BYTES LANGUAGE python
OPTIONS (entry_point='resize_image', runtime_version='python-3.11',
packages=['Pillow==11.2.1'], container_memory='CONTAINER_MEMORY', container_cpu=CONTAINER_CPU,
container_request_concurrency=CONTAINER_REQUEST_CONCURRENCY)
AS r"""
import io
from PIL import Image

def resize_image(image_bytes):
  img = Image.open(io.BytesIO(image_bytes))

  resized_img = img.resize((256, 256), Image.Resampling.LANCZOS)
  output_stream = io.BytesIO()
  resized_img.convert('RGB').save(output_stream, format='JPEG')
  return output_stream.getvalue()
""";

    Ersetzen Sie 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). Zum Beispiel 2Gi.
    • CONTAINER_CPU: Der CPU-Wert. Python-UDFs unterstützen CPU-Bruchteilwerte zwischen 0.33 und 1.0 sowie nicht bruchteilige 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  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. Teilwerte für die Eingabe 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:

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
Größer als 4Gi und bis zu 8Gi 2 4
Größer als 8Gi und bis zu 16Gi 4 4

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:

CPU Mindestspeicher Maximaler Arbeitsspeicher
Weniger als 0.5 256Mi 512Mi
0.5 auf 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 erteilt werden. Die erforderlichen Berechtigungen hängen vom Dienst ab, auf den zugegriffen wird, und von den APIs, die von Ihrem Python-Code aufgerufen werden.

Wenn Sie eine Python-UDF ohne Verwendung einer Cloud-Ressourcenverbindung erstellen, wird die Funktion in einer Umgebung ausgeführt, 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.

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

Cloud-Ressourcen-Verbindung erstellen

Zuerst erstellen Sie eine Cloud-Ressourcenverbindung in my_query_project. 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 das linke Steuerfeld nicht angezeigt wird, klicken Sie auf  Linkes Steuerfeld maximieren, um es 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 werden, werden sie aus dem Projekt und dem Standort abgeleitet, in 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 Google Cloud Projekt-ID
    • 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.iam.gserviceaccount.com"}

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

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 Standardprojekt Google Cloud 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 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 die Rolle Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) in my_query_project und die Rolle Cloud Translation API User (roles/cloudtranslate.user) in my_translate_project zu.

  1. Rufen Sie die IAM-Seite auf.

    IAM aufrufen

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

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

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}/locations/us-central1",
            "contents": [x],
            "target_language_code": "es",
            "mime_type": "text/plain",
        },
        retry=Retry(),
    )
    return response.translations[0].translated_text

""";

-- Call the UDF.
WITH text_table AS
  (SELECT "Hello" AS text
  UNION ALL
  SELECT "Good morning" AS text
  UNION ALL
  SELECT "Goodbye" AS text)
SELECT text,
`PROJECT_ID.DATASET_ID`.translate_to_es(text) AS translated_text
FROM text_table;

    Ersetzen Sie Folgendes:

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

  3. Klicken Sie auf  Ausführen.

    Die Ausgabe sollte so aussehen:

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

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.
  • Vermeiden Sie UDFs in bedingten Ausdrücken.
  • Vermeiden Sie die Verwendung von nutzerdefinierten Funktionen zum direkten Einbetten von STRUCT-Feldern.
  • UDFs in Prognosen isolieren Damit die Batchverarbeitung erfolgt, führen Sie die UDF in einer SELECT-Anweisung mit einem allgemeinen Tabellenausdruck (Common Table Expression, CTE) oder einer Unterabfrage aus. Führen Sie dann in einem separaten Schritt Filter oder Joins für dieses Ergebnis aus.
  • Daten-Payload optimieren Die Größe einzelner Zeilen kann sich auf die Effizienz der Batching-Funktion auswirken.
  • Zeilengröße minimieren 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.
  • Containerlimits effizient konfigurieren Die Skalierbarkeit hängt von CPU, Arbeitsspeicher und der Nebenläufigkeit von Anfragen ab.
  • 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.
  • Ressourcen skalieren Wenn die Monitoringmesswerte eine hohe Auslastung zeigen, erhöhen Sie die zugewiesene CPU und den zugewiesenen Arbeitsspeicher.
  • Externe Abhängigkeiten und Zuverlässigkeit verwalten. Für nutzerdefinierte Funktionen, die mit externen Diensten interagieren, sind eine Verbindung und entsprechende Berechtigungen erforderlich.
  • 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. Mit diesen Messwerten 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:

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 an. 102.% 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. 102.% 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

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

  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.

Unterstützte Standorte

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

Preise

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

Wenn die Abrechnung aktiviert ist, gilt Folgendes:

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

Kontingente

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