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 das Erstellen wiederverwendbarer SQL- und Python-basierter Modelle. Das Tool orchestriert die Ausführung dieser Transformationen im Ziel-Data Warehouse, wobei der Schwerpunkt auf dem Transformationsschritt der ELT-Pipeline liegt. Weitere Informationen finden Sie in der dbt-Dokumentation.

In dbt ist ein Python-Modell eine Datentransformation, die in Ihrem dbt-Projekt mit Python-Code definiert und ausgeführt wird. Anstatt SQL für die Transformationslogik zu schreiben, schreiben Sie Python-Scripts, die dann von dbt für die Ausführung in der Data Warehouse-Umgebung orchestriert werden. Mit einem Python-Modell können Sie Datentransformationen ausführen, die in SQL komplex oder ineffizient ausgedrückt werden können. So können Sie die Funktionen von Python nutzen und gleichzeitig von den Projektstruktur-, Orchestrierungs-, Abhängigkeitsverwaltungs-, Test- und Dokumentationsfunktionen von dbt profitieren. Weitere Informationen finden Sie unter Python-Modelle.

Der dbt-bigquery-Adapter unterstützt das Ausführen 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.

Erforderliche Rollen

Der dbt-bigquery-Adapter unterstützt die OAuth-basierte und die dienstkontobasierte Authentifizierung.

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

Wenn Sie sich mit einem Dienstkonto beim dbt-bigquery-Adapter authentifizieren möchten, bitten Sie Ihren Administrator, dem zu verwendenden Dienstkonto die folgenden Rollen zuzuweisen:

Wenn Sie sich mit einem Dienstkonto authentifizieren, muss dem zu verwendenden Dienstkonto auch die Rolle Dienstkontonutzer (roles/iam.serviceAccountUser) zugewiesen sein.

Python-Ausführungsumgebung

Der dbt-bigquery-Adapter verwendet den Notebook-Ausführungsdienst von Colab Enterprise, 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 dasGoogle Cloud Projekt auswählen, in dem das Notebook ausgeführt werden soll. Im Notebook wird der Python-Code aus dem Modell ausgeführt, der von der BigQuery DataFrames-Bibliothek in BigQuery SQL umgewandelt wird. Die BigQuery-SQL-Abfrage 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 vorhanden ist und der Nutzer, der den Code ausführt, die Berechtigungen zum Erstellen der Vorlage hat, erstellt der dbt-bigquery-Adapter automatisch die Standard-Notebook-Vorlage und verwendet sie. Sie können auch mit einer dbt-Konfiguration eine andere Notebook-Vorlage angeben.

Für die Ausführung von Notebooks ist ein Cloud Storage-Bucket zum Speichern des Codes und der Protokolle erforderlich. Der dbt-bigquery-Adapter kopiert die Protokolle jedoch in die dbt-Protokolle, 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 mit dem Makro dbt.source() aus einer vorhandenen BigQuery-Tabelle laden
  • Mit dem Makro dbt.ref() Daten aus anderen dbt-Modellen laden, um Abhängigkeiten aufzubauen und gerichtete azyklische Graphen (DAGs) mit Python-Modellen zu erstellen.
  • Python-Pakete von PyPi angeben und verwenden, die für die Ausführung von Python-Code verwendet werden können Weitere Informationen finden Sie unter Konfigurationen.
  • Benutzerdefinierte Notebook-Laufzeitvorlage für 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. Für die Verarbeitung von Änderungen wird häufig eine Zusammenführungsstrategie verwendet.

dbt für die Verwendung von BigQuery DataFrames einrichten

Wenn Sie dbt Core verwenden, müssen Sie eine profiles.yml-Datei für die Verwendung mit BigQuery DataFrames verwenden. Im folgenden Beispiel wird die oauth-Methode 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 direkt in der dbt Cloud-Benutzeroberfläche eine Verbindung zu Ihrer Datenplattform herstellen. In diesem Fall ist keine profiles.yml-Datei erforderlich. Weitere Informationen finden Sie unter profiles.yml.

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

# 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 Modellkonfigurationen und dbt_project.yml.

Konfigurationen

Sie können die folgenden Konfigurationen mit der dbt.config-Methode 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 keine Angabe erfolgt, 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-Python-Modelle

In den folgenden Abschnitten finden Sie Beispielszenarien und Python-Modelle.

Daten aus einer BigQuery-Tabelle laden

Wenn Sie Daten aus einer vorhandenen BigQuery-Tabelle als Quelle in Ihrem Python-Modell verwenden möchten, müssen Sie diese Quelle zuerst in einer YAML-Datei definieren. 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

Verweis auf ein anderes Modell

Sie können Modelle erstellen, die von der Ausgabe anderer dbt-Modelle abhängen, wie im folgenden Beispiel gezeigt. Das 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

Paketabhängigkeit angeben

Wenn für Ihr Python-Modell bestimmte Bibliotheken von Drittanbietern wie MLflow oder Boto3 erforderlich sind, 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

Nicht standardmäßige Vorlage angeben

Wenn Sie die Ausführungsumgebung besser steuern oder vorkonfigurierte Einstellungen verwenden möchten, können Sie für Ihr BigQuery DataFrames-Modell eine andere als die Standard-Notebook-Vorlage 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. Dies wird als Materialisierung bezeichnet.

Bei der Standardmaterialisierung von Tabellen erstellt oder ersetzt dbt jedes Mal, wenn das Modell ausgeführt wird, eine Tabelle in Ihrem Warehouse mit der Ausgabe des Modells. Dies geschieht standardmäßig oder durch explizites Festlegen der materialized='table'-Eigenschaft, 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. Das ist bei großen Datenmengen nützlich, da es ineffizient sein kann, eine Tabelle jedes Mal vollständig neu zu erstellen. Die Zusammenführungsstrategie ist eine gängige Methode, um diese Aktualisierungen zu verarbeiten.

Bei diesem Ansatz werden Änderungen intelligent integriert:

  • Vorhandene Zeilen aktualisieren, die sich geändert haben.
  • Neue Zeilen hinzufügen
  • Optional, je nach Konfiguration: Löschen von Zeilen, 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 ermitteln 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-Protokollen beobachten.

Außerdem können Sie den Code und die Protokolle (einschließlich vorheriger Ausführungen) auf der Seite Colab Enterprise-Ausführungen aufrufen.

Zu Colab Enterprise-Ausführungen

Abrechnung

Bei Verwendung des dbt-bigquery-Adapters mit BigQuery DataFrames fallen Google Cloud folgende Gebühren an:

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

  • BigQuery-Abfrageausführung: Im Notebook wandelt BigQuery DataFrames Python in SQL um und führt den Code in BigQuery aus. Die Abrechnung erfolgt gemäß Ihrer Projektkonfiguration und Ihrer Abfrage, wie in den BigQuery DataFrames-Preisen beschrieben.

Mit dem folgenden Abrechnungslabel in der BigQuery-Abrechnungskonsole können Sie den Abrechnungsbericht für die Notebookausführung und die vom dbt-bigquery-Adapter ausgelösten BigQuery-Ausführungen herausfiltern:

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

Nächste Schritte