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

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

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

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

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

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

התקנת Dataform CLI

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

    npm i -g @dataform/cli

הפעלה של פרויקט Dataform

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

    dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION

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

    • ‫YOUR_GOOGLE_CLOUD_PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫DEFAULT_LOCATION: המיקום ב-BigQuery שבו רוצים ש-Dataform יעבד ויאחסן את הנתונים.

עדכון של Dataform core

  • כדי לעדכן את מסגרת הליבה של Dataform, מעדכנים את dataformCoreVersion בקובץ workflow_settings.yaml. כשמגדירים את dataformCoreVersion ב-workflow_settings.yaml, ‏ Dataform מתקין את @dataform/core באופן אוטומטי בזמן הריצה. אם בפרויקט שלכם מנהלים את @dataform/core בקובץ package.json בלי dataformCoreVersion ב-workflow_settings.yaml, צריך לעדכן את הגרסה ב-package.json ולהריץ את הפקודה:

    dataform install

עדכון Dataform CLI

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

    npm i -g @dataform/cli@^3.0.50

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

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

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

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

    dataform init-creds

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

יצירת פרויקט

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

   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: המיקום ב-BigQuery שבו רוצים ש-Dataform יעבד ויאחסן נתונים.

שכפול פרויקט

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

  • אם בפרויקט המשוכפל מוגדרים יחסי תלות חיצוניים בקובץ package.json (בלי dataformCoreVersion ב-workflow_settings.yaml), מריצים את הפקודה הבאה בתוך ספריית המאגר המשוכפל:

    dataform install

הגדרת טבלה

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

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

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

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

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

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

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

הגדרה של טענת נכוֹנוּת (assertion) ידנית

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

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

    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 ולבנות מחדש טבלאות מצטברות (אלא אם הן מסומנות ב-protected) מאפס, מריצים את הפקודה הבאה:

    dataform run --full-refresh

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

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

    dataform run --dry-run

קבלת עזרה

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

    dataform help

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

    dataform help COMMAND

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

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