שימוש ב-Dataform CLI בקוד פתוח

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

באמצעות Dataform CLI בקוד פתוח, ��תם יכולים לאתחל, לקמפל, לבדוק ולהריץ את Dataform core באופן מקומי, מחוץ ל- Google Cloud.

ה-CLI של Dataform תומך ב-Application Default Credentials ‏ (ADC). בעזרת ADC, פרטי הכניסה לאפליקציה יכולים להיות זמינים בסביבות שונות, כמו בפיתוח מקומי או בייצור, בלי שיהיה צריך לשנות את קוד האפליקציה. כדי שתוכלו להשתמש ב-ADC, קודם כל צריך לספק את פרטי הכניסה ל-ADC.

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

לפני שמתקינים את Dataform CLI, מתקינים את NPM.

התקנת Dataform CLI

  • כדי להתקין את Dataform CLI, מריצים את הפקודה הבאה:

    npm i -g @dataform/cli

איך מאתחלים פרויקט Dataform

  • כדי לאתחל פרויקט חדש ב-Dataform, מריצים את הפקודה הבאה בספריית הפרויקט:

    dataform init . PROJECT_NAME DEFAULT_LOCATION

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

    • ‫PROJECT_NAME: שם הפרויקט.

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

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

עדכון של Dataform Core

  • כדי לעדכן את מסגרת הליבה של Dataform, מעדכנים את dataformCoreVersion בקובץ workflow_settings.yaml, ואז מריצים מחדש את NPM install:

    npm i

עדכון Dataform CLI

  • כדי לעדכן את כלי ה-CLI של Dataform, מריצים את הפקודה הבאה:

    npm i -g @dataform/cli@^3.0.50

יצירת קובץ פרטי כניסה

כדי להתחבר לשירותים מרוחקים וליצור את קובץ .df-credentials.json בדיסק, צריך קובץ פרטי כניסה ב-Dataform.

כדי ליצור את קובץ פרטי הכניסה:

  1. מריצים את הפקודה הבאה:

    dataform init-creds

  2. פועלים לפי ההוראות באשף init-creds ליצירת קובץ פרטי הכניסה.

יצירת פרויקט

פרויקט Dataform ריק ב-Dataform core בגרסה 3.0.0 ואילך כולל את המבנה הבא:

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

  • כדי ליצור פרויקט Dataform לפריסת נכסים ב-BigQuery, מריצים את הפקודה הבאה:

    dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION

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

    • ‫PROJECT_NAME: שם הפרויקט.
    • ‫YOUR_GOOGLE_CLOUD_PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

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

שכפול פרויקט

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

  • אחרי שמשכפלים את המאגר, מריצים את הפקודה הבאה בתוך ספריית המאגר המשוכפל:

    dataform install

הגדרת טבלה

שומרים את ההגדרות בתיקייה definitions/.

  • כדי להגדיר טבלה, מריצים את הפקודה הבאה:

    echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx

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

    • ‫TABLE_TYPE: סוג הטבלה: ‫table,‏ incremental או view.
    • ‫SELECT_STATEMENT: משפט SELECT שמגדיר את הטבלה.
    • ‫FILE: השם של קובץ הגדרת הטבלה.

בדוגמת הקוד הבאה מוגדר תצוגה בקובץ example SQLX.

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

הגדרה של הצהרה ידנית

שומרים את ההגדרות בתיקייה definitions/.

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

    echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx

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

    • ‫SELECT_STATEMENT: הצהרת SELECT שמגדירה את הטענה.
    • ‫FILE: השם של קובץ ההגדרה של פעולת ה-SQL המותאמת אישית.

הגדרת פעולת SQL בהתאמה אישית

שומרים את ההגדרות בתיקייה definitions/.

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

    echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx

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

    • ‫SQL_QUERY: פעולת ה-SQL בהתאמה אישית.
    • ‫FILE: השם של קובץ ההגדרה של פעולת ה-SQL המותאמת אישית.

צפייה בפלט של הקומפילציה

‫Dataform מהדר את הקוד בזמן אמת.

  • כדי לראות את הפלט של תהליך הקומפילציה בטרמינל, מריצים את הפקודה הבאה:

    dataform compile

  • כדי לראות את הפלט של תהליך הקומפילציה כאובייקט JSON, מריצים את הפקודה הבאה:

    dataform compile --json

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

    dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar

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

    • ‫SAMPLE_VAR: המשתנה המותאם אישית של הקומפילציה.
    • ‫SAMPLE_VALUE: הערך של משתנה ההידור המותאם אישית.

הרצת הקוד

כדי להריץ את הקוד, Dataform ניגש ל-BigQuery כדי לקבוע את המצב הנוכחי שלו ולהתאים את ה-SQL שמתקבל בהתאם.

  • כדי להריץ את הקוד של פרויקט Dataform, מריצים את הפקודה הבאה:

    dataform run

  • כדי להריץ את הקוד של פרויקט Dataform ב-BigQuery עם משתני קומפילציה בהתאמה אישית, מריצים את הפקודה הבאה:

    dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2

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

    • ‫SAMPLE_VAR: המשתנה המותאם אישית של הקומפילציה.
    • ‫SAMPLE_VALUE: הערך של משתנה ההידור המותאם אישית.

  • כדי להריץ את הקוד של פרויקט Dataform ב-BigQuery ולבנות מחדש את כל הטבלאות מאפס, מריצים את הפקודה הבאה:

    dataform run --full-refresh

בלי --full-refresh, ‏ Dataform מעדכן טבלאות מצטברות בלי לבנות אותן מחדש מאפס.

  • כדי לבצע הרצה יבש�� של הקוד ב-BigQuery, מריצים את הפקודה הבאה:

    dataform run --dry-run

קבלת עזרה

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

    dataform help

  • כדי לראות תיאור של פקודה ספציפית, מריצים את הפקודה הבאה:

    dataform help COMMAND

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

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