Mit Remote-Funktionen arbeiten

Mit einer BigQuery-Remote-Funktion können Sie Ihre Funktion in anderen Sprachen als SQL und JavaScript oder mit den Bibliotheken oder Diensten implementieren, die in benutzerdefinierten Funktionen in BigQuery nicht zulässig sind.

Übersicht

Mit einer BigQuery-Remote-Funktion können Sie GoogleSQL-Funktionen in Software außerhalb von BigQuery einbinden. Stellen Sie dazu eine direkte Integration mit Cloud Run-Funktionen und Cloud Run bereit. Mit den BigQuery-Remote-Funktionen können Sie Ihre Funktionen in Cloud Run-Funktionen oder Cloud Run bereitstellen, die mit einer beliebigen unterstützten Sprache implementiert sind, und sie dann über GoogleSQL-Abfragen aufrufen.

Workflow

  1. Erstellen Sie den HTTP-Endpunkt in Cloud Run Funktionen oder Cloud Run.
  2. Erstellen Sie eine Remote-Funktion in BigQuery.
    1. Erstellen Sie eine Verbindung vom Typ CLOUD_RESOURCE.
    2. Erstellen Sie eine Remote-Funktion.
  3. Sie können die Remote-Funktion in einer Abfrage wie alle anderen benutzerdefinierten Funktionen verwenden.

Beschränkungen

  • Remote-Funktionen unterstützen nur einen der folgenden Datentypen als Argument- oder Rückgabetyp:

    • Boolesch
    • Byte
    • Numerisch
    • String
    • Datum
    • Datum/Uhrzeit
    • Zeit
    • Zeitstempel
    • JSON

    Remote-Funktionen unterstützen die Typen ARRAY, STRUCT, INTERVAL oder GEOGRAPHY nicht.

  • Sie können keine temporären Remote-Funktionen erstellen.

  • Tabellenwert-Remote-Funktionen mit können nicht erstellt werden.

  • Sie können keine Remote-Funktionen beim Erstellen von materialisierten Ansichten verwenden.

  • Es wird davon ausgegangen, dass der Rückgabewert einer Remote-Funktion nicht deterministisch ist, sodass das Ergebnis einer Abfrage, die eine Remote-Funktion aufruft, nicht im Cache gespeichert wird.

  • Vorübergehende Anfragen mit denselben Daten an Ihrem Endpunkt können aufgrund vorübergehender Netzwerkfehler oder interner BigQuery-Fehler auch nach erfolgreichen Antworten wiederholt werden.

  • Wenn eine Remote-Funktionsbewertung für einige Zeilen aufgrund der Kurzschlussauswertung übersprungen wird, z. B. in bedingten Ausdrücken oder einer MERGE-Anweisung mit WHEN [NOT] MATCHED, wird die Batchverarbeitung nicht mit der Remote-Funktion verwendet. In diesem Fall hat das Feld calls im HTTP-Anfragetext genau ein Element.

  • Wenn das mit der Remote-Funktion verknüpfte Dataset über eine regionenübergreifende Dataset-Replikation in eine Zielregion repliziert wird, kann die Remote-Funktion nur in der Region abgefragt werden, in der sie erstellt wurde.

Endpunkt erstellen

Zum Erstellen einer Remote-Funktion, die Geschäftslogik implementieren kann, müssen Sie einen HTTP-Endpunkt mithilfe von Cloud Run-Funktionen oder Cloud Run erstellen. Der Endpunkt muss einen Zeilen-Batch in einer einzelnen HTTP-POST-Anfrage verarbeiten und die Ergebnisse für den Batch als HTTP-Antwort zurückgeben können.

Wenn Sie die Remote-Funktion mit BigQuery DataFrames erstellen, müssen Sie den HTTP-Endpunkt nicht manuell erstellen. Der Dienst erledigt das automatisch.

Informationen zum Schreiben, Bereitstellen, Testen und Verwalten einer Cloud Run-Funktion finden Sie in der Anleitung zu Cloud Run-Funktionen und in der weiteren Dokumentation zu Cloud Run-Funktionen.

In der Cloud Run-Kurzanleitung und anderen Cloud Run-Dokumentationen erfahren Sie, wie Sie einen Cloud Run-Dienst schreiben, bereitstellen, testen und warten.

Es wird empfohlen, die Standardauthentifizierung beizubehalten statt einen nicht authentifizierten Aufruf Ihrer Cloud Run-Funktion oder Ihres Cloud Run-Dienstes zuzulassen.

Eingabeformat

BigQuery sendet HTTP-POST-Anfragen mit JSON-Text im folgenden Format:

Feldname Beschreibung Feldtyp
requestId ID der Anfrage. Eindeutiger Wert für mehrere Anfragen, die in einer GoogleSQL-Abfrage an diesen Endpunkt gesendet werden. Immer bereitgestellt. String.
Aufrufer Vollständiger Ressourcenname des Jobs für die GoogleSQL-Abfrage, die die Remote-Funktion aufruft. Immer bereitgestellt. String.
sessionUser E-Mail-Adresse des Nutzers, der die GoogleSQL-Abfrage ausführt. Immer bereitgestellt. String.
userDefinedContext Der benutzerdefinierte Kontext, der beim Erstellen der Remote-Funktion in BigQuery verwendet wurde. Optional. Ein JSON-Objekt mit Schlüssel/Wert-Paaren.
Aufrufe Ein Eingabedaten-Batch. Immer bereitgestellt. Ein JSON-Array.

Jedes Element selbst ist ein JSON-Array, das eine JSON-codierte Argumentenliste eines Remote-Funktionsaufrufs ist.

Beispiel für eine Anfrage:

{
 "requestId": "124ab1c",
 "caller": "//bigquery.googleapis.com/projects/myproject/jobs/myproject:US.bquxjob_5b4c112c_17961fafeaf",
 "sessionUser": "test-user@test-company.com",
 "userDefinedContext": {
  "key1": "value1",
  "key2": "v2"
 },
 "calls": [
  [null, 1, "", "abc"],
  ["abc", "9007199254740993", null, null]
 ]
}

Ausgabeformat

BigQuery erwartet, dass der Endpunkt eine HTTP-Antwort im folgenden Format zurückgibt. Andernfalls kann BigQuery ihn nicht verarbeiten und lässt die Abfrage, die die Remote-Funktion aufruft, fehlschlagen.

Feldname Beschreibung Wertebereich
 Antworten Ein Rückgabewerte-Batch. Erforderlich für eine erfolgreiche Antwort. Ein JSON-Array.

Jedes Element entspricht einem JSON-codierten Rückgabewert der externen Funktion.

Die Größe des Arrays muss mit der Größe des JSON-Arrays von calls in der HTTP-Anfrage übereinstimmen. Wenn das JSON-Array in calls beispielsweise vier Elemente hat, muss dieses JSON-Array auch vier Elemente haben.

errorMessage Fehlermeldung, wenn ein anderer HTTP-Antwortcode als 200 zurückgegeben wird. Bei nicht wiederholbaren Fehlern geben wir dies als Teil der Fehlermeldung des BigQuery-Jobs an den Nutzer zurück. Optional. String. Die Größe sollte kleiner als 1 KB sein.

Beispiel für eine erfolgreiche Antwort:

{
  "replies": [
    1,
    0
  ]
}

Beispiel für eine fehlgeschlagene Antwort:

{
  "errorMessage": "Received but not expected that the argument 0 be null".
}

HTTP-Antwortcode

Der Endpunkt sollte den HTTP-Antwortcode 200 für eine erfolgreiche Antwort zurückgeben. Wenn BigQuery einen beliebigen anderen Wert empfängt, betrachtet BigQuery die Antwort als Fehler und wiederholt den Vorgang, wenn der HTTP-Antwortcode 408, 429, 500, 503 oder 504 bis zu einem internen Limit ist.

JSON-Codierung des SQL-Datentyps

Die JSON-Codierung in der HTTP-Anfrage/-Antwort folgt der vorhandenen BigQuery-JSON-Codierung für die TO_JSON_STRING-Funktion.

Beispiel für Cloud Run-Funktionscode

Im folgenden Python-Beispielcode wird das Hinzufügen aller Ganzzahlargumente der Remote-Funktion implementiert. Er verarbeitet eine Anfrage mit den Argumenten für Batchaufrufe und gibt das gesamte Ergebnis in einer Antwort zurück.

import functions_framework

from flask import jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992

@functions_framework.http
def batch_add(request):
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return_json = jsonify( { "replies":  replies } )
    return return_json
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

Angenommen, die Funktion wird im Projekt my_gcf_project in der Region us-east1 als Funktionsname remote_add bereitgestellt und kann über den Endpunkt https://us-east1-my_gcf_project.cloudfunctions.net/remote_add aufgerufen werden.

Cloud Run-Beispielcode

Im folgenden Python-Beispielcode wird ein Webdienst implementiert, der für dieselbe Funktionalität in Cloud Run erstellt und bereitgestellt werden kann.

import os

from flask import Flask, request, jsonify

# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992

app = Flask(__name__)

@app.route("/", methods=['POST'])
def batch_add():
  try:
    return_value = []
    request_json = request.get_json()
    calls = request_json['calls']
    for call in calls:
      return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
    replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
    return jsonify( { "replies" :  replies } )
  except Exception as e:
    return jsonify( { "errorMessage": str(e) } ), 400

if __name__ == "__main__":
    app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Weitere Informationen zum Erstellen und Bereitstellen des Codes finden Sie in der Anleitung.

Angenommen, der Cloud Run-Dienst wird im Projekt my_gcf_project in der Region us-east1 als Dienstname remote_add bereitgestellt, auf den über den Endpunkt https://remote_add-<project_id_hash>-ue.a.run.app zugegriffen werden kann.

Remote-Funktion erstellen

BigQuery verwendet eine CLOUD_RESOURCE-Verbindung für die Interaktion mit Ihrer Cloud Run-Funktion. Zum Erstellen einer Remote-Funktion müssen Sie eine CLOUD_RESOURCE-Verbindung herstellen. Wenn Sie die Remote-Funktion mit BigQuery DataFrames erstellen und Ihnen die Rolle „Project IAM Admin“ (roles/resourcemanager.projectIamAdmin-Rolle) zugewiesen wurde, müssen Sie die Verbindung nicht manuell erstellen und ihr Zugriff gewähren. Der Dienst erledigt das automatisch.

Verbindung herstellen

Sie benötigen eine Cloud-Ressourcenverbindung, um eine Verbindung zu einer Cloud Run-Funktion und Cloud Run herzustellen.

Wählen Sie eine der folgenden Optionen aus:

Console

  1. Rufen Sie die Seite BigQuery auf.

    BigQuery aufrufen

  2. Klicken Sie auf Hinzufügen und dann auf Verbindungen zu externen Datenquellen, um eine Verbindung zu erstellen.

  3. Wählen Sie in der Liste Verbindungstyp die Option Vertex AI-Remote-Modelle, Remote-Funktionen und BigLake (Cloud Resource) aus.

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

  5. Klicken Sie auf Verbindung erstellen.

  6. Klicken Sie auf Zur Verbindung.

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

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 in etwa so aus:

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

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.

Zugriff einrichten

Sie müssen der neuen Verbindung Lesezugriff auf Ihre Cloud Run-Funktion oder Ihren Cloud Run-Dienst gewähren. Es wird nicht empfohlen, einen nicht authentifizierten Aufruf für Ihre Cloud Run-Funktion oder Ihren Cloud Run-Dienst zuzulassen.

So weisen Sie Rollen zu:

  1. Zur Seite IAM & Verwaltung.

    IAM & Verwaltung aufrufen

  2. Klicken Sie auf Hinzufügen.

    Das Dialogfeld Principals hinzufügen wird geöffnet.

  3. Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID ein, die Sie zuvor kopiert haben.

  4. Wählen Sie im Feld Rolle auswählen eine der folgenden Optionen aus:

    • Wenn Sie eine Cloud Run-Funktion der 1. Generation verwenden, wählen Sie Cloud Functions-Funktion und dann Rolle „Cloud Functions-Aufrufer“ aus.
    • Wenn Sie eine Cloud Run-Funktion der 2. Generation verwenden, wählen Sie Cloud Run und dann Rolle „Cloud Run Invoker” aus.
    • Wenn Sie einen Cloud Run-Dienst verwenden, wählen Sie Cloud Run und dann Cloud Run Aufrufer-rolle aus.

  5. Klicken Sie auf Speichern.

Remote-Funktion erstellen

So erstellen Sie eine Remote-Funktion:

SQL

Führen Sie in BigQuery die folgende CREATE FUNCTION-Anweisung aus:

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    CREATE FUNCTION PROJECT_ID.DATASET_ID.remote_add(x INT64, y INT64) RETURNS INT64
REMOTE WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
OPTIONS (
  endpoint = 'ENDPOINT_URL'
)

    Ersetzen Sie Folgendes:

    • DATASET_ID: Die ID Ihres BigQuery-Datasets.
    • ENDPOINT_URL ist die URL des Endpunkts Ihrer Cloud Run- oder Cloud Run-Remote-Funktion.

  3. Klicken Sie auf Ausführen.

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

BigQuery DataFrames

  1. Aktivieren Sie die erforderlichen APIs und prüfen Sie, ob Sie die erforderlichen Rollen haben, wie im Abschnitt Anforderungen von Remote-Funktionen beschrieben wurde.

  2. Verwenden Sie den Decorator remote_function:

    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 scalar
# functions into a BigQuery remote function. It requires the GCP project to
# be set up appropriately and the user having sufficient privileges to use
# them. One can find more details about the usage and the requirements via
# `help` command.
help(bpd.remote_function)

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

# Define a custom function, and specify the intent to turn it into a remote
# function. It requires a BigQuery connection. If the connection is not
# already created, BigQuery DataFrames will attempt to create one assuming
# the necessary APIs and IAM permissions are setup in the project. In our
# examples we will be letting the default connection `bigframes-default-connection`
# be used. We will also set `reuse=False` to make sure we don't
# step over someone else creating remote function in the same project from
# the exact same source code at the same time. Let's try a `pandas`-like use
# case in which we want to apply a user defined scalar 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.remote_function(
    float,
    str,
    reuse=False,
)
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 remote function 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"]].head(10)

# The above operation was possible by doing all the computation on the
# cloud. For that, there is a google cloud function deployed by serializing
# the user code, and a BigQuery remote function created to call the cloud
# function via the latter's http endpoint on the data in the DataFrame.

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

# The cloud function can be located via another property
# `bigframes_cloud_function` set in the remote function object.
print(f"Created cloud function: {get_bucket.bigframes_cloud_function}")

# Warning: The deployed cloud function may be visible to other users with
# sufficient privilege in the project, so the user should be careful about
# having any sensitive data in the code that will be deployed as a remote
# function.

# Let's continue trying other potential use cases of remote functions. 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 remote function. The custom function in this example has external
# package dependency, which can be specified via `packages` parameter.
@bpd.remote_function(
    str,
    str,
    reuse=False,
    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 remote function in another `pandas`-like API `map` that
# can be applied on a DataFrame
df_redacted = df[["species", "island", "sex"]].map(get_hash)
df_redacted.head(10)

Sie benötigen die Berechtigung bigquery.routines.create für das Dataset, in dem Sie die Remote-Funktion erstellen, und die Berechtigung bigquery.connections.delegate (über die Rolle „BigQuery Connection Admin“ verfügbar) für die Verbindung, die von der Remote-Funktion verwendet wird.

Benutzerdefinierten Kontext bereitstellen

Sie können user_defined_context in OPTIONS als Form von Schlüssel/Wert-Paaren angeben, die Teil jeder HTTP-Anfrage an den Endpunkt sind. Mit benutzerdefiniertem Kontext können Sie mehrere Remote-Funktionen erstellen, aber einen einzigen Endpunkt wiederverwenden, der je nach dem übergebenen Kontext unterschiedliche Verhaltensweisen bietet.

In folgenden Beispielen werden zwei Remote-Funktionen erstellt, um BYTES-Daten mit demselben Endpunkt zu ver- und zu entschlüsseln.

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.encrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "encryption")]
)

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.decrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
  endpoint = 'ENDPOINT_URL',
  user_defined_context = [("mode", "decryption")]
)

Anzahl der Zeilen in einer Batchanfrage beschränken

Sie können max_batching_rows in OPTIONS als maximale Anzahl von Zeilen in jeder HTTP-Anfrage angeben, um ein Cloud Run-Funktionenzeitlimit zu vermeiden. Wenn nicht angegeben, entscheidet BigQuery, wie viele Zeilen in einem Batch enthalten sind.

Remote-Funktion in einer Abfrage verwenden

Sie müssen die Berechtigung für Ihre Cloud Run-Funktion gewährt haben, damit sie für das BigQuery-Dienstkonto zugänglich ist, das der Verbindung der Remote-Funktion zugeordnet ist.

Außerdem benötigen Sie die Berechtigung bigquery.routines.get für das Dataset, in dem sich die Remote-Funktion befindet, und die Berechtigung bigquery.connections.use (über die Rolle BigQuery Connection User verfügbar) für die Verbindung, die von der Remote-Funktion verwendet wird.

Sie können Remote-Funktionen in Abfragen wie benutzerdefinierte Funktionen verwenden.

Sie können beispielsweise die remote_add-Funktion in der Beispielabfrage verwenden:

SELECT
  val,
  `PROJECT_ID.DATASET_ID`.remote_add(val, 2)
FROM
  UNNEST([NULL,2,3,5,8]) AS val;

Dieses Beispiel liefert folgende Ausgabe:

+------+-----+
|  val | f0_ |
+------+-----+
| NULL |   2 |
|    2 |   4 |
|    3 |   5 |
|    5 |   7 |
|    8 |  10 |
+------+-----+

Unterstützte Regionen

In BigQuery gibt es zwei Standortarten:

  • Eine Region ist ein bestimmter geografischer Ort, wie z. B. London.

  • Eine Multiregion ist ein großes geografisches Gebiet (beispielsweise die USA), das mindestens zwei geografische Orte enthält.

Einzelne Regionen

In einem BigQuery-Dataset mit einer Region können Sie nur eine Remote-Funktion erstellen, die eine in derselben Region bereitgestellte Cloud Run-Funktion verwendet. Beispiel:

  • Eine Remote-Funktion in einer einzelnen BigQuery-Region us-east4 kann nur eine Cloud Run-Funktion in us-east4 verwenden.

Für einzelne Regionen werden Remote-Funktionen also nur in Regionen unterstützt, die sowohl Cloud Run-Funktionen als auch BigQuery unterstützen.

Multiregionen

In einem multiregionalen BigQuery-Dataset (US, EU) können Sie nur eine Remote-Funktion erstellen, die eine Cloud Run-Funktion verwendet, die sich in einer Region innerhalb desselben größeren geografischen Bereichs (US, EU) befindet. Beispiel:

  • Eine Remote-Funktion am multiregionalen BigQuery-Standort US kann nur eine Cloud Run-Funktion verwenden, die in einer einzelnen Region im geografischen Gebiet der USA bereitgestellt wird, z. B.us-central1, us-east4, us-west2 usw.
  • Eine Remote-Funktion am multiregionalen BigQuery-Standort EU kann nur eine Cloud Run-Funktion verwenden, die in einer einzelnen Region in einem der Mitgliedsstaaten der Europäischen Union bereitgestellt ist, z. B. europe-north1, europe-west3 usw.

Weitere Informationen zu Regionen und Multiregionen finden Sie auf der Seite Dataset-Standorte. Weitere Informationen zu Cloud Run-Funktionen-Regionen finden Sie auf der Seite Standorte für Cloud Run-Funktionen.

Verbindungen

Für einen Standort mit einer oder mehreren Regionen können Sie eine Remote-Funktion nur am Standort der von Ihnen verwendeten Verbindung erstellen. Beispiel: Wenn Sie eine Remote-Funktion am multiregionalen Standort US erstellen möchten, verwenden Sie eine Verbindung am multiregionalen Standort US.

Preise

  • Es gelten die standardmäßigen BigQuery-Preise.

  • Außerdem können durch die Verwendung dieses Features Kosten für Cloud Run-Funktionen und Cloud Run anfallen. Weitere Informationen finden Sie auf den Preisseiten für Cloud Run-Funktionen und Cloud Run.

VPC Service Controls verwenden

VPC Service Controls ist ein Google Cloud-Feature, mit dem Sie einen sicheren Perimeter einrichten können, der vor Daten-Exfiltration schützt. Zum Verwenden von VPC Service Controls mit Remote-Funktionen für zusätzliche Sicherheit oder zum Verwenden von Endpunkten mit internal traffic-Einstellungen für eingehenden Traffic folgen Sie den Anweisungen Anleitung zu VPC Service Controls um Folgendes zu tun:

  1. Dienstperimeter erstellen

  2. Fügen Sie das BigQuery-Projekt der Abfrage mithilfe der Remote-Funktion in den Perimeter ein.

  3. Fügen Sie das Endpunktprojekt dem Perimeter hinzu und legen Sie Cloud Functions API oder Cloud Run API in den eingeschränkten Diensten anhand Ihres Endpunkttyps fest. Weitere Informationen finden Sie unter VPC Service Controls für Cloud Run-Funktionen und VPC Service Controls für Cloud Run.

Best Practices für Remote-Funktionen

  • Eingabe vorfiltern: Wenn die Eingabe einfach heruntergefiltert werden kann, bevor sie an eine Remote-Funktion übergeben wird, wird die Abfrage wahrscheinlich schneller und kostengünstiger.

  • Halten Sie Ihre Cloud Run-Funktion skalierbar. Die Skalierbarkeit ist eine Funktion der Mindestanzahl von Instanzen, der Maximale Anzahl von Instanzen und der Nebenläufigkeit.

    • Verwenden Sie den Standardwert für die maximale Anzahl an Instanzen Ihrer Cloud Run-Funktion, wann immer möglich.
    • Beachten Sie, dass es für die HTTP-Cloud Run-Funktionen der 1. Generation kein Standardlimit gibt. Um unbegrenzte Skalierungsereignisse mit HTTP-Cloud Run-Funktion der 1. Generation beim Testen oder in der Produktion zu vermeiden, empfehlen wir das Festlegen eines Limits, z. B. 3.000.

  • Befolgen Sie andere Cloud Run-Funktionentipps, um eine bessere Leistung zu erzielen. Remote-Funktionsabfragen, die mit einer Cloud Run-Funktion mit hoher Latenz interagieren, können aufgrund eines Zeitlimits fehlschlagen.

  • Implementieren Sie den Endpunkt, um einen korrekte Kombination aus HTTP-Antwortcode und Nutzlast für eine fehlgeschlagene Antwort zurückzugeben.

    • Verwenden Sie HTTP-Antwortcodes außer 408, 429, 500, 503 und 504 für eine fehlgeschlagene Antwort, um Wiederholungsversuche aus BigQuery zu minimieren, und achten Sie darauf, alle Ausnahmen in Ihrem Funktionscode zu erfassen. Andernfalls kann das HTTP-Service-Framework für nicht abgefangene Ausnahmen automatisch 500 zurückgeben. Möglicherweise werden weiterhin wiederholte HTTP-Anfragen angezeigt, wenn BigQuery eine fehlgeschlagene Datenpartition oder Abfrage wiederholt.

    • Der Endpunkt sollte eine JSON-Nutzlast für eine fehlgeschlagene Antwort im definierten Format zurückgeben. Obwohl dies nicht unbedingt erforderlich ist, kann BigQuery so leichter unterscheiden, ob die fehlgeschlagene Antwort von Ihrer Funktionsimplementierung oder der Infrastruktur von Cloud Run-Funktionen/Cloud Run stammt. Bei letzteren kann BigQuery es mit einem anderen internen Limit noch einmal versuchen.

Kontingente

Informationen zu Remote-Funktionskontingenten finden Sie unter Kontingente und Limits.