BigQuery DataFrames in dbt verwenden

dbt (data build tool) ist ein Open-Source-Befehlszeilen Framework, das für die Datentransformation in modernen Data Warehouses entwickelt wurde. dbt ermöglicht modulare Datentransformationen durch die Erstellung wiederverwendbarer SQL und Python-basierter Modelle. Das Tool orchestriert die Ausführung dieser Transformationen im Ziel-Data-Warehouse und konzentriert sich dabei auf den Transformationsschritt der ELT-Pipeline. Weitere Informationen finden Sie in der dbt-Dokumentation.

In dbt ist ein Python-Modell eine Datentransformation, die mit Python-Code in Ihrem dbt-Projekt definiert und ausgeführt wird. Anstatt SQL für die Transformationslogik zu schreiben, schreiben Sie Python-Skripts, die dann von dbt in der Data Warehouse-Umgebung ausgeführt werden. Mit einem Python-Modell können Sie Datentransformationen ausführen, die in SQL möglicherweise komplex oder ineffizient sind. Dabei werden die Funktionen von Python genutzt und gleichzeitig die Vorteile der dbt-Projektstruktur, -Orchestrierung, -Abhängigkeitsverwaltung, -Tests und -Dokumentationsfunktionen genutzt. Weitere Informationen finden Sie unter Python-Modelle.

Der dbt-bigquery Adapter unterstützt die Ausführung von Python-Code, der in BigQuery DataFrames definiert ist. Diese Funktion ist in dbt Cloud und dbt Core verfügbar. Sie können diese Funktion auch erhalten, indem Sie die neueste Version des dbt-bigquery-Adapters klonen.

Hinweis

Aktivieren Sie die folgenden APIs in Ihrem Projekt, um den dbt-bigquery-Adapter zu verwenden:

  • BigQuery API (bigquery.googleapis.com)
  • Cloud Storage API (storage.googleapis.com)
  • Compute Engine API (compute.googleapis.com)
  • Dataform API (dataform.googleapis.com)
  • Identity and Access Management API (iam.googleapis.com)
  • Vertex AI API (aiplatform.googleapis.com)

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen.

APIs aktivieren

Erforderliche Rollen

Der dbt-bigquery-Adapter unterstützt die OAuth-basierte und die dienstkontobasierte Authentifizierung. In den folgenden Abschnitten werden die erforderlichen Rollen je nach geplanter Authentifizierungsmethode beschrieben.

OAuth

Wenn Sie sich mit OAuth beim dbt-bigquery-Adapter authentifizieren möchten, bitten Sie Ihren Administrator, Ihnen die folgenden Rollen zuzuweisen:

Dienstkonto

Wenn Sie sich mit einem Dienstkonto in Ihrem Projekt beim dbt-bigquery-Adapter authentifizieren möchten, bitten Sie Ihren Administrator, dem Dienstkonto, das Sie verwenden möchten, die folgenden Rollen zuzuweisen:

Wenn Sie sich mit einem Dienstkonto authentifizieren, müssen Sie auch die Rolle „Dienstkontonutzer“ (roles/iam.serviceAccountUser) für das Dienstkonto haben, das Sie verwenden möchten.

Identitätsübertragung für ein Dienstkonto

Wenn Sie sich mit OAuth beim dbt-bigquery-Adapter authentifizieren möchten, die Datenverarbeitung und Notebook-Ausführung aber unter der Identität eines Dienstkontos im selben Projekt erfolgen sollen, in dem die Jobs ausgeführt werden, bitten Sie Ihren Administrator, Ihnen die folgenden Rollen zuzuweisen:

Das übertragene Dienstkonto muss auch alle für die Authentifizierung erforderlichen Rollen haben.

Projektübergreifende Dienstkonten

Wenn Sie sich mit einem Dienstkonto in einem anderen Projekt beim dbt-bigquery Adapter authentifizieren möchten, dem Projekt mit Anmeldedaten, von dem aus die Jobs ausgeführt werden, dem Ausführungsprojekt, bitten Sie Ihren Administrator, Folgendes zu tun:

  1. Deaktivieren Sie die Einschränkung constraints/iam.disableCrossProjectServiceAccountUsage im Projekt mit Anmeldedaten.

  2. Weisen Sie dem Dienstkonto im Projekt mit Anmeldedaten zusätzlich zu allen für die Dienstkontoauthentifizierung erforderlichen Rollen, die folgenden Rollen zu:

Wenn Sie sich mit OAuth beim dbt-bigquery-Adapter authentifizieren möchten, die Datenverarbeitung und Notebook-Ausführung aber unter der Identität eines Dienstkontos in einem anderen Projekt erfolgen sollen, von dem aus die Jobs ausgeführt werden, bitten Sie Ihren Administrator, Folgendes zu tun:

Freigegebene VPC

Wenn Sie Colab Enterprise in einer Umgebung mit freigegebene VPC verwenden, bitten Sie Ihren Administrator, die folgenden Rollen und Berechtigungen zuzuweisen:

  • compute.subnetworks.use Berechtigung: Weisen Sie diese Berechtigung dem Dienstkonto zu, das von der Colab Enterprise-Laufzeit im Host Projekt oder in bestimmten Subnetzen verwendet wird. Diese Berechtigung ist in der Rolle „Compute Network User“ (roles/compute.networkUser) enthalten.

  • compute.subnetworks.get Berechtigung: Weisen Sie diese Berechtigung dem Dienstkonto zu, das von der Colab Enterprise-Laufzeit im Hostprojekt oder in bestimmten Subnetzen verwendet wird. Diese Berechtigung ist in der Rolle „Compute Network Viewer“ (roles/compute.networkViewer) enthalten.

  • Rolle „Compute Network User“ (roles/compute.networkUser): Weisen Sie diese Rolle dem Vertex AI-Dienst Agent service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, im Hostprojekt der freigegebene VPC zu.

  • Rolle „Compute Network User“ (roles/compute.networkUser): Wenn die Funktion für den Notebook-Ausführungsjob verwendet wird, weisen Sie diese Rolle dem Colab Enterprise-Dienst-Agent service-PROJECT_NUMBER@gcp-sa-vertex-nb.iam.gserviceaccount.com, im Hostprojekt der freigegebene VPC zu.

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

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollenerhalten.

Python-Ausführungsumgebung

Der dbt-bigquery Adapter verwendet den Colab Enterprise-Notebook-Ausführungsdienst um den BigQuery DataFrames-Python-Code auszuführen. Für jedes Python-Modell wird automatisch ein Colab Enterprise-Notebook vom dbt-bigquery-Adapter erstellt und ausgeführt. Sie können das Google Cloud Projekt auswählen, in dem das Notebook ausgeführt werden soll. Das Notebook führt den Python-Code aus dem Modell aus, der von der BigQuery DataFrames-Bibliothek in BigQuery-SQL konvertiert wird. Das BigQuery-SQL wird dann im konfigurierten Projekt ausgeführt. Das folgende Diagramm zeigt den Kontrollfluss:

BigQuery DataFrames-Python-Ausführungsumgebung für ein Notebook

Wenn im Projekt noch keine Notebook-Vorlage verfügbar ist und der Nutzer, der den Code ausführt, die Berechtigungen zum Erstellen der Vorlage hat, erstellt und verwendet der dbt-bigquery-Adapter automatisch die Standard-Notebook-Vorlage. Sie können auch eine andere Notebook-Vorlage mit einer dbt-Konfiguration angeben.

Für die Notebook-Ausführung ist ein Cloud Storage-Staging-Bucket zum Speichern des Codes und der Logs erforderlich. Der dbt-bigquery-Adapter kopiert die Logs jedoch in die dbt-Logs, sodass Sie den Bucket nicht durchsuchen müssen.

Unterstützte Features

Der dbt-bigquery-Adapter unterstützt die folgenden Funktionen für dbt-Python-Modelle, die BigQuery DataFrames ausführen:

  • Daten aus einer vorhandenen BigQuery-Tabelle mit dem Makro dbt.source() laden.
  • Daten aus anderen dbt-Modellen mit dem Makro dbt.ref() laden, um Abhängigkeiten zu erstellen und gerichtete azyklische Graphen (DAGs) mit Python-Modellen zu erstellen.
  • Python-Pakete von PyPi angeben und verwenden, die mit der Python-Codeausführung verwendet werden können. Weitere Informationen finden Sie unter Konfigurationen.
  • Eine benutzerdefinierte Notebook-Laufzeitvorlage für Ihre BigQuery DataFrames-Modelle angeben.

Der dbt-bigquery Adapter unterstützt die folgenden Materialisierungsstrategien:

  • Tabellenmaterialisierung, bei der Daten bei jeder Ausführung als Tabelle neu erstellt werden.
  • Inkrementelle Materialisierung mit einer Zusammenführungsstrategie, bei der einer vorhandenen Tabelle neue oder aktualisierte Daten hinzugefügt werden. Dabei wird häufig eine Zusammenführungsstrategie verwendet, um Änderungen zu verarbeiten.

dbt für die Verwendung von BigQuery DataFrames einrichten

Wenn Sie dbt Core verwenden, benötigen Sie eine profiles.yml Datei für die Verwendung mit BigQuery DataFrames. Im folgenden Beispiel wird die Methode oauth verwendet:

your_project_name:
  outputs:
    dev:
      compute_region: us-central1
      dataset: your_bq_dateset
      gcs_bucket: your_gcs_bucket
      job_execution_timeout_seconds: 300
      job_retries: 1
      location: US
      method: oauth
      priority: interactive
      project: your_gcp_project
      threads: 1
      type: bigquery
  target: dev

Wenn Sie dbt Cloud verwenden, können Sie sich direkt in der dbt Cloud-Oberfläche mit Ihrer Datenplattform verbinden. In diesem Fall benötigen Sie keine profiles.yml-Datei. Weitere Informationen finden Sie unter About profiles.yml.

Dies ist ein Beispiel für eine Konfiguration auf Projektebene für die Datei dbt_project.yml:

# Name your project! Project names should contain only lowercase characters
# and underscores. A good package name should reflect your organization's
# name or the intended use of these models.
name: 'your_project_name'
version: '1.0.0'

# Configuring models
# Full documentation: https://docs.getdbt.com/docs/configuring-models

# In this example config, we tell dbt to build all models in the example/
# directory as views. These settings can be overridden in the individual model
# files using the config(...) macro.

models:
  your_project_name:
    submission_method: bigframes
    notebook_template_id: 7018811640745295872
    packages: ["scikit-learn", "mlflow"]
    timeout: 3000
    # Config indicated by + and applies to all files under models/example/
    example:
      +materialized: view

Einige Parameter können auch mit der Methode dbt.config in Ihrem Python-Code konfiguriert werden. Wenn diese Einstellungen mit Ihrer dbt_project.yml-Datei in Konflikt stehen, haben die Konfigurationen mit dbt.config Vorrang.

Weitere Informationen finden Sie unter Model configurations und dbt_project.yml.

Konfigurationen

Sie können die folgenden Konfigurationen mit der Methode dbt.config in Ihrem Python-Modell einrichten. Diese Konfigurationen überschreiben die Konfiguration auf Projektebene.

Konfiguration Erforderlich Nutzung
submission_method Ja submission_method=bigframes
notebook_template_id Nein Wenn nicht angegeben, wird eine Standardvorlage erstellt und verwendet.
packages Nein Geben Sie bei Bedarf die zusätzliche Liste der Python-Pakete an.
timeout Nein Optional: Verlängern Sie das Zeitlimit für die Jobausführung.

Beispiel für Python-Modelle

In den folgenden Abschnitten werden Beispielszenarien und Python-Modelle vorgestellt.

Daten aus einer BigQuery-Tabelle laden

Wenn Sie Daten aus einer vorhandenen BigQuery-Tabelle als Quelle in Ihrem Python-Modell verwenden möchten, definieren Sie diese Quelle zuerst in einer YAML-Datei. Das folgende Beispiel ist in einer source.yml-Datei definiert.

version: 2

sources:
  - name: my_project_source   # A custom name for this source group
    database: bigframes-dev   # Your Google Cloud project ID
    schema: yyy_test_us       # The BigQuery dataset containing the table
    tables:
      - name: dev_sql1        # The name of your BigQuery table

Anschließend erstellen Sie Ihr Python-Modell, das die in dieser YAML-Datei konfigurierten Datenquellen verwenden kann:

def model(dbt, session):
    # Configure the model to use BigFrames for submission
    dbt.config(submission_method="bigframes")

    # Load data from the 'dev_sql1' table within 'my_project_source'
    source_data = dbt.source('my_project_source', 'dev_sql1')

    # Example transformation: Create a new column 'id_new'
    source_data['id_new'] = source_data['id'] * 10

    return source_data

Auf ein anderes Modell verweisen

Sie können Modelle erstellen, die von der Ausgabe anderer dbt-Modelle abhängen, wie im folgenden Beispiel gezeigt. Dies ist nützlich, um modulare Datenpipelines zu erstellen.

def model(dbt, session):
    # Configure the model to use BigFrames
    dbt.config(submission_method="bigframes")

    # Reference another dbt model named 'dev_sql1'.
    # It assumes you have a model defined in 'dev_sql1.sql' or 'dev_sql1.py'.
    df_from_sql = dbt.ref("dev_sql1")

    # Example transformation on the data from the referenced model
    df_from_sql['id'] = df_from_sql['id'] * 100

    return df_from_sql

Eine Paketabhängigkeit angeben

Wenn Ihr Python-Modell bestimmte Bibliotheken von Drittanbietern wie MLflow oder Boto3, erfordert, können Sie das Paket in der Konfiguration des Modells deklarieren, wie im folgenden Beispiel gezeigt. Diese Pakete werden in der Ausführungsumgebung installiert.

def model(dbt, session):
    # Configure the model for BigFrames and specify required packages
    dbt.config(
        submission_method="bigframes",
        packages=["mlflow", "boto3"]  # List the packages your model needs
    )

    # Import the specified packages for use in your model
    import mlflow
    import boto3

    # Example: Create a DataFrame showing the versions of the imported packages
    data = {
        "mlflow_version": [mlflow.__version__],
        "boto3_version": [boto3.__version__],
        "note": ["This demonstrates accessing package versions after import."]
    }
    bdf = bpd.DataFrame(data)

    return bdf

Eine nicht standardmäßige Vorlage angeben

Wenn Sie mehr Kontrolle über die Ausführungsumgebung haben oder vorkonfigurierte Einstellungen verwenden möchten, können Sie eine nicht standardmäßige Notebook-Vorlage für Ihr BigQuery DataFrames-Modell angeben, wie im folgenden Beispiel gezeigt.

def model(dbt, session):
    dbt.config(
        submission_method="bigframes",
     # ID of your pre-created notebook template
        notebook_template_id="857350349023451yyyy",
    )

    data = {"int": [1, 2, 3], "str": ['a', 'b', 'c']}
    return bpd.DataFrame(data=data)

Tabellen materialisieren

Wenn dbt Ihre Python-Modelle ausführt, muss es wissen, wie die Ergebnisse in Ihrem Data Warehouse gespeichert werden. Dieser Vorgang wird als Materialisierung bezeichnet.

Bei der Standardtabellenmaterialisierung erstellt oder ersetzt dbt bei jeder Ausführung eine Tabelle in Ihrem Data Warehouse vollständig durch die Ausgabe Ihres Modells. Dies erfolgt standardmäßig oder indem Sie die Eigenschaft materialized='table' explizit festlegen, wie im folgenden Beispiel gezeigt.

def model(dbt, session):
    dbt.config(
        submission_method="bigframes",
     # Instructs dbt to create/replace this model as a table
        materialized='table',
    )

    data = {"int_column": [1, 2], "str_column": ['a', 'b']}
    return bpd.DataFrame(data=data)

Mit der inkrementellen Materialisierung mit einer Zusammenführungsstrategie kann dbt Ihre Tabelle nur mit neuen oder geänderten Zeilen aktualisieren. Dies ist für große Datasets nützlich, da das vollständige Neuerstellen einer Tabelle bei jeder Ausführung ineffizient sein kann. Die Zusammenführungsstrategie ist eine gängige Methode, um diese Aktualisierungen zu verarbeiten.

Bei diesem Ansatz werden Änderungen auf intelligente Weise integriert, indem Folgendes geschieht:

  • Vorhandene Zeilen werden aktualisiert, die sich geändert haben.
  • Neue Zeilen werden hinzugefügt.
  • Optional, je nach Konfiguration: Zeilen werden gelöscht, die in der Quelle nicht mehr vorhanden sind.

Wenn Sie die Zusammenführungsstrategie verwenden möchten, müssen Sie eine unique_key-Eigenschaft angeben, mit der dbt die übereinstimmenden Zeilen zwischen der Ausgabe Ihres Modells und der vorhandenen Tabelle identifizieren kann, wie im folgenden Beispiel gezeigt.

def model(dbt, session):
    dbt.config(
        submission_method="bigframes",
        materialized='incremental',
        incremental_strategy='merge',
        unique_key='int',  # Specifies the column to identify unique rows
    )

    # In this example:
    # - Row with 'int' value 1 remains unchanged.
    # - Row with 'int' value 2 has been updated.
    # - Row with 'int' value 4 is a new addition.
    # The 'merge' strategy will ensure that only the updated row ('int 2')
    # and the new row ('int 4') are processed and integrated into the table.
    data = {"int": [1, 2, 4], "str": ['a', 'bbbb', 'd']}
    return bpd.DataFrame(data=data)

Fehlerbehebung

Sie können die Python-Ausführung in den dbt-Logs beobachten.

Außerdem können Sie den Code und die Logs (einschließlich früherer Ausführungen) auf der Seite Colab Enterprise-Ausführungen ansehen.

Zu „Colab Enterprise-Ausführungen“

Abrechnung

Bei Verwendung des dbt-bigquery-Adapters mit BigQuery DataFrames fallen Kosten für Folgendes an: Google Cloud

  • Notebook-Ausführung: Ihnen wird die Ausführung der Notebook-Laufzeit in Rechnung gestellt. Weitere Informationen finden Sie unter Preise für Notebook-Laufzeiten.

  • BigQuery-Abfrageausführung: Im Notebook konvertiert BigQuery DataFrames Python in SQL und führt den Code in BigQuery aus. Die Kosten richten sich nach Ihrer Projekt konfiguration und Ihrer Abfrage, wie unter Preise für BigQuery DataFrames beschrieben.

Sie können das folgende Abrechnungslabels in der BigQuery-Abrechnungskonsole verwenden, um den Abrechnungsbericht für die Notebook-Ausführung und für die von dbt-bigquery-Adapter ausgelösten BigQuery-Ausführungen herauszufiltern:

  • BigQuery-Ausführungslabels: bigframes-dbt-api

Nächste Schritte