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

ב-Knowledge Catalog (לשעבר Dataplex Universal Catalog) אתם יכולים לייבא מטא-נתונים תפעוליים, סמנטיים ושל שושלת נתונים מ-dbt Core, מ-dbt Cloud ומ-MetricFlow באמצעות Google Cloud CLI וקובצי פריטי המידע שנוצרו בתהליך הפיתוח (Artifact) של dbt. במקום להשאיר את המטא-נתונים של הטרנספורמציה מבודדים בסביבה של dbt, אתם יכולים לרכז אותם כדי לעזור למהנדסי מערכות מידע, למהנדסי ניתוח נתונים ולמנהלי מדיניות מידע ארגונית לגלות את הנתונים הארגוניים ולנהל אותם.

מטא-נתונים מיובאים ותרחישי שימוש

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

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

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

מגבלות

  • תמיכה ב-dbt Core גרסה 1 (אומת מול גרסאות 1.11 ו-1.12), ב-dbt Core גרסה 2 וב-dbt Fusion.
  • גרסה 586.0.0 ואילך של ה-CLI של gcloud תומכת בשילוב של dbt ו-Knowledge Catalog. כדי להתקין או לעדכן את ה-CLI, קראו את המאמר התקנת Google Cloud CLI.
  • אין חיבור ישיר ל-dbt Cloud. כדי לייבא מטא-נתונים ממשימה ב-dbt Cloud, קודם צריך לקבל את פריטי המידע שנוצרו בתהליך הפיתוח (Artifacts) של המשימה. ייבוא מטא-נתונים מהרצות של dbt Cloud
  • סכימות גדולות מאוד או סכימות עם רמות רבות של הטמעה נחתכות: היבט אחד לא יכול לחרוג ממגבלת הגודל לכל היבט, ולכן סכימות עם רמות רבות של הטמעה עלולות לאבד שדות נגררים.
  • --aspects-only יכול להוסיף ולרענן מטא-נתונים, אבל לא להסיר אותם. כדי למחוק משאב dbt, צריך להפעיל את הפרויקט באופן מלא.
  • השילוב הזה תומך רק באירועי שושלת נתונים של dbt במשאבי BigQuery בData Lineage API ובתרשים. רשומות dbt (מקורות, נתוני seed, מודלים) של מקורות חיצוניים של צד שלישי לא מתועדות בשושלת הנתונים.

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

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

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

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

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

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

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

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

אם אתם מריצים את הייבוא באמצעות חשבון שירות, למשל בצינור עיבוד נתונים אוטומטי של CI/CD, אתם יכולים להקצות את התפקידים האלה לחשבון השירות על ידי הרצת הפקודות הבאות של gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

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

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫USER_EMAIL: כתובת האימייל של חשבון המשתמש שלכם.
  • ‫SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות.
  • ‫STAGING_BUCKET: השם של קטגוריית ה-Staging של הפלט ב-Cloud Storage‏ (--storage-uri).
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .

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

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

מפעילים את Dataplex API.

להפעלת ה-API

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

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

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

במסוף המקומי, ב-Cloud Shell או בסביבת ה-CI/CD האוטומטית שבה מותקן dbt, עוברים לתיקיית השורש של פרויקט dbt ומריצים את פקודות ה-dbt הבאות לפי הסדר, מול פרופיל ויעד יחידים, כדי ליצור את קובצי ה-JSON המלאים של פריטי המידע שנוצרו בתהליך הפיתוח (Artifact) של המטא-נתונים של dbt:

  • ב-dbt Core 2.x וב-dbt Fusion:

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • ב-dbt Core 1.x (שבו dbt parse לא כותב קטלוג):

    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 לא צריך גישה לקטגוריית פריטי המידע של הקלט.
  • פלט (קטגוריית ה-Staging לייבוא של Knowledge Catalog): תחילית של URI של קטגוריה של Cloud Storage (למשל gs://my-staging-bucket/dbt-imports/) שאליה הפקודה gcloud מעלה את קובץ הייבוא של המטא-נתונים שעברו טרנספורמציה (dbt_metadata.jsonl), וממנה משימת הייבוא של Knowledge Catalog קוראת במהלך הטמעת הנתונים. אתם מספקים את ה-URI הזה באמצעות הדגל --storage-uri. לגורם שמפעיל את הפקודה gcloud צריכה להיות גישת כתיבה (roles/storage.objectCreator או roles/storage.objectAdmin) כדי להעלות את הקובץ, ולסוכן השירות של Knowledge Catalog צריכה להיות גישת קריאה (roles/storage.objectViewer) כדי לייבא אותו.

ייבוא מטא-נתונים מהרצות של dbt Cloud

‫Knowledge Catalog לא מתחבר ישירות ל-dbt Cloud. מכיוון שמשימה ב-dbt Cloud יוצרת את אותם קובצי ארטיפקטים כמו dbt Core, אתם יכולים לייבא מטא-נתונים מ-dbt Cloud על ידי אחזור של קובצי הארטיפקטים האלה לספרייה מקומית או לקטגוריית קלט של Cloud Storage, והרצה של הפקודה gcloud.

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

הגדרת המשימה ב-dbt Cloud

במסוף dbt Google Cloud , מגדירים את הגדרות המשימה כדי ליצור את קבוצת פריטי המידע המלאה של המטא-נתונים:

  1. בקטע Execution settings, בוחרים באפשרות Run source freshness. ‫dbt Cloud מריץ את dbt source freshness לפני פקודות המשימה כדי ליצור את sources.json.
  2. בקטע Commands, מוסיפים את dbt build.
  3. מוסיפים פקודה ליצירת catalog.json על סמך מסלול ההפצה:
    • במסלולי ההפצה של dbt Core 2.x ו-dbt Fusion: מוסיפים את dbt parse --write-catalog כפקודת משימה.
    • במסלולי הפצה של dbt Core 1.x: מוסיפים את dbt docs generate --no-compile כפקודת משימה במקום לבחור באפשרות Generate docs on run. תיבת הסימון Generate docs on run מריצה את dbt docs generate בלי --no-compile, מה שמחליף את תוצאות הבדיקה מ-dbt build, כפי שמתואר בדרישות המוקדמות של dbt. שימו לב שאם שלב הפקודה נכשל, גם המשימה נכשלת, אבל שלב תיבת הסימון לא גורם למשימה להיכשל.

אם הפקודה dbt build נכשלת, למשל בגלל שגיאת בדיקה, dbt Cloud מדלג על הפקודות שאחריה ובמהלך ההרצה לא נוצר catalog.json. כדי ליצור תמיד קטלוג, צריך להוסיף את הפקודה catalog לפני dbt build. הקטלוג מתאר את הטבלאות כפי שהיו לפני ה-build.

למידע נוסף, קראו את המאמרים פקודות של משימות ומסלולי הפצה במסמכי התיעוד של dbt.

הורדת פריטי מידע שנוצרו מהמסוף של dbt Google Cloud

כדי להוריד ידנית פריטי מידע מהפעלה שהושלמה במסוףGoogle Cloud של dbt:

  1. במסוף dbt Google Cloud , פותחים את הרצת המשימה שהסתיימה.
  2. עוברים לכרטיסייה Artifacts כדי לראות את קובצי פריטי המידע שנוצרו.
  3. מורידים את manifest.json,‏ catalog.json,‏ run_results.json ו-sources.json לספרייה מקומית.
  4. בטרמינל המקומי או ב-Cloud Shell, מריצים את פקודת הייבוא של gcloud שמתוארת בקטע הגדרת הקישוריות של dbt ומגדירים את --artifacts-path לספרייה שמכילה את הקבצים שהורדתם.

למידע נוסף, קראו את המאמר Run visibility במסמכי התיעוד של dbt.

הורדת פריטי מידע באמצעות ה-CLI של פלטפורמת dbt

ממשק שורת הפקודה (CLI) של פלטפורמת dbt (לשעבר dbt Cloud CLI) מריץ פקודות dbt בפלטפורמת dbt Cloud מהמסוף המקומי, ומוריד באופן אוטומטי את פריטי המידע שנוצרו לספרייה target/ של פרויקט dbt המקומי.

  1. בטרמינל המקומי, עוברים לתיקיית השורש של פרויקט ה-dbt ומריצים את שלוש הפקודות שמפורטות בקטע דרישות מוקדמות ל-dbt.
  2. מריצים את פקודת הייבוא של gcloud שמתוארת בקטע הגדרת הקישוריות של dbt ומגדירים את --artifacts-path לספריית הבסיס של הפרויקט או לספרייה target/.

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

מידע נוסף זמין במאמר התקנת ה-CLI של פלטפורמת dbt במאמרי העזרה של dbt.

הורדת פריטי מידע שנוצרו בתהליך הפיתוח (Artifact) באמצעות dbt Administrative API

אתם יכולים להשתמש ב-dbt Administrative API כדי לאחזר באופן פרוגרמטי פריטי מידע שנוצרו בעקבות הרצה של משימה שהושלמה. נקודת הקצה List Run Artifacts מחזירה את נתיבי הקבצים שנוצרו על ידי הרצה, ונקודת הקצה Retrieve Run Artifact מורידה קובץ פריט מידע שנוצר בתהליך הפיתוח ספציפי מכתובת ה-URL הבאה:

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

‫ACCESS_URL תלוי באזור שבו מתארח החשבון שלכם ב-dbt Cloud. מאמתים את הבקשות באמצעות אסימון שירות של dbt Cloud. מידע נוסף זמין בדפים הבאים במסמכי התיעוד של dbt:

במסוף המקומי, ב-Cloud Shell או בסביבת תהליך העבודה האוטומטי, מורידים את manifest.json,‏ catalog.json,‏ run_results.json ו-sources.json לספרייה מקומית או לקטגוריה של Cloud Storage, ואז מריצים את הפקודה gcloud שמתוארת בקטע הגדרת הקישוריות של dbt בנתיב הזה.

כברירת מחדל, נקודת הקצה של פריט המידע שנוצר מחזירה פריטי מידע שנוצרו מהשלב האחרון של ההרצה, אלא אם מציינים את הפרמטר step של השאילתה. כשמגדירים את המשימה כמו שמתואר בקטע הגדרת המשימה ב-dbt Cloud, השלב האחרון הוא dbt parse --write-catalog או dbt docs generate --no-compile, שרק כותב את catalog.json ומשאיר את שלושת פריטי המידע האחרים ללא שינוי בשלב ברירת המחדל.

אחזור מזהה ההרצה

כדי להוריד את פריטי המידע שנוצרו בהפעלה ספציפית, צריך את מזהה ההפעלה. אפשר להעתיק את מזהה ההרצה מכתובת ה-URL של ההרצה במסוף dbt Google Cloud , או לשלוח שאילתה ל-API מהטרמינל או מסקריפט של תהליך העבודה כדי לקבל את ההרצה המוצלחת האחרונה של משימה:

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

בפרמטרים של השאילתה, status=10 מסנן הפעלות שהושלמו עם סטטוס Success. אתם יכולים לדגום את נקודת הקצה הזו לפי לוח זמנים כדי לזהות את ההפעלה המוצלחת האחרונה, להוריד את פריטי המידע שנוצרו בה ולהריץ את פקודת הייבוא של gcloud.

הפעלת הייבוא באמצעות תגובה לפעולה מאתר אחר (webhook)

במקום לדגום את ה-API, אתם יכולים להגדיר webhook של dbt Cloud כדי להפעיל ייבוא אוטומטי של מטא-נתונים בכל פעם שהרצת משימה מסתיימת. ה-webhook שולח מטען ייעודי (payload) לנקודת קצה (endpoint) של HTTP שאתם מספקים:

  1. במסוף dbt Google Cloud , נכנסים אל Account settings ‏ > Webhooks ולוחצים על Create webhook (או על Create new webhook). מגדירים את המינוי ל-webhook:
    • אירועים: בוחרים באפשרות Run completed (job.run.completed), שמופעלת רק אחרי שההרצה מסתיימת והפריטים שלה זמינים להורדה.
    • ‫Jobs: בוחרים את משימות הפריסה של dbt Cloud שרוצים לעקוב אחריהן.
    • נקודת קצה (endpoint): מזינים את כתובת ה-URL מסוג HTTPS של שירות שאתם מפעילים (לדוגמה, שירות Cloud Run או פונקציית Cloud Run).
  2. שומרים את האסימון הסודי של ה-webhook שמוצג ב-dbt Cloud. השירות שלכם משתמש בסוד הזה כדי לאמת את הכותרת Authorization, שמכילה חתימת HMAC-SHA256 של גוף הבקשה.
  3. בשירות שלכם, קוראים את data.runId מהמטען הייעודי (payload) בפורמט JSON, מורידים את פריטי המידע שנוצרו בהרצה באמצעות Administrative API כמו שמתואר למעלה, ומריצים את הפקודה gcloud dataplex dbt metadata-jobs create.

כשמטמיעים את ה-webhook handler, חשוב להביא בחשבון את הדברים הבאים:

  • ‫dbt Cloud ממתין לתגובה במשך 10 שניות לכל היותר. מכיוון שייבוא המטא-נתונים נמשך כמה דקות, קודם צריך להחזיר תגובת HTTP ולהריץ את הייבוא ברקע (לדוגמה, כמשימה של Cloud Run או באמצעות הדגל --async).
  • האירוע job.run.completed מופעל גם בהרצות שנכשלו, כך שהרצות עם בדיקות שנכשלו עדיין מיובאות. אל תירשמו ל-job.run.errored, כי הוא יכול לפעול לפני שהפריטים של ההרצה זמינים.

למידע נוסף על מטענים ייעודיים (payloads) של תגובות לפעולה מאתר אחר ואימות חתימה, ראו תגובות לפעולה מאתר אחר למשימות במסמכי התיעוד של dbt.

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

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

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

המסוף

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

    לדף Connectors

  2. לוחצים על הוספת חיבור.

  3. ברשימה Connectors, בוחרים בכרטיס dbt Core and MetricFlow.

  4. כדי לראות את נכסי ה-dbt שיובאו, עוברים לדף Search או לדף Entry groups של היעד.

gcloud

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

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

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

    gcloud 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/) (פלט/Staging), שאליו מועלה קובץ ה-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 שלו לא היה קיים בהרצה הזו שומר על הערך שניתן לו בהרצה קודמת. השיטה הזו מתאימה להטמעה שגרתית וחוזרת. איך מריצים מחדש את ההטמעה
    • ‫--include-entry-links: הפקת קישורים לרשומות של קשרי dbt. ההגדרה הזו מופעלת כברירת מחדל. כדי להשבית את האפשרות, משתמשים ב---no-include-entry-links. הפקודה מפיקה את סוגי הקישורים הבאים לרשומות:
      • ‫reference: משאב אחד תלוי במשאב אחר, מתאר אותו או משתמש בו. הוא כולל יחסי תלות של dbt בין צמתים, בדיקה והמשאב שהיא בודקת, מודל סמנטי או מדד והמשאב שעליו הוא מבוסס, צומת ופקודות המאקרו של הפרויקט שהוא קורא להן, וצומת והטבלה ב-BigQuery שהוא מתממש בה.
      • schema-join: עמודות שאפשר לצרף, שהוגדרו בבדיקת relationships dbt.
    • --skip-bigquery-link: דילוג על reference קישורים (צומת dbt ← טבלה ב-BigQuery). כברירת מחדל, קישור reference נוצר לכל צומת dbt שנוצר (מודל, seed, תמונת מצב) שמערך הנתונים שלו ב-BigQuery נמצא במיקום הייבוא (--location). מקורות dbt לא מקבלים קישור reference לטבלה שלהם ב-BigQuery. קישורי רשומות יכולים להפנות רק לרשומות של @bigquery באותו אזור, כך שקבוצות נתונים באזור אחר נדלגות באופן אוטומטי. כדי לקבוע את האזור של כל מערך נתונים, הפקודה קוראת ל-BigQuery API, ולכן למבצע הקריאה נדרשת ההרשאה bigquery.datasets.get במערכי הנתונים האלה. בלי ההרשאה הזו, הפקודה לא יכולה לדלג על מערכי נתונים באזורים אחרים והקישורים אליהם לא נפתרים. אם הטבלאות ב-BigQuery לא מקוטלגות ב-Knowledge Catalog, משתמשים ב---skip-bigquery-link.
    • ‫--validate-only: יוצרים ומעלים את קובץ ה-JSON ומאמתים את משימת המטא-נתונים, אבל לא מטמיעים בפועל.

  4. מוודאים שמופיע הסטטוס Created.

REST

כדי לייבא מטא-נתונים של dbt באמצעות ה-API בארכיטקטורת REST:

  1. יוצרים את פריטי המידע של dbt וממירים אותם לקובץ הייבוא של Knowledge Catalog בפורמט JSON‏ (dbt_metadata.jsonl).
  2. מעלים את הקובץ שעבר טרנספורמציה לקטגוריית ה-Staging ב-Cloud Storage‏ (gs://BUCKET_NAME/PATH/).

  3. מפעילים את השיטה projects.locations.metadataJobs.create:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו נמצאת קבוצת הרשומות.
    • ‫LOCATION: האזור של קבוצת הרשומות (לדוגמה, us-central1).
    • ‫JOB_ID: מזהה ייחודי של משימת המטא-נתונים.
    • ‫BUCKET_NAME/PATH: הקידומת של ה-URI של Cloud Storage שאליו הועלה הקובץ dbt_metadata.jsonl.
    • ‫ENTRY_GROUP: המזהה הקצר של קבוצת הרשומות ביעד.

  4. כדי לעקוב אחרי הסטטוס של משימת הייבוא, משתמשים ב-method‏ projects.locations.metadataJobs.get:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

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

הפעלה מחדש של ההטמעה

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

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

  • ההטמעה הראשונה בקבוצת רשומות.
  • משאב dbt נוסף, נמחק או ששמו שונה.
  • השם המוצג, התיאור או התוויות של רשומה משתנים.
  • ההיררכיה של הרשומות משתנה.
  • שינוי ביחסי התלות של dbt, למשל כשמוסיפים או מסירים ref(), source(), בדיקה או קריאה למאקרו. הפעלות של --aspects-only לא יוצרות או מעדכנות קישורים לרשומות.
  • אתם משנים את --include-entry-links או את --skip-bigquery-link.

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

מריצים את --aspects-only כדי לרענן את התרחישים:

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

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

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

המסוף

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

    מעבר לחיפוש

  2. בחלונית Filters, מסננים לפי נכסי dbt:

    • בקטע System, בוחרים באפשרות Imported Context.
    • בסעיף המשנה Managed Connectors שמופיע, בוחרים באפשרות dbt.

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

  4. בתוצאות החיפוש, לוחצים על נכס dbt כלשהו כדי לפתוח את דף פרטי הרשומה שלו ולראות את הסכימה, השושלת וההיבטים הטכניים שלו.

gcloud

  1. כדי לחפש רשומות dbt בפרויקט, משתמשים בפקודה gcloud dataplex entries search:

    gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

    כדי לסנן לפי סוג רשומה ספציפי של dbt (כמו מודלים או מקורות):

    gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

  2. כדי לראות את הפרטים וההיבטים המלאים של רשומת dbt ספציפית, משתמשים בפקודה gcloud dataplex entries lookup:

    gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫LOCATION: המיקום של קבוצת הרשומות (לדוגמה, us-central1).
    • ‫ENTRY_GROUP: המזהה הקצר של קבוצת הרשומות ביעד (לדוגמה, dbt-metadata-ingestion).
    • ‫ENTRY_ID: המזהה הקצר או שם המשאב היחסי של רשומת ה-dbt.

REST

  1. כדי לחפש רשומות dbt, מפעילים את השיטה projects.locations:searchEntries:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

    כדי לסנן לפי סוג ספציפי של משאב dbt:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

  2. כדי לאחזר את הפרטים וההיבטים המלאים של המטא-נתונים של רשומה ספציפית, מפעילים את השיטה projects.locations.entryGroups.entries.get:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

  3. כדי לאחזר הקשר של LLM למשאבי dbt ספציפיים, משתמשים ב-API‏ projects.locations:lookupContext:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫LOCATION: המיקום של קבוצת הרשומות (לדוגמה, us-central1).
    • ‫ENTRY_GROUP: המזהה הקצר של קבוצת הרשומות ביעד (לדוגמה, dbt-metadata-ingestion).
    • ‫ENTRY_ID: המזהה הקצר או שם המשאב היחסי של רשומת ה-dbt.

כדי להציג את הקישורים של רשומת dbt, צריך לבצע קריאה ל-method‏ projects.locations:lookupEntryLinks. לדוגמה, כדי לאחזר את הטבלה ב-BigQuery שאליה מודל dbt יוצר חומר:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

‫ENTRY_NAME הוא השם המלא של המשאב ברשומת ה-dbt. התוצאות מחולקות לדפים, עם עד 10 קישורים בכל דף.

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

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