ניהול מאגר

במאמר הזה נסביר איך לבצע את הפעולות הבאות ב-Dataform:

• הגדרת תהליכי עבודה ב-Dataform.
• ניהול חבילת הליבה של Dataform.
• ניהול גרסאות של הקוד.

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

1. בוחרים מאגר או יוצרים מאגר.

   הערה: רשימת מאגרי Dataform כוללת רק מאגרים שנוצרו לפיתוח תהליכי עבודה ב-Dataform. מאגרים של נכסי BigQuery Studio, כמו מחברות או שאילתות שמורות, מנוהלים בנפרד ולא מופיעים ברשימה הזו.

2. אופציונלי: חיבור המאגר למאגר Git של צד שלישי.

3. יצירה ואתחול של סביבת עבודה לפיתוח במאגר.

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

כדי לקבל את ההרשאות שדרושות לביצוע המשימות שמתוארות במסמך הזה, אתם צריכים לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

• מגדירים את ההגדרות של Dataform ומנהלים את המיקום של חבילת הליבה של Dataform: Dataform Admin (roles/dataform.admin) במאגרי מידע.
• מעדכנים את חבילת הליבה של Dataform ומשתמשים בניהול גרסאות ב-Dataform: Dataform Editor (roles/dataform.editor) בסביבות עבודה.

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

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

הגדרת הגדרות של תהליכי עבודה ב-Dataform

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

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

מידע על הגדרות מאגר

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

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

החל מגרסה Dataform core 3.0.0, הגדרות של תהליכי עבודה נשמרות בקובץ workflow_settings.yaml כברירת מחדל. בגרסאות קודמות של Dataform core, הגדרות של תהליכי עבודה מאוחסנות בקובץ dataform.json. שני קובצי התצורה האלה צריכים להיות בספריית השורש של המאגר. קובץ Dataform core 3.0‏ workflow_settings.yaml תואם לדורות קודמים של קובץ dataform.json. אתם יכולים להמשיך להשתמש בקובץ dataform.json כדי לאחסן הגדרות של תהליכי עבודה. מומלץ להעביר את הגדרות תהליך העבודה של המאגר לפורמט workflow_settings.yaml כדי לשמור על תאימות בעתיד.

מידע על workflow_settings.yaml

קובץ workflow_settings.yaml, שהוצג ב-Dataform core 3.0, מאחסן הגדרות של תהליכי עבודה ב-Dataform בפורמט YAML.

דוגמת קוד workflow_settings.yaml לדוגמה:

  defaultProject: my-gcp-project-id
  defaultDataset: dataform
  defaultLocation: australia-southeast2
  defaultAssertionDataset: dataform_assertions

בדוגמת הקוד שצוינה למעלה, צמדי מפתח/ערך מתוארים באופן הבא:

• ‫defaultProject: מזהה הפרויקט ב-BigQuery Google Cloud .
• ‫defaultDataset: מערך הנתונים ב-BigQuery שבו Dataform יוצר נכסים, שנקראים dataform כברירת מחדל.

• defaultLocation (אופציונלי): המיקום של מערך הנתונים שמוגדר כברירת מחדל ב-BigQuery. ‫Dataform משתמש במיקום הזה כדי לעבד את הקוד ולאחסן את התוצאות. המיקום של העיבוד צריך להיות זהה למיקום של מערכי הנתונים ב-BigQuery. עם זאת, הוא לא צריך להיות זהה למיקום המאגר של Dataform.

  אם לא מגדירים את הפרמטר defaultLocation, ‏ Dataform קובע את המיקום על סמך מערכי הנתונים שאליהם מתייחסת שאילתת ה-SQL. כך זה עובד:

  • אם השאילתה מפנה למערכי נתונים מאותו מיקום, מערכת Dataform משתמשת במיקום הזה.
  • אם השאילתה מפנה למערכי נתונים משני מיקומים שונים או יותר, תתרחש שגיאה. פרטים נוספים על ההגבלה הזו זמינים במאמר בנושא שכפול של מערכי נתונים באזורים שונים.
  • אם השאילתה לא מפנה לאף מערך נתונים, המיקום שמוגדר כברירת מחדל ב-Dataform הוא US multi-region. כדי לבחור מיקום אחר, מגדירים את מיקום ברירת המחדל. אפשר גם להשתמש במשתנה המערכת @@location בשאילתה. מידע נוסף זמין במאמר בנושא ציון מיקומים.

• ‫defaultAssertionDataset: מערך הנתונים ב-BigQuery שבו Dataform יוצר תצוגות עם תוצאות של הצהרות, שנקראות dataform_assertions כברירת מחדל.

מידע נוסף על מאפייני workflow_settings.yaml זמין במאמר בנושא WorkflowSettings ב-GitHub.

אפשר לגשת למאפיינים שמוגדרים ב-workflow_settings.yaml בקוד Dataform כמאפיינים של האובייקט dataform.projectConfig.

אלו המיפויים מאפשרויות workflow_settings.yaml לאפשרויות dataform.projectConfig שנגישות לקוד:

• defaultProject => defaultDatabase
• defaultDataset => defaultSchema
• defaultAssertionDataset => assertionSchema
• projectSuffix => databaseSuffix
• datasetSuffix => schemaSuffix
• namePrefix => tablePrefix

בדוגמה הבאה של קוד אפשר לראות את האובייקט dataform.projectConfig שאליו מתייחסת ההצהרה SELECT בתצוגה:

  config { type: "view" }
  SELECT ${when(
    !dataform.projectConfig.tablePrefix,
    "table prefix is set!",
    "table prefix is not set!"
  )}

מידע על dataform.json

בקובץ dataform.json מאוחסנות הגדרות של תהליכי עבודה ב-Dataform בפורמט JSON.

דוגמת קוד dataform.json לדוגמה:

  {
    "warehouse": "bigquery",
    "defaultDatabase": "my-gcp-project-id",
    "defaultSchema": "dataform",
    "defaultLocation": "australia-southeast2",
    "assertionSchema": "dataform_assertions"
  }

בדוגמת הקוד שצוינה למעלה, צמדי מפתח/ערך מתוארים באופן הבא:

• ‫warehouse: מצביע ל-BigQuery, שבו Dataform יוצר נכסים.
• ‫defaultDatabase: מזהה הפרויקט ב-BigQuery Google Cloud .
• ‫defaultSchema: מערך הנתונים ב-BigQuery שבו Dataform יוצר נכסים.

• defaultLocation (אופציונלי): המיקום של מערך הנתונים שמוגדר כברירת מחדל ב-BigQuery. ‫Dataform משתמש במיקום הזה כדי לעבד את הקוד ולאחסן את התוצאות. המיקום של העיבוד צריך להיות זהה למיקום של מערכי הנתונים ב-BigQuery. עם זאת, הוא לא צריך להיות זהה למיקום המאגר של Dataform.

  אם לא מגדירים את הפרמטר defaultLocation, ‏ Dataform קובע את המיקום על סמך מערכי הנתונים שאליהם מתייחסת שאילתת ה-SQL. כך זה עובד:

  • אם השאילתה מפנה למערכי נתונים מאותו מיקום, מערכת Dataform משתמשת במיקום הזה.
  • אם השאילתה מפנה למערכי נתונים משני מיקומים שונים או יותר, תתרחש שגיאה. פרטים נוספים על ההגבלה הזו זמינים במאמר בנושא שכפול של מערכי נתונים באזורים שונים.
  • אם השאילתה לא מפנה לאף מערך נתונים, המיקום שמוגדר כברירת מחדל ב-Dataform הוא US multi-region. כדי לבחור מיקום אחר, מגדירים את מיקום ברירת המחדל. אפשר גם להשתמש במשתנה המערכת @@location בשאילתה. מידע נוסף זמין במאמר בנושא ציון מיקומים.

• ‫assertionSchema: מערך הנתונים ב-BigQuery שבו Dataform יוצר תצוגות עם תוצאות של הצהרות, שנקראות dataform_assertions כברירת מחדל.

אפשר לגשת למאפיינים שהוגדרו בקובץ dataform.json בקוד הפרויקט כמאפיינים של האובייקט dataform.projectConfig.

הגדרת שמות של סכימות

כדי להגדיר שמות של סכימות, צריך לערוך את המאפיינים defaultDataset ו-defaultAssertionSchema בקובץ workflow_settings.yaml, או את המאפיינים defaultSchema ו-assertionSchema בקובץ dataform.json.

כדי להגדיר את השם של סכימה, מבצעים את השלבים הבאים:

workflow_settings.yaml

1. בסביבת העבודה לפיתוח, בחלונית Files (קבצים), לוחצים על הקובץ workflow_settings.yaml.

2. עורכים את הערך של defaultDataset, defaultAssertionSchema או שניהם.

בדוגמת הקוד הבאה מוצג שם מותאם אישית של defaultDataset שמוגדר בקובץ workflow_settings.yaml:

  ...
  defaultDataset: mytables
  ...

dataform.json

1. בסביבת העבודה לפיתוח, בחלונית Files (קבצים), לוחצים על הקובץ dataform.json.

2. עורכים את הערך של defaultSchema, assertionSchema או שניהם.

בדוגמת הקוד הבאה מוצג שם מותאם אישית של defaultSchema שמוגדר בקובץ dataform.json:

{
  ...
  "defaultSchema": "mytables",
  ...
}

יצירת משתנים מותאמים אישית של אוסף

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

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

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

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

workflow_settings.yaml

1. עוברים לסביבת הפיתוח של Dataform.
2. בחלונית קבצים, בוחרים את הקובץ workflow_settings.yaml.

3. מזינים את קטע הקוד הבא:

   "vars": {
     "VARIABLE":"VALUE"
   }
   

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

   • ‫VARIABLE: שם המשתנה
   • ‫VALUE: ערך ברירת המחדל של משתנה ההידור

בדוגמת הקוד הבאה אפשר לראות את משתנה ההידור myVariableName שמוגדר לערך myVariableValue בקובץ workflow_settings.yaml:

...
vars:
  myVariableName: myVariableValue
...

בדוגמת הקוד הבאה אפשר לראות את הקובץ workflow_settings.yaml עם משתנה הקומפילציה executionSetting שמוגדר ל-dev:

defaultProject: default_bigquery_database
defaultLocation: us-west1
defaultDataset: dataform_data,
vars:
executionSetting: dev

dataform.json

1. עוברים לסביבת הפיתוח של Dataform.
2. בחלונית קבצים, בוחרים את הקובץ dataform.json.

3. מזינים את קטע הקוד הבא:

   "vars": {
     "VARIABLE":"VALUE"
   }
   

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

   • ‫VARIABLE: שם המשתנה
   • ‫VALUE: ערך ברירת המחדל של משתנה ההידור

בדוגמת הקוד הבאה אפשר לראות את משתנה ההידור myVariableName שמוגדר לערך myVariableValue בקובץ dataform.json:

{
  ...
  "vars": {
    "myVariableName": "myVariableValue"
  },
  ...
}

בדוגמת הקוד הבאה אפשר לראות את הקובץ dataform.json עם משתנה הקומפילציה executionSetting שמוגדר ל-dev:

{
"warehouse": "bigquery",
"defaultSchema": "dataform_data",
"defaultDatabase": "default_bigquery_database".
"defaultLocation":"us-west-1",
"vars": {
"executionSetting":"dev"
}
}

הוספת משתנה של אוסף לטבלה

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

1. עוברים לסביבת הפיתוח של Dataform.
2. בחלונית Files, בוחרים קובץ הגדרת טבלה מסוג SQLX.

3. בקובץ, מזינים סעיף when בפורמט הבא:

   ${when(dataform.projectConfig.vars.VARIABLE === "SET_VALUE", "CONDITION")}
   

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

   • ‫VARIABLE: השם של המשתנה, לדוגמה executionSetting
   • ‫SET_VALUE: ערך של המשתנה, לדוגמה staging
   • CONDITION: תנאי להפעלת הטבלה

בדוגמה הבאה של קובץ SQLX עם הגדרת טבלה מוצגים סעיף when והמשתנה executionSetting שמבצע 10% מהנתונים בהגדרת הביצוע של שלב הביניים:

  select
    *
  from ${ref("data")}
  ${when(
    dataform.projectConfig.vars.executionSetting === "staging",
    "where mod(farm_fingerprint(id) / 10) = 0",
  )}

בדוגמה הבאה מוצג קובץ SQLX של הגדרת תצוגה עם פסקה when והמשתנה myVariableName:

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

הגדרת ברירות מחדל ברמת תהליך העבודה לטבלאות Iceberg

אפשר לספק ברירות מחדל ברמת תהליך העבודה לטבלאות מנוהלות של Apache Iceberg בקובץ workflow_settings.yaml. אתם יכולים להגדיר ערכי ברירת מחדל לשם הדלי, לתיקיית הבסיס של הטבלה ולנתיב המשנה של תיקיית הטבלה.

‫Dataform משתמש בערכי ברירת המחדל האלה כדי ליצור את ה-URI של האחסון עבור טבלה מנוהלת ב-Iceberg, אם לא מגדירים את הערכים האלה בבלוק config של קובץ הגדרת הטבלה.

כדי להגדיר ערכי ברירת מחדל ברמת זרימת העבודה עבור הטבלאות, מוסיפים את הבלוק defaultIcebergConfig עם השדות הבאים לקובץ workflow_settings.yaml:

• ‫bucketName: אופציונלי. שם ברירת המחדל של קטגוריית Cloud Storage.
• ‫tableFolderRoot: אופציונלי. שם ברירת המחדל של התיקייה ברמה הראשונה בתוך הקטגוריה של Cloud Storage.
• ‫tableFolderSubpath: אופציונלי. שם ברירת המחדל של תיקיית משנה בתוך tableFolderRoot.

בדוגמה הבאה של קוד מוצג קובץ workflow_settings.yaml עם ברירות מחדל ברמת תהליך העבודה לטבלאות מנוהלות של Iceberg:

defaultProject: "defaultProject"
defaultDataset: "defaultDataset"
defaultLocation: "us-central1"
defaultIcebergConfig:
  bucketName: "wsDefaultBucketName"
  tableFolderRoot: "wsDefaultTableFolderRoot"
  tableFolderSubpath: "wsDefaultTableFolderSubpath"

אפשר לגשת לשדות האלה בקוד Dataform כמאפיינים של אובייקט ProjectConfig:

dataform.ProjectConfig.defaultIcebergConfig.bucketName
dataform.ProjectConfig.defaultIcebergConfig.tableFolderRoot
dataform.ProjectConfig.defaultIcebergConfig.tableFolderSubpath

מידע נוסף זמין במאמר בנושא יצירה של טבלאות מנוהלות ב-Apache Iceberg ובמאמר בנושא מאפייני בלוק iceberg.

העברת הגדרות של תהליכי עבודה אל workflow_settings.yaml

כדי לוודא שקובץ הגדרות תהליך העבודה שלכם תואם לגרסאות עתידיות של מסגרת Dataform Core, אתם צריכים להעביר את הגדרות תהליך העבודה מקובץ dataform.json לקובץ workflow_settings.yaml.

הקובץ workflow_settings.yaml מחליף את הקובץ dataform.json.

אם חבילת התלות היחידה במאגר היא Dataform core, אז קובץ workflow_settings.yaml מחליף גם את קובץ package.json. מידע נוסף על החלפת הקובץ package.json בקובץ workflow_settings.yaml זמין במאמר בנושא ניהול חבילת הליבה של Dataform.

בטבלה הבאה מוצג מיפוי של מאפייני הגדרות תהליך העבודה מקובץ dataform.json לקובץ workflow_settings.yaml:

נכס ב-dataform.json	נכס ב-workflow_settings.yaml	תיאור
assertionSchema	defaultAssertionDataset	חובה. מערך הנתונים שמוגדר כברירת מחדל לאישורים.
defaultDatabase	defaultProject	חובה. שם הפרויקט Google Cloud שמוגדר כברירת מחדל.
defaultLocation	defaultLocation	זה שינוי אופציונלי. מיקום ברירת המחדל ב-BigQuery שבו Dataform יוצר טבלאות. אם לא מגדירים מיקום, Dataform קובע את המיקום על סמך מערכי הנתונים שאליהם מתייחסת שאילתת ה-SQL. מידע נוסף זמין במאמר בנושא ציון מיקומים.
defaultSchema	defaultDataset	חובה. מערך הנתונים שמוגדר כברירת מחדל.
databaseSuffix	projectSuffix	זה שינוי אופציונלי. הסיומת שמוסיפים לכל ההפניות לפרויקט Google Cloud .
schemaSuffix	datasetSuffix	זה שינוי אופציונלי. הסיומת שמוסיפים לכל מערכי הנתונים של הפעולות.
tablePrefix	namePrefix	זה שינוי אופציונלי. הקידומת שתתווסף לכל שמות הפעולות.
vars	vars	זה שינוי אופציונלי. משתנים שהוגדרו על ידי המשתמש וזמינים לקוד הפרויקט במהלך ההידור. אובייקט שמכיל רשימה של key: value זוגות.
warehouse	-	נדרש בdataform.json. הערך חייב להיות bigquery. לא זמין בworkflow_settings.yaml.
-	dataformCoreVersion	לא זמין בdataform.json. כברירת מחדל, המאפיין הזה מותקן ב-workflow_settings.yaml במאגרים חדשים. מידע נוסף זמין במאמר בנושא ניהול חבילת הליבה של Dataform.

כדי להעביר את הגדרות תהליך העבודה אל workflow_settings.yaml, פועלים לפי השלבים הבאים:

1. נכנסים לדף Dataform במסוף Google Cloud .

   מעבר אל Dataform

2. בוחרים מאגר ואז בוחרים סביבת עבודה.

3. בחלונית Files, לוחצים על addAdd ואז על Create file.

4. בשדה Add a file path (הוספת נתיב קובץ), מזינים את הערך workflow_settings.yaml.

5. לוחצים על יצירת קובץ.

6. בקובץ workflow_settings.yaml, מוסיפים את ההגדרות מקובץ dataform.json, שמוצגות בפורמט YAML.

7. בחלונית קבצים, לוחצים על תפריט האפשרויות הנוספות לצד dataform.json, ואז לוחצים על מחיקה.

8. כדי לאשר את המחיקה של dataform.json, לוחצים על מחיקה.

בדוגמת הקוד הבאה מוצגות הגדרות של תהליך עבודה שמוגדרות בקובץ dataform.json:

{
  "warehouse": "bigquery",
  "defaultDatabase": "dataform-demos",
  "defaultLocation": "US",
  "defaultSchema": "dataform",
  "assertionSchema": "dataform_assertions"
  "vars": {
    "environmentName": "development"
  }
}

בדוגמת הקוד הבאה מוצג הקובץ dataform.json שצוין למעלה אחרי המרה ל-workflow_settings.yaml:

defaultProject: dataform-demos
defaultLocation: US
defaultDataset: dataform
defaultAssertionDataset: dataform_assertions
vars:
    environmentName: "development"

ניהול חבילת הליבה של Dataform

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

‫Dataform Core היא מסגרת Dataform בקוד פתוח לפיתוח תהליכי עבודה באמצעות SQL,‏ SQLX ו-JavaScript. מומלץ להשתמש תמיד בגרסה העדכנית ביותר של מסגרת הליבה של Dataform. מידע על הגרסאות של מסגרת הליבה של Dataform זמין בגרסאות של Dataform ב-GitHub.

ניהול המיקום של חבילת הליבה של Dataform

כשמפעילים את סביבת העבודה הראשונה במאגר, Dataform מגדיר באופן אוטומטי את Dataform Core כחבילת תלות. החל מגרסה Dataform core 3.0.0,‏ Dataform מתקין את חבילת Dataform core בקובץ workflow_settings.yaml כברירת מחדל. בגרסאות קודמות של Dataform core, ‏ Dataform core הוגדר בקובץ package.json.

ב-Dataform core 3.0.0 ואילך, אם Dataform core הוא החבילה היחידה במאגר, צריך להגדיר אותה בקובץ workflow_settings.yaml. אם המאגרים נוצרו בגרסאות קודמות של Dataform Core, צריך להעביר את חבילת Dataform Core אל workflow_settings.yaml.

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

העברת ליבת Dataform אל workflow_settings.yaml

אם המאגרים נוצרו עם גרסאות של Dataform Core שקודמות לגרסה 3.0.0, ואין לכם חבילות של יחסי תלות מלבד Dataform Core, אתם צריכים להעביר את חבילת Dataform Core מהקובץ package.json לקובץ workflow_settings.yaml ולמחוק את הקובץ המיותר package.json.

כדי להעביר את חבילת הליבה של Dataform מקובץ package.json לקובץ workflow_settings.yaml:

1. נכנסים לדף Dataform במסוף Google Cloud .

   מעבר אל Dataform

2. בוחרים מאגר ואז בוחרים סביבת עבודה.

3. בחלונית קבצים, בוחרים את הקובץ workflow_settings.yaml.

4. בקובץ workflow_settings.yaml, מוסיפים את חבילת הליבה של Dataform בפורמט הבא:

   dataformCoreVersion: "VERSION"
   
   

   מחליפים את VERSION בגרסה העדכנית של Dataform, לדוגמה, 3.0.0.

5. בחלונית Files, לוחצים על תפריט More לצד הקובץ package.json ואז לוחצים על Delete.

6. כדי לאשר את המחיקה של קובץ dataform.json, לוחצים על מחיקה.

7. לוחצים על Install packages (התקנת חבילות).

העברת ליבת Dataform אל package.json

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

אם המאגר לא מכיל את הקובץ package.json כי חבילת הליבה של Dataform מוגדרת בקובץ workflow_settings.yaml, צריך ליצור את הקובץ package.json כדי להתקין חבילות נוספות, ואז להעביר את חבילת הליבה של Dataform מהקובץ workflow_settings.yaml לקובץ package.json החדש שנוצר.

כדי ליצור את הקובץ package.json ולהעביר את חבילת הליבה של Dataform, פועלים לפי השלבים הבאים:

1. נכנסים לדף Dataform במסוף Google Cloud .

   מעבר אל Dataform

2. בוחרים מאגר ואז בוחרים סביבת עבודה.

3. בחלונית Files, לוחצים על addAdd ואז על Create file.

4. בשדה Add a file path (הוספת נתיב קובץ), מזינים את הערך package.json.

5. לוחצים על יצירת קובץ.

6. בקובץ package.json, מוסיפים את חבילת הליבה של Dataform בפורמט הבא:

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   מחליפים את VERSION בגרסה העדכנית של Dataform, לדוגמה, 3.0.0.

7. לוחצים על Install packages (התקנת חבילות).

8. בחלונית קבצים, לוחצים על workflow_settings.yaml.

9. בקובץ workflow_settings.yaml, מוחקים את dataformCoreVersion הנכס.

עדכון של Dataform Core

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

כדי לעדכן את חבילת התלות המרכזית של Dataform, פועלים לפי השלבים הבאים:

1. אפשר לעיין בגרסה העדכנית של @dataform/core בדף הגרסאות של Dataform ב-GitHub.

2. נכנסים לדף Dataform במסוף Google Cloud .

   מעבר אל Dataform

3. בוחרים מאגר ואז בוחרים סביבת עבודה.

4. בחלונית Files, בוחרים את קובץ package.json או את קובץ workflow_settings.yaml.

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

5. מעדכנים את חבילת התלות העיקרית של Dataform לגרסה העדכנית:

   package.json

   {
       "dependencies": {
           "@dataform/core": "VERSION"
       }
   }
   

   מחליפים את VERSION בגרסה העדכנית של Dataform, לדוגמה, 3.0.0. כדי למנוע בעיות בהתקנת החבילה, צריך לציין במפורש את גרסת חבילת הליבה של Dataform. לא להשתמש באפשרויות אחרות של קובץ package.json, למשל dependencies או >version.

   workflow_settings.yaml

   dataformCoreVersion: "VERSION"
   

   מחליפים את VERSION בגרסה העדכנית של Dataform, לדוגמה, 3.0.0.

6. לוחצים על Install packages (התקנת חבילות).

7. שמירת השינויים.

8. שליחת השינויים למאגר.

בדוגמת הקוד הבאה אפשר לראות את התלות @dataform/core שמעודכנת לגרסה 3.0.0 בקובץ package.json:

{
    "dependencies": {
        "@dataform/core": "3.0.0"
    }
}

ניהול גרסאות של הקוד

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

ב-Dataform נעשה שימוש ב-Git כדי לעקוב אחרי כל שינוי שבוצע בקבצים במאגר.

במאגר Dataform, אתם מבצעים אינטראקציה ישירות עם מאגר Git.

במאגר מקושר, אתם מבצעים אינטראקציה עם ענף המעקב של המאגר המרוחק שהגדרתם בזמן קישור המאגר.

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

ב-Dataform מוצגות האפשרויות הבאות של בקרת גרסאות:

שמירת השינויים X

מאשרים את X מספר השינויים המקומיים בסביבת העבודה או בקבצים שנבחרו. ב-Dataform מוצגים השינויים שלא בוצעו.

שליחה לענף ברירת המחדל

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

דחיפה אל your-branch-name

דוחפים את השינויים שבוצעו אל your-branch-name. האפשרות הזו זמינה במאגר שמקושר למאגר Git של צד שלישי אם אין שינויים שלא בוצעו בסביבת העבודה.

שליפה מענף ברירת המחדל

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

העברה מ-your-branch-name

מעדכנים את סביבת העבודה בשינויים האחרונים מ-your-branch-name. האפשרות הזו זמינה במאגר שמקושר למאגר Git של צד שלישי אם אין שינויים שלא בוצעו או שינויים שבוצעו ולא נדחפו במרחב העבודה.

חזרה לקומיט האחרון

משחזרים את הקבצים בסביבת העבודה למצב שלהם מההתחייבות האחרונה.

משיכת שינויים

אם סביבת העבודה לפיתוח לא מסונכרנת עם המאגר, האפשרות Pull מוצגת ב-Dataform. כדי למשוך שינויים מהמאגר לסביבת הפיתוח, פועלים לפי השלבים הבאים:

1. בדף Dataform, בוחרים מאגר.
2. בכרטיסייה סביבות עבודה לפיתוח, בוחרים סביבת עבודה לפיתוח.
3. בדף של סביבת הפיתוח, מבצעים את הפעולות הבאות:
   1. אם אתם במאגר Dataform, לוחצים על Pull from default branch (שליפה מענף ברירת המחדל).
   2. אם אתם במאגר שמקושר למאגר Git של צד שלישי, לוחצים על Pull from your-branch-name.

אישור השינויים

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

הערה: כברירת מחדל, Dataform משתמש בכתובת האימייל של המשתמש המאומת כיוצר הקומיט, אבל Dataform API מאפשר להגדיר כתובת אימייל מותאמת אישית ליוצר הקומיט.Google Cloud ההתנהגות הזו דומה לפקודה git commit --author ומשפיעה רק על היסטוריית הקומיטים של Git. הזהות של מחבר הקומיט לא אומתה באופן קריפטוגרפי.

בתיבת הדו-שיח New commit (קובץ חדש להעלאה), מוצגים השינויים שלא הועלו.

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

1. בדף Dataform, בוחרים מאגר.
2. בדף המאגר, בוחרים סביבת עבודה לפיתוח.
3. בדף של סביבת העבודה לפיתוח, לוחצים על Commit (ביצוע).

4. בחלונית New commit:

   1. בשדה Add a commit message (הוספת הודעת קומיט), מזינים תיאור לקומיט.

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

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

   3. לוחצים על Commit All changes (אישור כל השינויים) או על Commit X changes (אישור X שינויים).

      שם הלחצן תלוי בבחירת הקבצים שרוצים להעביר.

שליחת השינויים

האפשרות Push מוצגת ב-Dataform אחרי שמאשרים את השינויים. כדי להעביר שינויים מסביבת הפיתוח למאגר:

1. בדף Dataform, בוחרים מאגר.
2. בדף המאגר, בוחרים סביבת עבודה לפיתוח.
3. אישור השינויים.
4. בדף של סביבת הפיתוח, מבצעים את הפעולות הבאות:
   1. אם אתם במאגר Dataform, לוחצים על Push to default branch (שליחה לענף ברירת המחדל).
   2. אם אתם במאגר שמקושר למאגר Git של צד שלישי, לוחצים על Push to your-branch-name.

ביטול שינויים שלא נשמרו

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

1. בדף Dataform, בוחרים מאגר.
2. בדף המאגר, בוחרים סביבת עבודה לפיתוח.
3. מעל החלונית Files, לוחצים על התפריט More ואז על Revert to last commit.

פתרון בעיות שקשורות למיזוג

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

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

בדוגמת הקוד הבאה אפשר לראות התנגשות מיזוג שמוצגת בקובץ SQLX:

    <<<<<<< HEAD
    SELECT 1 as CustomerOrders
    =======
    SELECT 1 as Orders
    >>>>>>> refs/heads/main

כדי לפתור עריכות מתנגשות:

1. בסביבת הפיתוח, בחלונית Files, בוחרים קובץ מושפע.
2. עורכים את הקובץ עם השינויים הרצויים.
3. אישור השינויים.
4. אופציונלי: דחיפת השינויים.

זיהוי מאגרי נתונים לנכסי BigQuery

מאגרי Dataform שנוצרו ומנוהלים באופן אוטומטי על ידי תכונה אחרת של BigQuery, כמו מחברות או שאילתות שמורות, מוסתרים במסוף Dataform Google Cloud כדי למנוע עומס ולמנוע שינוי לא מכוון של לוגיקה ספציפית לתכונה. יכול להיות שהמאגרים האלה יופיעו בחיפושים ב-מאגר משאבי ענן או בביקורות של הרשאות IAM, אבל הם לא יופיעו ב-Dataform במסוף Google Cloud .

כדי לזהות את המקור של מאגר Dataform, אפשר לבדוק את תוויות המשאבים שלו. בטבלה הבאה מתוארות התוויות שבהן נעשה שימוש בתכונות שונות של BigQuery:

תכונה	מפתח התווית	ערך התווית
מאגרי BigQuery	origin	bigquery-studio
מאגרי Git ב-BigQuery Studio	origin	bigquery-studio-git-folder
קנבסים של נתונים	single-file-asset-type	data_canvas
הכנת הנתונים	single-file-asset-type	data_preparation או data_preparation_sqlx
מחברות	single-file-asset-type	notebook
צינורות עיבוד נתונים	bigquery-workflow	(כל ערך)
שאילתות שמורות	single-file-asset-type	sql

כדי לאחזר את התוויות ממאגר שלא מופיע ב-Dataform, בוחרים באחת מהאפשרויות הבאות:

המסוף

1. נכנסים לדף Asset Inventory במסוף Google Cloud .

   מעבר למלאי הנכסים

2. לוחצים על הכרטיסייה Resource.

3. בחלונית Filter results, ליד Resource type, לוחצים על View more ומזינים dataform.googleapis.com/Repository.

4. בוחרים באפשרות dataform.Repository ולוחצים על אישור.

5. בטבלת התוצאות, מאתרים את המאגר ובודקים את העמודה תוויות. מתאימים את התוויות שנמצאו לטבלה שמתארת את התוויות שמשמשות תכונות שונות של BigQuery כדי לזהות את תכונת המקור.

API

כדי לאחזר תוויות, משתמשים בשיטה projects.locations.repositories.get. מריצים את בקשת ה-API עם הפרטים הבאים:

• נקודת קצה: GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID

לחלופין, בטרמינל, מריצים את הפקודה curl הבאה:

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

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

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫LOCATION: האזור שבו נמצאים משאבי Dataform.
• ‫REPOSITORY_ID: המזהה הייחודי של מאגר Dataform שמתבצעת בו שאילתה.

משאב projects.locations.repositories שמוחזר בתגובה מכיל מפת תוויות עם המטא-נתונים שמשמשים לזיהוי התכונה שממנה הגיעו הנתונים.

gcloud

מריצים את הפקודה הבאה ב-Google Cloud CLI כדי לאחזר את התוויות של מאגר ספציפי:

gcloud asset search-all-resources \
    --asset-types=dataform.googleapis.com/Repository \
    --query="name:projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID" \
    --format="yaml(labels)"

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

• ‫PROJECT_ID: המזהה הייחודי של הפרויקט ב-Google Cloud .
• ‫LOCATION: האזור שבו נמצא המאגר. Google Cloud
• ‫REPOSITORY_ID: המזהה הייחודי של מאגר Dataform החדש.

כדי לאתר את המשאב שמתאים לתווית הפלט, עוברים לדף התכונה התואם במסוף – לדוגמה, התיקיות Notebooks או Data canvases בכרטיסייה Explorer בחלונית הימנית ב-BigQuery Studio. Google Cloud

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

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