שימוש ב-BigQuery DataFrames ב-dbt

כדי לבצע טרנספורמציות מודולריות של נתונים ב-Python ישירות ב-BigQuery, משלבים את BigQuery DataFrames עם כלי הקוד הפתוח לבניית נתונים (dbt). באמצעות המתאם של dbt-bigquery להרצת מודלים של Python, אפשר לבצע טרנספורמציות מורכבות של חילוץ, טעינה וטרנספורמציה (ELT) שלא יעיל לבטא ב-SQL, ועדיין ליהנות מהתכונות החזקות של dbt לתזמור, לניהול תלויות ולבדיקה.

סקירה כללית על dbt

‫dbt הוא מסגרת קוד פתוח של שורת פקודה, שמיועדת לטרנספורמציה של נתונים במחסני נתונים מודרניים. dbt מאפשר טרנספורמציות מודולריות של נתונים באמצעות יצירת מודלים מבוססי-SQL ו-Python שניתן לעשות בהם שימוש חוזר. הכלי מתזמר את ביצוע הטרנספורמציות האלה במחסן הנתונים של היעד, ומתמקד בשלב הטרנספורמציה של צינור עיבוד הנתונים של ה-ELT. מידע נוסף זמין במאמרי העזרה של dbt.

ב-dbt, מודל Python הוא טרנספורמציית נתונים שמוגדרת ומופעלת באמצעות קוד Python בפרויקט dbt. במקום לכתוב SQL ללוגיקה של הטרנספורמציה, כותבים סקריפטים של Python, ואז dbt מתזמר אותם להרצה בסביבה של מחסן הנתונים. מודל Python מאפשר לבצע טרנספורמציות של נתונים שיכול להיות שיהיה מורכב או לא יעיל לבטא ב-SQL. כך אפשר לנצל את היכולות של Python ועדיין ליהנות מהתכונות של dbt, כמו מבנה הפרויקט, התזמור, ניהול יחסי התלות, הבדיקות והתיעוד. מידע נוסף זמין במאמר מודלים של Python.

המתאם של dbt-bigquery תומך בהרצה של קוד Python שמוגדר ב-BigQuery DataFrames. התכונה הזו זמינה ב-dbt Cloud וב-dbt Core.

לפני שמתחילים

כדי להשתמש במתאם dbt-bigquery, צריך להפעיל את ממשקי ה-API הבאים בפרויקט:

  • ‫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)

התפקידים שנדרשים כדי להפעיל ממשקי API

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, אתם יכולים לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים?

הפעלת ממשקי ה-API

התפקידים הנדרשים

המתאם של dbt-bigquery תומך באימות שמבוסס על OAuth ובאימות שמבוסס על חשבון שירות. בקטעים הבאים מתוארים התפקידים הנדרשים בהתאם לאופן שבו אתם מתכננים לבצע אימות.

OAuth

אם אתם מתכננים לבצע אימות למתאם dbt-bigquery באמצעות OAuth, בקשו מהאדמין להקצות לכם את התפקידים הבאים:

חשבון שירות

אם אתם מתכננים לבצע אימות למתאם dbt-bigquery באמצעות חשבון שירות בפרויקט, בקשו מהאדמין להקצות את התפקידים הבאים לחשבון השירות שבו אתם מתכננים להשתמש:

אם אתם מבצעים אימות באמצעות חשבון שירות, ודאו שקיבלתם את התפקיד "משתמש בחשבון שירות" (roles/iam.serviceAccountUser) בחשבון השירות שבו אתם מתכוונים להשתמש.

התחזות לחשבון שירות

אם אתם מתכננים לבצע אימות למתאם dbt-bigquery באמצעות OAuth, אבל רוצים שעיבוד הנתונים והרצת ה-notebook יתבצעו באמצעות הזהות של חשבון שירות באותו פרויקט שבו המשימות פועלות, בקשו מהאדמין להקצות לכם את התפקידים הבאים:

לחשבון השירות שאליו מתחזים צריכים להיות גם כל התפקידים שנדרשים לאימות.

חשבונות שירות בפרויקטים שונים

אם אתם מתכננים לבצע אימות למתאם dbt-bigquery באמצעות חשבון שירות בפרויקט אחר, פרויקט פרטי הכניסה, שממנו מופעלות המשימות, פרויקט ההפעלה, בקשו מהאדמין לבצע את הפעולות הבאות:

  1. משביתים את האילוץ constraints/iam.disableCrossProjectServiceAccountUsage בפרויקט של פרטי הכניסה.

  2. בנוסף לכל התפקידים שנדרשים לאימות של חשבון השירות, מקצים לחשבון השירות את התפקידים הבאים בפרויקט של פרטי הכניסה:

אם אתם מתכננים לבצע אימות למתאם dbt-bigquery באמצעות OAuth, אבל רוצים שעיבוד הנתונים והרצת ה-notebook יתרחשו בזהות של חשבון שירות בפרויקט אחר מזה שבו המשימות מופעלות, בקשו מהאדמין לבצע את הפעולות הבאות:

VPC משותף

אם אתם משתמשים ב-Colab Enterprise בסביבת VPC משותף, בקשו מהאדמין להקצות את התפקידים וההרשאות הבאים:

  • הרשאת compute.subnetworks.use: נותנים את ההרשאה הזו לחשבון השירות שמשמש את סביבת זמן הריצה של Colab Enterprise בפרויקט המארח או ברשתות משנה ספציפיות. ההרשאה הזו כלולה בתפקיד משתמש ברשת Compute (roles/compute.networkUser).

  • הרשאת compute.subnetworks.get: צריך לתת את ההרשאה הזו לחשבון השירות שמשמש את סביבת זמן הריצה של Colab Enterprise בפרויקט המארח או ברשתות משנה ספציפיות. ההרשאה הזו כלולה בתפקיד "צפייה ברשת" ב-Compute (roles/compute.networkViewer).

  • תפקיד משתמש ברשת Compute (roles/compute.networkUser): מקצים את התפקיד הזה לסוכן השירות של פלטפורמת הסוכנים של Gemini Enterprise, ‏service-PROJECT_NUMBER@gcp-sa-aiplatform., בפרויקט המארח של ה-VPC המשותף.

  • התפקיד "משתמש ברשת Compute" (roles/compute.networkUser): אם אתם משתמשים בתכונה "משימת הפעלה של Notebook", אתם צריכים להקצות את התפקיד הזה לסוכן השירות של Colab Enterprise, ‏service-PROJECT_NUMBER@gcp-sa-vertex-nb., בפרויקט המארח של ה-VPC המשותף.

כדי לקרוא הסבר על מתן תפקידים, קראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שתוכלו לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

סביבת הרצה של Python

המתאם של dbt-bigquery משתמש בשירות של Colab Enterprise להרצת קוד ב-notebook כדי להריץ את קוד ה-Python של BigQuery DataFrames. ‫notebook של Colab Enterprise נוצר ומופעל באופן אוטומטי על ידי המתאם של dbt-bigquery לכל מודל Python. אפשר לבחור את הפרויקט ב-Google Cloud שבו רוצים להריץ את ה-notebook. ה-Notebook מריץ את קוד ה-Python מהמודל, שמומר ל-BigQuery SQL על ידי ספריית BigQuery DataFrames. לאחר מכן, ה-SQL של BigQuery מופעל בפרויקט שהוגדר. התרשים הבא מציג את תהליך הבקרה:

סביבת הרצה של BigQuery DataFrames Python ל-Notebook

אם אין תבנית של Notebook בפרויקט, ולמשתמש שמריץ את הקוד יש הרשאות ליצור תבנית, המתאם של dbt-bigquery יוצר באופן אוטומטי את תבנית ברירת המחדל של Notebook ומשתמש בה. אפשר גם לציין תבנית אחרת של Notebook באמצעות הגדרת dbt.

כדי להריץ את ה-notebook, צריך קטגוריה של Cloud Storage להכנת קוד ויומנים לאחסון. עם זאת, המתאם של dbt-bigquery מעתיק את היומנים אל יומני dbt, כך שאין צורך לחפש בקטגוריה.

התכונות הנתמכות

המתאם dbt-bigquery תומך ביכולות הבאות של מודלים של dbt Python שמריצים BigQuery DataFrames:

  • טעינת נתונים מטבלה קיימת ב-BigQuery באמצעות פקודת המאקרו dbt.source().
  • טעינת נתונים ממודלים אחרים של dbt באמצעות פקודת המאקרו dbt.ref() כדי ליצור יחסי תלות וגרפים אציקליים מכוונים (DAG) עם מודלים של Python.
  • הגדרה ושימוש בחבילות Python מ-PyPi שאפשר להשתמש בהן עם הרצת קוד ב-Python. מידע נוסף זמין במאמר הגדרות אישיות.
  • הגדרת תבנית מותאמת אישית של סביבת זמן ריצה של Notebook למודלים של BigQuery DataFrames.

המתאם dbt-bigquery תומך באסטרטגיות המטריאליזציה הבאות:

  • התממשקות של טבלה, שבה הנתונים נבנים מחדש כטבלה בכל הפעלה.
  • התממשקות מצטברת עם אסטרטגיית מיזוג, שבה נתונים חדשים או מעודכנים מתווספים לטבלה קיימת, בדרך כלל באמצעות אסטרטגיית מיזוג כדי לטפל בשינויים.

הגדרת dbt לשימוש ב-BigQuery DataFrames

אם אתם משתמשים ב-dbt Core, אתם צריכים להשתמש בקובץ profiles.yml כדי להשתמש ב-BigQuery DataFrames. בדוגמה הבאה משתמשים ב-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

אם אתם משתמשים ב-dbt Cloud, אתם יכולים להתחבר לפלטפורמת הנתונים ישירות בממשק של dbt Cloud. בתרחיש הזה, אתם לא צריכים קובץ profiles.yml. מידע נוסף זמין במאמר מידע על profiles.yml.

דוגמה להגדרה ברמת הפרויקט של הקובץ 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

אפשר גם להגדיר חלק מהפרמטרים באמצעות השיטה dbt.config בקוד Python. אם ההגדרות האלה מתנגשות עם קובץ dbt_project.yml, ההגדרות עם dbt.config יקבלו עדיפות.

מידע נוסף זמין במאמרים הגדרות מודל ו-dbt_project.yml.

הגדרות אישיות

אתם יכולים להגדיר את ההגדרות הבאות באמצעות השיטה dbt.config במודל Python. ההגדרות האלה מבטלות את ההגדרות ברמת הפרויקט.

הגדרות אישיות חובה Usage
submission_method כן submission_method=bigframes
notebook_template_id לא אם לא מציינים תבנית, המערכת יוצרת תבנית ברירת מחדל ומשתמשת בה.
packages לא אם צריך, מציינים את הרשימה הנוספת של חבילות Python.
timeout לא אופציונלי: מאריכים את הזמן הקצוב לתפוגה של ביצוע המשימה.

דוגמאות למודלים ב-Python

בקטעים הבאים מוצגים תרחישים לדוגמה ומודלים של Python.

טעינת נתונים מטבלה ב-BigQuery

כדי להשתמש בנתונים מטבלה קיימת ב-BigQuery כמקור במודל Python, קודם צריך להגדיר את המקור הזה בקובץ YAML. הדוגמה הבאה מוגדרת בקובץ 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

אחר כך יוצרים את המודל ב-Python, שיכול להשתמש במקורות הנתונים שהוגדרו בקובץ ה-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

הפניה למודל אחר

אתם יכולים ליצור מודלים שתלויים בפלט של מודלים אחרים של dbt, כמו בדוגמה הבאה. האפשרות הזו שימושית ליצירת פייפליינים מודולריים.

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

ציון תלות בחבילה

אם למודל Python נדרשות ספריות ספציפיות של צד שלישי כמו MLflow או Boto3, אפשר להצהיר על החבילה בהגדרות של המודל, כמו בדוגמה הבאה. החבילות האלה מותקנות בסביבת ההפעלה.

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

ציון תבנית שהיא לא ברירת המחדל

כדי לקבל יותר שליטה על סביבת ההפעלה או כדי להשתמש בהגדרות שנקבעו מראש, אתם יכולים לציין תבנית Notebook שאינה ברירת המחדל למודל BigQuery DataFrames, כמו שמוצג בדוגמה הבאה.

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)

התממשקות לטבלאות

כש-dbt מריץ את המודלים של Python, הוא צריך לדעת איך לשמור את התוצאות במחסן הנתונים. התהליך הזה נקרא התממשות.

כדי ליצור טבלה רגילה, dbt יוצר או מחליף לגמרי טבלה במחסן הנתונים עם הפלט של המודל בכל פעם שהוא פועל. הפעולה הזו מתבצעת כברירת מחדל, או על ידי הגדרה מפורשת של המאפיין materialized='table', כמו שמוצג בדוגמה הבאה.

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)

התממשקות מצטברת עם אסטרטגיית מיזוג מאפשרת ל-dbt לעדכן את הטבלה רק עם שורות חדשות או שורות ששונו. האפשרות הזו שימושית לקבוצות נתונים גדולות, כי בנייה מחדש של טבלה בכל פעם יכולה להיות לא יעילה. אסטרטגיית המיזוג היא דרך נפוצה לטפל בעדכונים האלה.

הגישה הזו משלבת שינויים בצורה חכמה על ידי ביצוע הפעולות הבאות:

  • עדכון שורות קיימות שהשתנו.
  • הוספת שורות חדשות.
  • אופציונלי, בהתאם להגדרות: מחיקת שורות שכבר לא קיימות במקור.

כדי להשתמש באסטרטגיית המיזוג, צריך לציין מאפיין unique_key ש-dbt יכול להשתמש בו כדי לזהות את השורות התואמות בין הפלט של המודל לבין הטבלה הקיימת, כמו בדוגמה הבאה.

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)

פתרון בעיות

אפשר לראות את הרצת Python ביומני dbt.

בנוסף, אתם יכולים לראות את הקוד ואת היומנים (כולל הרצות קודמות) בדף Colab Enterprise Executions.

לדף Colab Enterprise Executions

חיוב

כשמשתמשים במתאם dbt-bigquery עם BigQuery DataFrames, החיובים של Google Cloud הם על:

  • הרצת Notebook: אתם מחויבים על הרצת זמן הריצה של ה-Notebook. למידע נוסף, קראו את המאמר תמחור של סביבות זמן ריצה של Notebook.

  • הרצת שאילתות ב-BigQuery: ב-Notebook, ‏BigQuery DataFrames ממיר את Python ל-SQL ומריץ את הקוד ב-BigQuery. החיוב מתבצע בהתאם להגדרות הפרויקט ולשאילתה, כמו שמתואר בתמחור של BigQuery DataFrames.

אתם יכולים להשתמש בתווית החיוב הבאה במסוף החיוב ב-BigQuery כדי לסנן את דוח החיוב של הפעלת ה-Notebook ושל הפעלות BigQuery שמופעלות על ידי מתאם dbt-bigquery:

  • תווית ההפעלה של BigQuery:‏ bigframes-dbt-api

המאמרים הבאים