הגדרה של מרחב שמות בהתאמה אישית

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

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

מבנה תיקיות של מרחב שמות בהתאמה אישית

התיקיות במרחב השמות של Cortex Framework משמשות לאריזה ולבידוד של ארטיפקטים של מודולים בהתאמה אישית. מבנה התיקיות של מרחב שמות מותאם אישית מוגדר בטבלה:

נתיב הספרייה	מטרה ותיאור
config/	הגדרת הפריסה של Cortex (חובה) כדי ליצור מרחבי שמות חדשים, צריך להגדיר אותם ב-config.yaml.
src/data_modules/custom_namespace/data_foundation/data_foundation_module_type	מודולים של התשתית לנתונים טרנספורמציות של מערכי נתונים גולמיים לתשתית. כל בסיס נתונים מופרד בספריית משנה ומורכב מהרכיבים הבאים: ‫annotations/: תיאורים ברמת העמודה והשדה. ‫table_settings.default.yaml: הגדרה של Table settings
src/data_modules/custom_namespace/data_product/data_product_module_type	הגדרות של מוצרי נתונים כולל לוגיקה עסקית ומודלים אנליטיים. כל מוצר מופרד בספריית משנה ומורכב מהרכיבים הבאים: ‫Readme: תיעוד של המודול ‫manifest.yaml: מגדיר את סוג ה-builder, התלויות וההגדרה. ‫table_settings.default.yaml: הגדרה של Table settings ‫annotations/: תיאורים ברמת העמודה והשדה. ‫definitions/: קובצי מקור של Dataform SQLX או JS.
src/data_modules/custom_namespace/includes/	JavaScript helpers כל קובצי ה-JavaScript שמוצבים כאן נארזים אוטומטית וזמינים למודלים של Dataform במהלך ההידור (compilation) בנתיב של מרחב השמות (לדוגמה, includes/custom_namespace/).
src/data_modules/custom_namespace/common/	כלים משותפים במרחב השמות כלים מותאמים אישית לבנייה, לפריסה ולמטרות אחרות, שמוגבלים למרחב השמות.

הגדרת מרחב שמות בהתאמה אישית

מרחב שמות חדש: custom_namespace אפשר להגדיר אותו על ידי הרחבת הקטע המתאים בקובץ config.yaml, יצירת ספרייה חדשה ב-src/data_modules/ והוספת נכסי קוד המודול החדש.

כדי שהקומפיילר של Google Cloud Cortex Framework יזהה את מרחב השמות והמודולים המותאמים אישית שלכם, אתם צריכים לרשום אותם בקובץ ההגדרות הגלובלי (לדוגמה, config/config.yaml).

שלב א': רישום מרחב השמות

בקטע data.namespaces block, מוסיפים את המטא-נתונים של מרחב השמות:

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name:  custom_namespace    # <-- Name of custom namespace
      path:  custom_namespace/  # <-- Folder name that is used for custom namespace, points to subdirectory of 'src/data_modules/'

שלב ב': הגדרת מודולים בהתאמה אישית

רושמים את המודולים המותאמים אישית בקטע data.modules.foundation או data.modules.product. בשדה type צריך להשתמש בפורמט custom_namespace.module_type עם נקודות בין המספרים:

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_data_foundation_module_type
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/table_settings.default.yaml"
        # Custom table settings file, relative to 'config/' directory
        tableSettings: "custom_namespace/data_foundation/data_foundation_module_type/table_settings.yaml"
        
    product:
      - moduleId: custom_namespace_data_product_module_type
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_data_foundation_module_type # References an existing foundation moduleId 
        dataTargetId: product_target
        # Custom table settings file, relative to 'config/' directory
        # tableSettings: "custom_namespace/data_product/data_product_module_type/table_settings.yaml"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_product/data_product_module_type/table_settings.default.yaml"

הערה: הערכים data_foundation_module_type ו-data_product_module_type הם מחרוזות שעברו ניקוי טכני של שם המודול (אותיות קטנות, והתווים המיוחדים והרווחים הוחלפו בקווים תחתונים). הערך חייב להיות זהה לערך המאפיין type: בקובץ src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/manifest.yaml או src/data_modules/custom_namespace/data_product/data_product_module_type/manifest.yaml.

קוד משותף של מרחב שמות בהתאמה אישית

מרחב השמות המותאם אישית תומך בשיתוף ארטיפקטים של קוד בין המודולים שלו. סוגי הארטיפקטים הנתמכים הם:

• ‫includes – מכיל עזרים של JavaScript שיהיו זמינים לארטיפקטים של Dataform. אפשר למקם אותם בתיקייה: src/data_modules/custom_namespace/includes/.
• ‫builders – כל מחלקות הגנרטורים בהתאמה אישית שיכולות לקמפל את קוד המקור של המודול לארטיפקטים של Dataform. אפשר למקם אותם בsrc/data_modules/custom_namespace/common/.

הסבר על כלים ליצירת אפליקציות ואיך משתמשים בהם

קלאסים של גנרטורים ב-Python שקומפלו את קובצי המקור של המודול לפלט של Dataform. ‫Google Cloud Cortex Framework קומפל מודולים באמצעות רצף גמיש של פתרונות לבנייה בשלוש שכבות:

איור 1. רצף הפתרון של כלי בנייה להרחבת Cortex Framework.

רמה 1: builders גלובליים לגיבוי

המסגרת כוללת כלי בנייה חזקים מאוד שנמצאים ב-src/common/builders/. ה-Builders האלה רשומים באופן גלובלי ואפשר להשתמש בהם בכל מרחב שמות מותאם אישית.

לדוגמה, כדי להשתמש בבוני מוצרי הנתונים הסטנדרטיים של SAP עבור מוצר הנתונים המותאם אישית שלכם, צריך להפנות אל sap_product ב-manifest.yaml:

# src/data_modules/custom_namespace/data_product/data_product_module_type/manifest.yaml
type: data_product_module_type
builder: sap_product     # Automatically resolves to the global SapProductBuilder fallback
dependencies:
  sapModule:
    type: sap
    supportedVersions:
      - ecc
      - s4

רמה 2: כלי בנייה בהיקף של מרחב שמות

אם מודולים במרחב השמות המותאם אישית שלכם דורשים קומפיילר מיוחד, אתם יכולים לרשום builder מותאם אישית למרחב השמות הזה.

1. יוצרים קובץ builder בתיקייה src/data_modules/custom_namespace/common/builders/my_builder.py.

2. מקשטים את מחלקת ה-builder באמצעות @builder_registry.register("my_builder") :

    from common.builders.base import ProductBuilder
    from common.registry import builder_registry
   
    @builder_registry.register("my_builder")
    class MyCustomProductBuilder(ProductBuilder):
        # Implement build logic here...
   

3. אפשר להפנות אליו בmanifest.yaml המוצר באמצעות builder: my_builder.

רמה 3: יוצרים ברמת המוצר הבודד

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

1. פשוט יוצרים קובץ בשם builder.py ישירות בתוך תיקיית מוצר הנתונים (למשל, src/data_modules/custom_namespace/data_product/data_product_module_type/builder.py).

2. מגדירים מחלקת משנה של BaseBuilder או ProductBuilder בתוך המחלקה:

    from common.builders.base import ProductBuilder
   
    class UniqueSalesPerformanceBuilder(ProductBuilder):
        # Implement unique build logic here...
   

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

בשלבים הבאים: יצירת מודול של שכבת בסיס נתונים ויצירת מודול של מוצר נתונים, נסביר איך להוסיף מודולים של נתונים למרחב השמות.

---

• השלב הבא: יצירת מודול של נתוני בסיס
• חזרה לסקירה הכללית