Usa BigQuery DataFrames en dbt

dbt (data build tool) es un framework de línea de comandos de código abierto diseñado para la transformación de datos en almacenes de datos modernos. dbt facilita las transformaciones de datos modulares mediante la creación de modelos reutilizables basados en SQL y Python. La herramienta organiza la ejecución de estas transformaciones en el almacén de datos de destino y se enfoca en el paso de transformación de la canalización de ELT. Para obtener más información, consulta la documentación de dbt.

En dbt, un modelo de Python es una transformación de datos que se define y ejecuta con código de Python dentro de tu proyecto de dbt. En lugar de escribir SQL para la lógica de transformación, escribes secuencias de comandos de Python que dbt organiza para que se ejecuten en el entorno del almacén de datos. Un modelo de Python te permite realizar transformaciones de datos que podrían ser complejas o ineficientes para expresar en SQL. Esto aprovecha las capacidades de Python y, al mismo tiempo, se beneficia de la estructura del proyecto, la organización, la administración de dependencias, las pruebas y las funciones de documentación de dbt. Para obtener más información, consulta Modelos de Python.

El adaptador dbt-bigqueryadmite la ejecución de código de Python definido en BigQuery DataFrames. Esta función está disponible en dbt Cloud y dbt Core. También puedes obtener esta función clonando la versión más reciente del adaptador dbt-bigquery.

Antes de comenzar

Para usar el adaptador dbt-bigquery, habilita las siguientes APIs en tu proyecto:

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

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

Habilitar las API

Roles obligatorios

El adaptador dbt-bigquery admite la autenticación basada en OAuth y en cuentas de servicio. En las siguientes secciones, se describen los roles necesarios según la forma en que planeas autenticarte.

OAuth

Si planeas autenticarte en el adaptador dbt-bigquery con OAuth, pídele a tu administrador que te otorgue los siguientes roles:

Cuenta de servicio

Si planeas autenticarte en el adaptador dbt-bigquery con una cuenta de servicio en tu proyecto, pídele a tu administrador que otorgue los siguientes roles a la cuenta de servicio que planeas usar:

Si te autenticas con una cuenta de servicio, también asegúrate de tener el rol de usuario de cuenta de servicio (roles/iam.serviceAccountUser) otorgado para la cuenta de servicio que planeas usar.

Uso de identidad temporal como cuenta de servicio

Si planeas autenticarte en el adaptador dbt-bigquery con OAuth, pero quieres que el procesamiento de datos y la ejecución de notebooks se realicen con la identidad de una cuenta de servicio en el mismo proyecto en el que se ejecutan los trabajos, pídele a tu administrador que te otorgue los siguientes roles:

La cuenta de servicio suplantada también debe tener todos los roles necesarios para la autenticación.

Cuentas de servicio entre proyectos

Si planeas autenticarte en el adaptador dbt-bigquery con una cuenta de servicio en un proyecto diferente, el proyecto de credenciales, desde donde se ejecutan los trabajos, el proyecto de ejecución, pídele a tu administrador que haga lo siguiente:

  1. Inhabilita la restricción constraints/iam.disableCrossProjectServiceAccountUsage en el proyecto de credenciales.

  2. Además de todos los roles necesarios para la autenticación de la cuenta de servicio, otorga los siguientes roles a la cuenta de servicio en el proyecto de credenciales:

Si planeas autenticarte en el adaptador dbt-bigquery con OAuth, pero quieres que el procesamiento de datos y la ejecución de notebooks se realicen con la identidad de una cuenta de servicio en un proyecto diferente desde el que se ejecutan los trabajos, pídele a tu administrador que haga lo siguiente:

VPC compartida

Si usas Colab Enterprise en un entorno de VPC compartida, pídele a tu administrador que otorgue los siguientes roles y permisos:

  • compute.subnetworks.use permiso: Otorga este permiso a la cuenta de servicio que usa el entorno de ejecución de Colab Enterprise en el proyecto host o en subredes específicas. Este permiso se incluye en el rol de usuario de la red de Compute (roles/compute.networkUser).

  • compute.subnetworks.get permiso: Otorga este permiso a la cuenta de servicio que usa el entorno de ejecución de Colab Enterprise en el proyecto host o en subredes específicas. Este permiso se incluye en el rol de visualizador de la red de Compute (roles/compute.networkViewer).

  • Rol de usuario de la red de Compute (roles/compute.networkUser): Otorga este rol al agente de servicio de Gemini Enterprise Agent Platform , service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, en el proyecto host de la VPC compartida.

  • Rol de usuario de la red de Compute (roles/compute.networkUser): Si se usa la función de trabajo de ejecución de notebooks, otorga este rol al agente de servicio de Colab Enterprise, service-PROJECT_NUMBER@gcp-sa-vertex-nb.iam.gserviceaccount.com, en el proyecto host de la VPC compartida.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Entorno de ejecución de Python

El adaptador dbt-bigquery utiliza el servicio de ejecutor de notebooks de Colab Enterprise para ejecutar el código de Python de BigQuery DataFrames. El adaptador dbt-bigquery crea y ejecuta automáticamente un notebook de Colab Enterprise para cada modelo de Python. Puedes elegir el Google Cloud proyecto en el que se ejecutará el notebook. El notebook ejecuta el código de Python del modelo, que la biblioteca de BigQuery DataFrames convierte en SQL de BigQuery. Luego, el SQL de BigQuery se ejecuta en el proyecto configurado. En el siguiente diagrama, se presenta el flujo de control:

Entorno de ejecución de Python de BigQuery DataFrames para un notebook

Si aún no hay una plantilla de notebook disponible en el proyecto y el usuario que ejecuta el código tiene los permisos para crear la plantilla, el adaptador dbt-bigquery crea y usa automáticamente la plantilla de notebook predeterminada. También puedes especificar una plantilla de notebook diferente con una configuración de dbt.

La ejecución de notebooks requiere un bucket de Cloud Storage de etapa de pruebas para almacenar el código y los registros. Sin embargo, el adaptador dbt-bigquery copia los registros en los registros de dbt, por lo que no tienes que buscar en el bucket.

Funciones admitidas

El adaptador dbt-bigquery admite las siguientes capacidades para los modelos de Python de dbt que ejecutan BigQuery DataFrames:

  • Carga de datos desde una tabla de BigQuery existente con la macro dbt.source()
  • Carga de datos desde otros modelos de dbt con la macro dbt.ref() para compilar dependencias y crear grafos acíclicos dirigidos (DAGs) con modelos de Python
  • Especificación y uso de paquetes de Python de PyPi que se pueden usar con la ejecución de código de Python (para obtener más información, consulta Parámetros de configuración)
  • Especificación de una plantilla de entorno de ejecución de notebook personalizada para tus modelos de BigQuery DataFrames

El adaptador dbt-bigquery admite las siguientes estrategias de materialización:

  • Materialización de tablas, en la que los datos se vuelven a compilar como una tabla en cada ejecución
  • Materialización incremental con una estrategia de combinación, en la que se agregan datos nuevos o actualizados a una tabla existente, a menudo con una estrategia de combinación para controlar los cambios

Configura dbt para usar BigQuery DataFrames

Si usas dbt Core, debes usar un archivo profiles.yml para usarlo con BigQuery DataFrames. En el siguiente ejemplo, se usa el método oauth:

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

Si usas dbt Cloud, puedes conectarte a tu plataforma de datos directamente en la interfaz de dbt Cloud. En este caso, no necesitas un archivo profiles.yml. Para obtener más información, consulta Acerca de profiles.yml.

Este es un ejemplo de una configuración a nivel de proyecto para el archivo 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

Algunos parámetros también se pueden configurar con el método dbt.config dentro de tu código de Python. Si estos parámetros de configuración entran en conflicto con tu archivo dbt_project.yml, las configuraciones con dbt.config tendrán prioridad.

Para obtener más información, consulta Parámetros de configuración del modelo y dbt_project.yml.

Parámetros de configuración

Puedes configurar los siguientes parámetros de configuración con el método dbt.config en tu modelo de Python. Estos parámetros de configuración anulan la configuración a nivel de proyecto.

Configuración Obligatorio Uso
submission_method Sí submission_method=bigframes
notebook_template_id No Si no se especifica, se crea y se usa una plantilla predeterminada.
packages No Especifica la lista adicional de paquetes de Python, si es necesario.
timeout No Opcional: Extiende el tiempo de espera de ejecución del trabajo.

Ejemplo de modelos de Python

En las siguientes secciones, se presentan situaciones de ejemplo y modelos de Python.

Carga datos desde una tabla de BigQuery

Para usar datos de una tabla de BigQuery existente como fuente en tu modelo de Python, primero debes definir esta fuente en un archivo YAML. En el siguiente ejemplo, se define en un archivo source.yml.

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

Luego, compila tu modelo de Python, que puede usar las fuentes de datos configuradas en este archivo YAML:

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

Haz referencia a otro modelo

Puedes compilar modelos que dependan del resultado de otros modelos de dbt, como se muestra en el siguiente ejemplo. Esto es útil para crear canalizaciones de datos modulares.

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

Especifica una dependencia de paquete

Si tu modelo de Python requiere bibliotecas específicas de terceros, como MLflow o Boto3, puedes declarar el paquete en la configuración del modelo, como se muestra en el siguiente ejemplo. Estos paquetes se instalan en el entorno de ejecución.

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

Especifica una plantilla no predeterminada

Para tener más control sobre el entorno de ejecución o usar parámetros de configuración preconfigurados, puedes especificar una plantilla de notebook no predeterminada para tu modelo de BigQuery DataFrames, como se muestra en el siguiente ejemplo.

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)

Materializa las tablas

Cuando dbt ejecuta tus modelos de Python, debe saber cómo guardar los resultados en tu almacén de datos. Esto se denomina materialización.

Para la materialización de tablas estándar, dbt crea o reemplaza por completo una tabla en tu almacén con el resultado de tu modelo cada vez que se ejecuta. Esto se hace de forma predeterminada o configurando explícitamente la propiedad materialized='table', como se muestra en el siguiente ejemplo.

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)

La materialización incremental con una estrategia de combinación permite que dbt actualice tu tabla solo con filas nuevas o modificadas. Esto es útil para conjuntos de datos grandes, ya que volver a compilar una tabla por completo cada vez puede ser ineficiente. La estrategia de combinación es una forma común de controlar estas actualizaciones.

Este enfoque integra los cambios de forma inteligente de la siguiente manera:

  • Actualiza las filas existentes que cambiaron.
  • Agrega filas nuevas.
  • Opcional, según la configuración: Borra las filas que ya no están presentes en la fuente.

Para usar la estrategia de combinación, debes especificar una propiedad unique_key que dbt pueda usar para identificar las filas coincidentes entre el resultado de tu modelo y la tabla existente, como se muestra en el siguiente ejemplo.

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)

Soluciona problemas

Puedes observar la ejecución de Python en los registros de dbt.

Además, puedes ver el código y los registros (incluidas las ejecuciones anteriores) en la página Ejecuciones de Colab Enterprise.

Ir a Ejecuciones de Colab Enterprise

Facturación

Cuando usas el adaptador dbt-bigquery con BigQuery DataFrames, se generan Google Cloud cargos por lo siguiente:

  • Ejecución de notebooks: Se te cobra por la ejecución del entorno de ejecución del notebook. Para obtener más información, consulta Precios del entorno de ejecución de notebooks.

  • Ejecución de consultas de BigQuery: En el notebook, BigQuery DataFrames convierte Python en SQL y ejecuta el código en BigQuery. Se te cobra según la configuración de tu proyecto y tu consulta, como se describe en los precios de BigQuery DataFrames DataFrames.

Puedes usar la siguiente etiqueta de facturación en la consola de facturación de BigQuery para filtrar el informe de facturación de la ejecución de notebooks y de las ejecuciones de BigQuery que activa el adaptador dbt-bigquery:

  • Etiqueta de ejecución de BigQuery: bigframes-dbt-api

¿Qué sigue?