שימוש ב-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 בפקודה שרוצים לקבל עליה מידע.

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