ייבוא מטא-נתונים מ-dbt Core

במאמר הזה מוסבר איך לייבא מטא-נתונים מ-dbt Core ומ-MetricFlow אל Knowledge Catalog (לשעבר Dataplex Universal Catalog) באמצעות הפקודה gcloud.

המטא-נתונים הבאים נאספים על ידי השילוב של dbt:

  • מטא-נתונים טכניים: כוללים משאבים מרכזיים (מקורות, נתונים ראשוניים, מודלים) והמאפיינים הטכניים שלהם (שמות עמודות, סוגי נתונים, מספר שורות).
  • מטא-נתונים עסקיים וסמנטיים: מבוסס על dbt MetricFlow, כולל הגדרות עסקיות ולוגיקה כמו מודלים סמנטיים, מדדים ושאילתות שמורות.
  • מטא-נתונים תפעוליים ומטא-נתונים של איכות הנתונים: כולל מטא-נתונים של ביצוע כמו תזמון, סטטוס הצלחה או כשל, רעננות הנתונים, בדיקה ותוצאות הבדיקה.
  • מטא-נתונים של שושלת וקשרים: כולל גרפים של טרנספורמציות (DAG) ותלות בין משאבי dbt, שושלת פיזית שעוקבת אחרי בלוקים של טרנספורמציות פיזיות ומקשרת ביניהם, מפתחות של צירופים וצירופים דינמיים, וקשרים של הורה-צאצא.
  • מטא-נתונים של צריכה: כולל מטא-נתונים שמתועדים בחשיפות שממפים את אופן השימוש בנתונים מחוץ ל-dbt.

כדי לייבא מטא-נתונים מ-dbt Core ומ-MetricFlow, צריך לבצע את המשימות הבאות:

  1. נותנים את התפקידים וההרשאות הנדרשים.
  2. הפעלת Knowledge Catalog API
  3. עמידה בדרישות המוקדמות של dbt.
  4. יוצרים את קבוצת הכניסה של היעד אם היא עדיין לא קיימת.
  5. הסבר על התפקידים ב-Cloud Storage

תפקידים והרשאות של IAM

כדי ליצור ולנהל עבודת מחבר של Knowledge Catalog, אתם צריכים תפקידים בניהול הזהויות והרשאות הגישה (IAM) שמעניקים הרשאות ל-Knowledge Catalog ול-Cloud Storage.

כדי לקבל את ההרשאות שנדרשות להגדרת מחבר dbt, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

בנוסף, צריך להקצות לסוכן השירות של Knowledge Catalog‏ (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) את התפקיד צפייה באובייקט אחסון‏ (roles/storage.objectViewer) בקטגוריה של Cloud Storage שמשמשת כשלב ביניים לפלט (--storage-uri), כדי שמשימת הייבוא תוכל לקרוא את קובץ המטא-נתונים שמוכן לייבוא.

מידע נוסף על מתן תפקידים זמין במאמר ניהול הגישה.

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

מפעילים את Knowledge Catalog API.

להפעלת ה-API

דרישות מוקדמות ל-dbt

כדי לייבא את כל המטא-נתונים של dbt, מומלץ ליצור את כל ארבעת קובצי הארטיפקט של dbt בפורמט JSON. רק manifest.json הוא שדה חובה. שאר השדות משפרים את הייבוא, וההמרה מתבצעת בצורה חלקה גם בלעדיהם:

  • ‫manifest.json (חובה): מבנה הפרויקט הגרעיני וגרף הביצוע. הוא כולל גם את המודלים הסמנטיים, המדדים והשאילתות השמורות של MetricFlow.
  • ‫catalog.json: שמות העמודות וסוגי הנתונים. בלי catalog.json, היבט הסכימה מיובא עם עמודות ללא סוג.
  • ‫run_results.json: תוצאות הבדיקה ומטא-נתונים של ההרצה.
  • ‫sources.json: רעננות המקור.

כדי ליצור את כל קובצי ה-JSON של ארטיפקטים של מטא-נתונים של dbt, אפשר להריץ את פקודות dbt הבאות לפי הסדר הזה:

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

הסבר על תפקידים ב-Cloud Storage

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

  • קלט (ארטיפקטים של מקור dbt): המקום שבו נמצאים קובצי ה-JSON של dbt שנוצרו. זה יכול להיות נתיב של ספרייה מקומית במחשב או ב-CI runner (כמו ./target/ או .) או קידומת של URI של קטגוריה של Cloud Storage (כמו gs://my-dbt-artifacts-bucket/target/). את הנתיב הזה מציינים באמצעות הדגל --artifacts-path. הפקודה gcloud קוראת את קובצי הקלט האלה במהלך הכנת העבודה. אם משתמשים ב-Cloud Storage, למשתמש שמפעיל את הפקודה gcloud צריכה להיות גישת קריאה (roles/storage.objectViewer או roles/storage.objectAdmin). לסוכן השירות של Knowledge Catalog לא צריכה להיות גישה לדלי של ארטיפקטים של קלט.
  • פלט (קטגוריית אחסון זמני לייבוא לקטלוג הידע): קידומת של URI של קטגוריית Cloud Storage (למשל gs://my-staging-bucket/dbt-imports/) שאליה הפקודה gcloud מעלה את קובץ הייבוא של המטא-נתונים שעברו טרנספורמציה (dbt_metadata.jsonl), ושממנה משימת הייבוא לקטלוג הידע קוראת במהלך ההטמעה. אתם מספקים את ה-URI הזה באמצעות הדגל --storage-uri. למבצע הקריאה של הפקודה gcloud צריכה להיות הרשאת כתיבה (roles/storage.objectCreator או roles/storage.objectAdmin) כדי להעלות את הקובץ, ולסוכן השירות של קטלוג הידע צריכה להיות הרשאת קריאה (roles/storage.objectViewer) כדי לייבא אותו.

הגדרת קישוריות ל-dbt

כדי ליצור קישוריות ל-dbt, קודם צריך להריץ את פקודות dbt המתאימות כדי ליצור את פריטי המטא-נתונים. אחרי שמאחסנים את קובצי ה-JSON ומוודאים שאפשר לגשת אליהם, אפשר להשתמש בפקודה gcloud alpha dataplex dbt metadata-jobs create כדי:

  1. קריאת ארטיפקטים של קלט: קריאת ארטיפקטים של JSON שנוצרו על ידי dbt Core ו-MetricFlow ממיקום הקלט (ספרייה מקומית או URI של Cloud Storage שצוינו ב---artifacts-path).
  2. המרת מטא-נתונים: המרת התוכן לפורמט ייבוא המטא-נתונים של Knowledge Catalog (dbt_metadata.jsonl).
  3. העלאה לאזור ההמתנה: מעלים את קובץ ייבוא המטא-נתונים שעבר המרה למיקום של אזור ההמתנה לפלט ב-Cloud Storage שצוין ב---storage-uri.
  4. הפעלת עבודת ייבוא: הפעלת עבודת ייבוא של מטא-נתונים של Knowledge Catalog, שמורה לסוכן של שירות Knowledge Catalog לקרוא את המטא-נתונים שהועברו ל---storage-uri ולהוסיף אותם למשאבים של Knowledge Catalog.

כדי ליצור משימת מטא-נתונים של dbt:

  1. מוודאים שקובצי הארטיפקט של המטא-נתונים של dbt מאוחסנים באופן מקומי או בקטגוריה של Cloud Storage כקלט.
  2. צריך לוודא שהגדרתם קטגוריה של Cloud Storage לביניים עם ההרשאות המתאימות גם למתקשר וגם לסוכן של שירות Knowledge Catalog.

  3. מריצים את הפקודה gcloud מ-Cloud Shell, מטרמינל מקומי או מכלי אוטומטי של תהליך עבודה:

    gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/

    דגלים נדרשים

    • ‫--storage-uri=STORAGE_URI: (פלט/הכנה) קידומת של URI של Cloud Storage ‏ (gs://bucket/path/) שאליה מועלה קובץ ה-JSONL שעבר טרנספורמציה, ושממנה עבודת הייבוא קוראת במהלך הטמעת הנתונים. למבצע הקריאה צריכה להיות הרשאת כתיבה (roles/storage.objectCreator או roles/storage.objectAdmin), ולאגנט השירות של Knowledge Catalog צריכה להיות הרשאת קריאה (roles/storage.objectViewer).

    דגלים אופציונליים

    • ‫--artifacts-path=ARTIFACTS_PATH: (קלט) הנתיב לארטיפקטים של dbt במקור. הנתיב יכול להיות נתיב של ספרייה מקומית (למשל . או ./target) או קידומת URI של Cloud Storage (למשל gs://my-bucket/dbt-artifacts/). יכול להיות שהנתיב מצביע על ספריית הבסיס של פרויקט dbt (תת-הספרייה target/ מזוהה באופן אוטומטי) או ישירות על הספרייה שמכילה את manifest.json. ברירת המחדל היא .. אם מציינים URI של Cloud Storage, למבצע הקריאה צריכה להיות הרשאת גישה לקריאה (roles/storage.objectViewer או roles/storage.objectAdmin) לקטגוריית הקלט.
    • ‫--async: חזרה מיידית, בלי המתנה שהפעולה תסתיים.
    • ‫--entry-group=ENTRY_GROUP: המזהה הקצר של קבוצת הרשומות שמקבלת את הרשומות של dbt. היא חייבת כבר להיות קיימת בפרויקט ובמיקום (ברירת המחדל היא dbt-metadata-ingestion).
    • ‫--aspects-only: עדכון רק של המטא-נתונים שנצפו בהרצת ה-dbt הזו, בלי לגעת בשאר הרשומות בקבוצת הרשומות. לא נוצרת רשומה, לא נמחקת רשומה ולא מתבצעת העברה של רשומה לאובייקט אב אחר, והיבט שפריט ה-dbt שלו לא היה קיים בהרצה הזו שומר על הערך שניתן לו בהרצה קודמת. השתמשו באפשרות הזו להעלאה שגרתית וחוזרת. איך מפעילים מחדש את ההעברה
    • ‫--validate-only: בנייה והעלאה של קובץ ה-JSON ואימות של משימת המטא-נתונים, אבל לא מתבצעת בפועל הטמעה.

  4. מוודאים שקיבלתם סטטוס נוצר.

  5. אחרי שיוצרים את העבודה, Knowledge Catalog מתזמן את ההרצה הראשונה בהתאם להגדרה, או שאפשר להתחיל אותה באופן ידני.

הפעלה מחדש של ההעברה

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

הפעלת הטמעה מלאה (השמטת --aspects-only) כשקבוצת הרשומות משתנה:

  • הטמעה ראשונה בקבוצת רשומות.
  • משאב dbt מתווסף, משנה את השם או נמחק.
  • השם המוצג, התיאור או התוויות של רשומה משתנים.
  • היררכיית הרשומות משתנה.

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

הפעלת --aspects-only לרענון שגרתי:

  • אחרי כל פקודת dbt שצינור עיבוד הנתונים מריץ: dbt build,‏ dbt test,‏ dbt source freshness או בנייה מחדש מצומצמת של --select.
  • עמודה נוספת, מוסרת, מוגדרת מחדש או מתוארת מחדש.
  • ה-SQL של המודל השתנה וההרצה כתבה גם את catalog.json.
  • תוצאות חדשות של בדיקות או עדכניות של המקור.

--aspects-only יכול להוסיף ולרענן מטא-נתונים, אבל לא להסיר אותם.

חיפוש והצגה של מטא-נתונים של dbt

  1. נכנסים לדף Search בKnowledge Catalog במסוף Google Cloud .

    מעבר אל חיפוש

  2. בחלונית Filters, אפשר לסנן נכסי dbt באמצעות הקטעים Project,‏ System ו-Type aliases. בקטע מערכת, בוחרים באפשרות הקשר מיובא. כשבוחרים במסנן הזה, נפתח קטע המשנה Managed Connectors (מחברים מנוהלים). בוחרים באפשרות dbt כדי לסנן את כל המטא-נתונים של dbt.

  3. אפשר להשתמש בשדה החיפוש כדי להריץ שאילתות חיפוש. אפשר לבצע חיפוש של מילות מפתח או חיפוש בשפה טבעית. לדוגמה, כדי לראות את כל הנכסים של dbt באמצעות חיפוש מילות מפתח, מזינים system=DBT.

    למידע נוסף על חיפוש משאבים, אפשר לעיין במאמר חיפוש משאבים ב-Knowledge Catalog. מידע נוסף על הביטויים שאפשר להשתמש בהם בשדה החיפוש זמין במאמר תחביר החיפוש ב-Knowledge Catalog.

  4. אפשר גם להשתמש ב-API‏ LookupContext כדי לאחזר הקשר של LLM למשאבי dbt ספציפיים.

מגבלות

  • תמיכה בגרסאות עדכניות של dbt Core v1 (התבצע אימות מול גרסאות 1.11 ו-1.12). אין תמיכה ב-dbt Core v2 וב-dbt Fusion.
  • אין תמיכה במודלים של dbt שמשתמשים בניהול גרסאות של מודלים.
  • אין תמיכה ב-dbt Cloud.
  • סכימות גדולות מאוד או כאלה עם קינון עמוק נחתכות: גודל של היבט יחיד לא יכול לחרוג מהגודל המקסימלי לכל היבט, ולכן יכול להיות ששדות בסוף של סכימות עם קינון עמוק יאבדו.
  • --aspects-only יכול להוסיף ולרענן מטא-נתונים, אבל לא להסיר אותם. כדי למחוק משאב dbt, צריך להריץ את כל התהליך.
  • אין תמיכה בקישורי כניסה.
  • השילוב הזה תומך רק באירועי שושלת נתונים של dbt במשאבי BigQuery ב-API ובגרף של Data Lineage. רשומות dbt (מקור, seeds, מודלים) למקורות חיצוניים של צד שלישי לא נכללות בשושלת הנתונים.

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