הגדרת יחסי תלות

במאמר הזה מוסבר איך להגדיר את הקשר בין אובייקטים בתהליך העבודה ב-Dataform באמצעות הצהרה על תלות.

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

הצהרות התלות יוצרות עץ תלות של תהליך העבודה, שקובע את הסדר שבו Dataform מריץ את הפעולות בתהליך העבודה.

אפשר להגדיר את יחסי התלות בין הפעולות הבאות בתהליך העבודה:

הצהרות על מקורות נתונים
הצהרות של מקורות נתונים ב-BigQuery שמאפשרות לכם להפנות למקורות הנתונים האלה בהגדרות של טבלאות Dataform ובפעולות SQL. אפשר להגדיר הצהרה על מקור נתונים כתלות, אבל לא כגורם שתלוי במשהו אחר.
טבלאות
טבלאות שיוצרים ב-Dataform על סמך מקורות הנתונים המוצהרים או טבלאות אחרות בתהליך העבודה. ‫Dataform תומך בסוגי הטבלאות הבאים: table,‏ incremental table,‏ view ו-materialized view. אפשר להגדיר טבלה כתלות וכטבלה שתלויה בטבלה אחרת.
פעולות SQL בהתאמה אישית
הצהרות SQL שמופעלות ב-BigQuery על ידי Dataform כמו שהן, בלי שינוי. אפשר להגדיר פעולת SQL בהתאמה אישית שמוגדרת בקובץ type: operations כתלות וכגורם תלוי. כדי להצהיר על פעולת SQL בהתאמה אישית כתלות בפונקציה ref, צריך להגדיר את המאפיין hasOutput לערך true בקובץ ההגדרה של פעולת ה-SQL בהתאמה אישית ב-SQLX.
טענות
שאילתות לבדיקת איכות הנתונים שבהן אפשר להשתמש כדי לבדוק את נתוני הטבלה. ‫Dataform מריץ הצהרות בכל פעם שהוא מעדכן את תהליך העבודה, ומתריע אם הצהרה כלשהי נכשלת. אפשר להגדיר טענה שמוגדרת בקובץ type: assertion כתלות וכגורם שתלוי בגורם אחר, על ידי הצהרה על תלויות בבלוק config.

אפשר להגדיר את יחסי התלות בדרכים הבאות:

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

  1. יצירה ואתחול של סביבת עבודה לפיתוח במאגר.
  2. אופציונלי: הצהרה על מקור נתונים.
  3. יוצרים לפחות שתי פעולות בתהליך העבודה: טבלאות, טענות, הצהרות על מקורות נתונים, או פעולות.

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

כדי לקבל את ההרשאות שנדרשות להצהרה על תלות בטבלאות, בהצהרות, בהצהרות על מקורות נתונים ובפעולות SQL בהתאמה אישית, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Dataform Editor ‏ (roles/dataform.editor) בסביבות עבודה. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

הצהרה על תלות כארגומנט של הפונקציה ref

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

הפונקציה ref היא פונקציה מובנית ב-Dataform Core שמאפשרת לכם להפנות לכל טבלה, הצהרה על מקור נתונים או פעולת SQL מותאמת אישית, ולהגדיר תלות אוטומטית בהם, כשהמאפיין hasOutput מוגדר לערך true בתהליך העבודה.

מידע נוסף על הפונקציה ref מופיע במאמר הסבר על שיטות ליבה של Dataform.

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

בדוגמת קוד הבאה מוצגת הצהרה של מקור נתונים source_data שנוספה כארגומנט של הפונקציה ref בקובץ ההגדרה incremental_table.sqlx SQLX של טבלה מצטברת:

// filename is incremental_table.sqlx

config { type: "incremental" }

SELECT * FROM ${ref("source_data")}

בדוגמת הקוד שצוינה למעלה, המשתנה source_data מוצהר אוטומטית כתלות של incremental_table.

בדוגמה הבאה של קוד מוצג קובץ SQLX עם הגדרת טבלה some_table שנוסף כארגומנט של הפונקציה ref בקובץ ההגדרה custom_assertion.sqlx של טענה ב-SQLX:

// filename is custom_assertion.sqlx

config { type: "assertion" }

SELECT
  *
FROM
  ${ref("some_table")}
WHERE
  a is null
  or b is null
  or c is null

בדוגמת הקוד שצוינה למעלה, המשתנה some_table מוצהר אוטומטית כתלות של custom_assertion. במהלך ההרצה, Dataform מריץ את some_table קודם, ואז מריץ את custom_assertion אחרי ש-some_table נוצר.

הצהרה על יחסי תלות בבלוק config

כדי להצהיר על תלות שלא מוזכרת בהגדרת הצהרת ה-SQL של התלות, אבל צריך להפעיל אותה לפני הטבלה, הטענה או פעולת ה-SQL המותאמת אישית, פועלים לפי השלבים הבאים:

  1. בסביבת העבודה לפיתוח, בחלונית Files, מרחיבים את הספרייה definitions/.
  2. בוחרים את הקובץ SQLX של הטבלה, האסרטיב או פעולת ה-SQL המותאמת אישית שרוצים לערוך.

  3. בבלוק config של הקובץ, מזינים את קטע הקוד הבא:

    dependencies: [ "DEPENDENCY", ]

    מחליפים את DEPENDENCY במחרוזת היעד – לדוגמה, שם הקובץ של הפעולה שרוצים להוסיף כתלות. אפשר להזין כמה יעדים ולהפריד ביניהם באמצעות פסיקים.

  4. אופציונלי: לוחצים על עיצוב.

בדוגמת הקוד הבאה אפשר לראות את הטבלה some_table ואת טענת some_assertion שנוספו כתלות לבלוק config של קובץ הגדרת הטבלה:

config { dependencies: [ "some_table", "some_assertion" ] }

הגדרת טענות כהצהרות תלות

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

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

הגדרת טענות נבחרות כתלויות

אפשר להגדיר טענות נבחרות כתלויות באופן ידני על ידי הוספתן לשורה dependencies: [ "" ] בקטע config של הפעולה הערוכה.

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

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

הגדרת הטענות של פעולת תלות שנבחרה כתלויות

אתם יכולים להגדיר את הפרמטר includeDependentAssertions כך שכל ההצהרות הישירות של פעולת זרימת עבודה של תלות שנבחרה יוגדרו באופן אוטומטי כתלויות של הפעולה שנערכה. ‫Dataform מוסיף את ההצהרות האלה כתלות במהלך כל קומפילציה של הפעולה כדי לוודא שהתלויות עדכניות אם ההצהרות של פעולת התלות משתנות.

לדוגמה, אם פעולה C תלויה בפעולות A ו-B, אבל אתם רוצים שפעולה C תהיה תלויה רק באסרטיבים של פעולה A, אתם יכולים לערוך את פעולה C ולהגדיר את הפרמטר includeDependentAssertions כך שכל האסרטיבים של פעולה A יוגדרו אוטומטית כתלות של פעולה C.

אפשר להגדיר את הפרמטר includeDependentAssertions לפעולות מהסוגים הבאים:

  • table
  • view
  • operations
הגדרת הטענות של כל פעולות התלות כתלויות

אפשר להגדיר את הפרמטר dependOnDependencyAssertions כך שכל ההצהרות הישירות מכל פעולות התלות של הפעולה הערוכה יוגדרו באופן אוטומטי כתלויות נוספות של הפעולה הערוכה. ‫Dataform מוסיף את ההצהרות האלה כתלות במהלך כל קומפילציה של הפעולה כדי לוודא שהתלויות עדכניות אם ההצהרות של פעולת התלות משתנות.

לדוגמה, אם הפעולה C תלויה בפעולות A ו-B, אפשר לערוך את הפעולה C ולהגדיר את הפרמטר dependOnDependencyAssertions כך שכל האסרטיבים של הפעולות A ו-B יוגדרו אוטומטית כתלות של הפעולה C.

אפשר להגדיר את הפרמטר dependOnDependencyAssertions לפעולות מהסוגים הבאים:

  • table
  • view
  • operations

כשמגדירים את הפרמטר dependOnDependencyAssertions ואת הפרמטרים includeDependentAssertions בקובץ אחד, הפרמטר includeDependentAssertions מקבל עדיפות. לדוגמה, אם מגדירים את dependOnDependencyAssertions ל-true, אבל מגדירים גם את includeDependentAssertions ל-false לפעולת תלות נבחרת, Dataform לא יוסיף את הטענות של הפעולה הזו לתלויות.

בדוגמת הקוד הבאה מוצגים הפרמטרים dependOnDependencyAssertions ו-includeDependentAssertions שמוגדרים באותו קובץ הגדרה של טבלה:

// filename is tableName.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "actionA", {name: "actionB", includeDependentAssertions: false} ]
}

SELECT * FROM ${ref("actionC")}

בדוגמת הקוד שלמעלה, Dataform מוסיף את כל ההצהרות הישירות של actionA ו-actionC לתלות של tableName במהלך הקומפילציה.

הגדרת טענות נבחרות כתלויות

כדי להפעיל פעולה בתהליך עבודה רק אם טענות נבחרות עוברות את הבדיקה, אפשר להוסיף את הטענה הנבחרת לשורה dependencies: [ "" ] בבלוק config של הפעולה הערוכה.

כדי להגדיר טענה שנבחרה כתלות של פעולה שנבחרה בתהליך העבודה, פועלים לפי השלבים הבאים:

  1. בסביבת העבודה לפיתוח, בחלונית Files (קבצים), מרחיבים את definitions/.
  2. בוחרים קובץ SQLX של פעולה בתהליך עבודה.
  3. בבלוק config של קובץ הפעולה, מזינים dependencies: [ "" ].

  4. בתוך dependencies: [ "" ], מזינים את השם של טענת הפעולה או את שם הקובץ של הטענה הידנית שרוצים להגדיר כתלות באחד מהפורמטים הבאים:

    nonNull

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_nonNull"]
}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫ACTION_DATASET_NAME: השם של מערך הנתונים שבו מוגדרת הפעולה. ערכת הנתונים שמוגדרת כברירת מחדל מוגדרת בקובץ ההגדרות של תהליך העבודה.
    • ‫ACTION_NAME: שם הפעולה שבה מוגדרת הטענה.

    rowConditions

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_rowConditions"]
}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫DATASET_NAME: השם של מערך הנתונים שבו מוגדרת הפעולה. ערכת הנתונים שמוגדרת כברירת מחדל מוגדרת בקובץ ההגדרות של תהליך העבודה.
    • ‫ACTION_NAME: שם הפעולה שבה מוגדרת הטענה.

    uniqueKey

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKey_INDEX"]
}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫DATASET_NAME: השם של מערך הנתונים שבו מוגדרת הטבלה. ערכת הנתונים שמוגדרת כברירת מחדל מוגדרת בקובץ ההגדרות של תהליך העבודה.
    • ‫ACTION_NAME: שם הטבלה שבה מוגדרת הטענה.
    • ‫INDEX: האינדקס של מערך המפתחות שמוגדרים בטענת הנכונות (assertion) uniqueKey שרוצים להוסיף כתלות. לדוגמה: 0 או 1. אם מוגדר רק מערך אחד של מפתחות באסרטיון, האינדקס הוא 0.

    uniqueKeys

    config {
  type: "ACTION_TYPE",
  dependencies: [ "ACTION_DATASET_NAME_ACTION_NAME_assertions_uniqueKeys_INDEX"]
}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫DATASET_NAME: השם של מערך הנתונים שבו מוגדרת הטבלה. ערכת הנתונים שמוגדרת כברירת מחדל מוגדרת בקובץ ההגדרות של תהליך העבודה.
    • ‫ACTION_NAME: שם הטבלה שבה מוגדרת הטענה.
    • ‫INDEX: האינדקס של מערך המפתחות שמוגדרים בטענת הנכונות (assertion) uniqueKeys שרוצים להוסיף כתלות. לדוגמה: 0 או 1. אם מוגדר רק מערך אחד של מפתחות באסרטיון, האינדקס הוא 0.

    הצהרת בעלות ידנית

    config {
  type: "ACTION_TYPE",
  dependencies: [ "MANUAL_ASSERTION_NAME"]
}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫MANUAL_ASSERTION_NAME: השם של ההצהרה הידנית.

  5. כדי להוסיף עוד טענה כתלות לטבלה הערוכה, חוזרים על שלב 4.

  6. אופציונלי: לוחצים על עיצוב.

בדוגמת הקוד הבאה מוצגות טענות שנוספו לטבלה A, שמוגדרת במערך הנתונים dataform:

config {
  type: "table",
  assertions: {
    uniqueKey: ["user_id"],
    nonNull: ["user_id", "customer_id"],
  }
}

בדוגמת הקוד הבאה אפשר לראות טענות של טבלה A שנוספו כתלות לטבלה B:

config {
  type: "table",
  dependencies: [ "dataform_A_assertions_uniqueKey_0",  "dataform_A_assertions_nonNull"]
}

בדוגמה הבאה של קוד מוצגת טענה ידנית שמוגדרת בקובץ manualAssertion.sqlx ונוספת כתלות לתצוגה:

config {
  type: "view",
  dependencies: [ "manualAssertion"]
}

בדוגמת הקוד הבאה אפשר לראות את קובץ manual_assertion ואת טבלת sometable שנוספה כתלות לטבלה:

config {
  type: "table",
  dependencies: [ "manual_assertion",  "dataform_sometable_assertions_nonNull" ,  "dataform_sometable_assertions_rowConditions"]
}

SELECT * FROM ${ref("referenced_table")} LEFT JOIN ...

הגדרת הטענות של פעולה נבחרת כתלויות

כדי להפעיל פעולה בתהליך עבודה רק כשכל הטענות הישירות של פעולת תלות נבחרת עוברות, מגדירים את הפרמטר includeDependentAssertions לערך true בפעולה הערוכה. ‫Dataform מוסיף אוטומטית את ההצהרות הישירות של פעולת התלות שנבחרה לתלויות במהלך ההידור. ערך ברירת המחדל הוא false.

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

  1. בסביבת העבודה לפיתוח, בחלונית Files (קבצים), מרחיבים את definitions/.
  2. בוחרים קובץ SQLX של פעולה בתהליך עבודה.

  3. בתוך הקובץ, מגדירים את הפרמטר includeDependentAssertions לערך true באחת מהדרכים הבאות:

    בבלוק config

    config {
type: "ACTION_TYPE",
dependencies: [{name: "dEPENDENCY_ACTION_NAME", includeDependentAssertions: true}]
}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫DEPENDENCY_ACTION_NAME: השם של פעולת התלות עם הטענות שרוצים להגדיר כתלויות של הפעולה שנערכת.

    בדף הפירוט SELECT

      config { type: "ACTION_TYPE" }

  SELECT * FROM ${ref({name: "DEPENDENCY_ACTION_NAME", includeDependentAssertions: true})}

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

    • ‫ACTION_TYPE: סוג הפעולה בתהליך העבודה: ‫table,‏ view או operations.
    • ‫DEPENDENCY_ACTION_NAME: השם של פעולת התלות עם הטענות שרוצים להגדיר כתלויות של הפעולה שנערכת.

  4. אופציונלי: לוחצים על עיצוב.

בדוגמת הקוד הבאה מוצג tableC, שתלוי ב-viewA, ב-tableB ובכל הטענות של tableB:

// filename is tableC.sqlx

config {
type: "table",
dependencies: ["viewA", {name: "tableB", includeDependentAssertions: true}]
}

SELECT * FROM ...

בדוגמת הקוד שלמעלה, Dataform מוסיף אוטומטית את כל ההצהרות הישירות של tableB כתלות ב-tableC במהלך הקומפילציה.

הגדרת הטענות של כל פעולות התלות כתלויות

כדי להריץ פעולה בתהליך עבודה רק אם כל הטענות הישירות של כל פעולות התלות עוברות, מגדירים את הפרמטר dependOnDependencyAssertions לערך true בפעולה הערוכה. ‫Dataform מוסיף באופן אוטומטי את ההצהרות הישירות של פעולות התלות כתלויות במהלך ההידור. ערך ברירת המחדל הוא false.

כשמגדירים את הפרמטר dependOnDependencyAssertions ואת הפרמטרים includeDependentAssertions בקובץ אחד, הפרמטר includeDependentAssertions מקבל עדיפות בפעולת התלות שעבורה הוא מוגדר.

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

  1. בסביבת העבודה לפיתוח, בחלונית Files (קבצים), מרחיבים את definitions/.
  2. בוחרים קובץ SQLX של פעולה בתהליך עבודה.

  3. בקובץ, מגדירים את הפרמטר dependOnDependencyAssertions לערך true בפורמט הבא:

    config {
type: "ACTION_TYPE",
dependOnDependencyAssertions: true,
dependencies: [ "dependency1", "dependency2" ]
}

    מחליפים את ACTION_TYPE: סוג הפעולה בתהליך העבודה. הערכים הנתמכים כוללים table,‏ view ו-operations.

  4. אופציונלי: לוחצים על עיצוב.

בדוגמת הקוד הבאה מוצג sometableE, שתלוי ב-sometableA, sometableB, sometableC, sometableD ובכל הטענות הישירות של טבלאות התלות:

// filename is sometableE.sqlx

config {
type: "table",
dependOnDependencyAssertions: true,
dependencies: [ "sometableA", "sometableB" ]
}

SELECT * FROM ${ref("sometableC")}
SELECT * FROM ${ref("sometableD")}

בדוגמת הקוד שלמעלה, Dataform מוסיף באופן אוטומטי את כל ההצהרות הישירות של sometableA,‏ sometableB,‏ sometableC ו-sometableD כתלות ב-sometableE במהלך ההידור.

הפניה לטבלה עם שם טבלה שהוחלף

  • כדי להפנות לטבלה עם שם טבלה שהוחלף, בפונקציה ref, מזינים את שם הטבלה שהוחלף שהוגדר ב-name: "".

בדוגמת הקוד הבאה יש הפניה לטבלה ששמה הוחלף ב-overridden_name:

  SELECT * FROM ${ref("overridden_name")}

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

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