ייבוא מטא-נתונים מ-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 לא נדרשת גישה לקטגוריית האחסון של ארטיפקטים של קלט.
  • פלט (קטגוריית אחסון זמני לייבוא ל-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) כדי להעלות את הקובץ, ולסוכן השירות של קטלוג הידע צריכה להיות הרשאת קריאה (roles/storage.objectViewer) כדי לייבא אותו.

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

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

  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.

המסוף

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

    כניסה לדף Connectors

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

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

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

gcloud

כדי ליצור משימת מטא-נתונים של 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. מוודאים שקיבלתם סטטוס נוצר.

REST

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

  1. יוצרים את הארטיפקטים של dbt וממירים אותם לקובץ ייבוא JSON של Knowledge Catalog (dbt_metadata.jsonl).
  2. מעלים את הקובץ שעבר טרנספורמציה לקטגוריית הביניים של 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. כדי לעקוב אחרי הסטטוס של עבודת הייבוא, משתמשים בשיטה 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 מתווסף, משנה שם או נמחק.
  • השם המוצג, התיאור או התוויות של רשומה משתנים.
  • ההיררכיה של הרשומה משתנה.

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

מריצים את הפקודה --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:

    • בקטע 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.

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

מגבלות

  • תמיכה בגרסאות עדכניות של 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, מודלים) למקורות חיצוניים של צד שלישי לא נכללות בשושלת הנתונים.

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