カスタム Namespace の設定

カスタム名前空間は、データ基盤と分析データ プロダクト モジュールをパッケージ化して分離するための論理環境として機能します。専用のカスタム Namespace 内で実行すると、構成オプションとデプロイ オプションを個別に管理できるため、環境の分離が実現します。この分離の主なメリットは、カスタム モジュールをオーバーライドしたり破損させたりするリスクを冒すことなく、Google Cloud Cortex Framework の cortex 名前空間から将来の更新や機能強化をシームレスに取得できることです。専用の名前空間内にカスタム モジュールを作成することを強くおすすめします。

カスタム Namespace のフォルダ構造

Cortex Framework の Namespace フォルダは、カスタム モジュール アーティファクトのパッケージ化と分離に使用されます。カスタム名前空間のフォルダ構造は、次の表で定義されています。

ディレクトリ パス 目的と説明 一般的なサブフォルダ構造
config/ Cortex デプロイ構成（必須）
新しい Namespace を作成するには、config.yaml 内で設定する必要があります。		 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ データ基盤モジュール（省略可）
生データから基盤データセットへの変換。		 
-
src/data_modules/custom_namespace_path/data_product/ データ プロダクトの定義（省略可）
ビジネス ロジックと分析モデルが含まれます。各プロダクトはサブディレクトリ（your_product_name など）に分割され、次の要素で構成されます。
  • Readme: モジュールのドキュメント
  • manifest.yaml: ビルダーのタイプ、依存関係、構成を宣言します。
  • annotations/: 列とフィールド レベルの説明。
  • definitions/: Dataform SQLX または JS ソースファイル。
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ JavaScript ヘルパー（省略可）
ここに配置された JavaScript ファイルは自動的にパッケージ化され、コンパイル中に名前空間パス（includes/custom_namespace/ など）の下で Dataform モデルで使用できるようになります。		 
-
src/data_modules/custom_namespace_path/common/ Namespace 共有ツール（省略可）
Namespace スコープのカスタム ビルダー、デプロイツール、その他のツール。		 
-

カスタム Namespace の構成

新しい名前空間 custom_namespace は、config.yaml ファイルの対応するセクションを拡張し、src/data_modules/ の下に新しいディレクトリを作成して、新しいモジュール コード アセットを追加することで定義できます。

Google Cloud Cortex Framework コンパイラがカスタム Namespace とモジュールを認識できるようにするには、グローバル構成ファイル（config/config.yaml など）に登録する必要があります。

ステップ A: 名前空間を登録する

data.namespaces ブロックの下に、名前空間のメタデータを追加します。

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

ステップ B: カスタム モジュールを構成する

カスタム モジュールを data.modules.foundation または data.modules.product に登録します。type フィールドには、ドット区切りの形式 custom_namespace.module_type を使用します。

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_foundation_module_id
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        tableSettings: "config/custom_namespace_path/data_foundation/sap/table_settings.yaml"

    product:
      - moduleId: custom_namespace_data_product_id
        type: custom_namespace.data_product_id  # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: erp_ecc            # References an existing foundation moduleId
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_id/table_settings.yaml"

カスタム Namespace の共有コード

カスタム名前空間は、モジュール間のコード アーティファクトの共有をサポートしています。サポートされているアーティファクト タイプは次のとおりです。

  • includes - Dataform アーティファクトで使用可能になる JavaScript ヘルパーが含まれています。src/data_modules/custom_namespace_path/includes/ フォルダに配置できます。
  • builders - モジュールのソースコードを Dataform アーティファクトにコンパイルできるカスタム ジェネレータ クラス。これらは src/data_modules/custom_namespace_path/common/ に配置できます。

ビルダーの理解と参照

ビルダーは、モジュール ソースファイルを物理的な Dataform 出力にコンパイルする Python ジェネレータ クラスです。Google Cloud Cortex Framework は、柔軟な3 層のビルダー解決シーケンスを使用してモジュールをコンパイルします。

Google Cloud Cortex Framework の拡張性ビルダーの解決シーケンス

図 1. Cortex Framework 拡張機能ビルダーの解決シーケンス。

Tier 1: グローバル フォールバック ビルダー

このフレームワークには、src/common/builders/ にある非常に堅牢なビルダーが含まれています。これらのビルダーはグローバルに登録され、任意のカスタム Namespace で使用できます。

たとえば、カスタム プロダクトに標準の SAP データ プロダクト ビルダーを使用するには、manifest.yaml で sap_product を参照します。

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

Tier 2: Namespace-scoped ビルダー

カスタム名前空間内のモジュールに特殊なコンパイラが必要な場合は、その名前空間のカスタム ビルダーを登録できます。

  1. src/data_modules/custom_namespace_path/common/builders/my_builder.py の下にビルダー ファイルを作成します。

  2. ビルダー クラスに @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...
  1. builder: my_builder を使用して、プロダクトの manifest.yaml で参照します。

Tier 3: 個々のプロダクト レベルのビルダー

一意性の高いパイプラインの場合は、単一のデータ プロダクトに限定してビルダーを定義できます。

  1. データ プロダクト フォルダ（src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py など）内に builder.py という名前のファイルを作成するだけです。

  2. その中で BaseBuilder または ProductBuilder のサブクラスを定義します。

   from common.builders.base import ProductBuilder

   class UniqueSalesPerformanceBuilder(ProductBuilder):
       # Implement unique build logic here...
  1. コンパイラは、登録やデコレータを必要とせずに、このクラスを自動的に動的にインポートして実行します。

カスタム Namespace の例

config/config.yaml ファイルの data.namespaces の下に次のブロックを追加します。

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

次のステップ（データ基盤モジュールの作成とデータ プロダクト モジュールの作成）では、データ モジュールを Namespace に追加する方法について説明します。