ניהול מאגר

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

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

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

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

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

2. אופציונלי: מקשרים את המאגר למאגר Git של צד שלישי.

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

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

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

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

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

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

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

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

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

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

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

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

החל מגרסה Dataform core 3.0.0, הגדרות תהליך העבודה נשמרות בקובץ workflow_settings.yaml כברירת מחדל. בגרסאות קודמות של ליבת Dataform, ההגדרות של תהליך העבודה מאוחסנות בקובץ dataform.json. שני קובצי התצורה האלה צריכים להיות בתיקיית השורש של המאגר. קובץ workflow_settings.yaml של Dataform core 3.0 תואם לדורות קודמים של הקובץ 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
  dataformCoreVersion: 3.0.62
  preserveGovernanceControls: true

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

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

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

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

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

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

• ‫dataformCoreVersion: הגרסה של חבילת הליבה של Dataform שמותקנת במאגר. מידע נוסף זמין במאמר ניהול חבילת הליבה של Dataform.

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

מידע נוסף על המאפיינים של 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 . אם לא מגדירים את הפרמטר defaultDatabase, ‏Dataform משתמש בפרויקט Google Cloud שבו נמצא המאגר של Dataform.
• ‫defaultSchema: מערך הנתונים ב-BigQuery שבו Dataform יוצר נכסים.

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

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

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

• ‫assertionSchema: מערך הנתונים ב-BigQuery שבו Dataform יוצר תצוגות עם תוצאות של טענות נכונות (assertions). כברירת מחדל, מערך הנתונים נקרא 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",
  ...
}

יצירת משתני הידור מותאמים אישית

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

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

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

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

workflow_settings.yaml

1. נכנסים לסביבת הפיתוח של Dataform.
2. בחלונית Files, בוחרים את הקובץ 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. בחלונית Files, בוחרים את הקובץ 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% מהנתונים בהגדרת ההרצה של ה-staging:

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

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

כדי להגדיר את ברירות המחדל של הטבלאות ברמת תהליך העבודה, מוסיפים את הבלוק 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 framework, צריך להעביר את הגדרות תהליך העבודה מהקובץ 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 . אם לא מגדירים את הפרויקט, Dataform משתמש בפרויקט ב- Google Cloud שבו נמצא המאגר של Dataform.
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. בשדה הוספת נתיב לקובץ, מזינים workflow_settings.yaml.

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

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

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

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 כחבילת תלות. החל מגרסה 3.0.0 של Dataform core, ‏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 core אל 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. בחלונית Files, בוחרים את הקובץ workflow_settings.yaml.

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

   dataformCoreVersion: "VERSION"
   
   

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

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

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

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

העברת Dataform core אל 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. בשדה הוספת נתיב לקובץ, מזינים package.json.

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

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

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

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

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

8. בחלונית Files, בוחרים באפשרות 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 תלוי בגרסה של ליבת Dataform ובשימוש שלכם בחבילות. מידע נוסף זמין במאמר ניהול המיקום של חבילת הליבה של Dataform.

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

   package.json

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

   מחליפים את VERSION בגרסה העדכנית של Dataform, לדוגמה 3.0.0. כדי למנוע בעיות בהתקנת החבילה, צריך לציין במפורש את גרסת החבילה של ליבת Dataform. אל תשתמשו באפשרויות אחרות של dependencies בקובץ package.json, למשל >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 מוצגת רק כשיש שינויים מקומיים שלא נשמרו בסביבת העבודה. כשהקבצים בסביבת העבודה הם עותק מדויק של ברירת המחדל או של הענף למעקב, ב-Dataform מוצג הסטטוס Workspace is up to date.

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

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

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

דחיפה להסתעפות ברירת המחדל

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

העברה אל your-branch-name

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

משיכה מההסתעפות שמוגדרת כברירת מחדל

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

משיכה מ-your-branch-name

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

חזרה לשמירה האחרונה

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

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

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

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

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

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

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

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

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

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

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

   1. בשדה Add a commit message, מזינים תיאור ל-commit.

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

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

   3. לוחצים על Commit All changes או על Commit X changes.

      שם הכפתור תלוי בקבצים שבחרתם לשמור.

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

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

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

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

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

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

פתרון התנגשויות במיזוג

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

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

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

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

כדי לפתור התנגשות במיזוג:

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

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

מאגרי Dataform שנוצרו ומנוהלים באופן אוטומטי על ידי תכונה אחרת של BigQuery, כמו Notebooks או שאילתות שמורות, מוסתרים ב-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
Notebooks	single-file-asset-type	notebook
צינורות עיבוד נתונים	bigquery-workflow	(כל ערך)
שאילתות שמורות	single-file-asset-type	sql

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

המסוף

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

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

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

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

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

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

API

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

• נקודת קצה (endpoint): 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.

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

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

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