デプロイ構成

このページでは、次の領域における Cortex Framework のデプロイ構成オプションについて説明します。

  • デプロイ構成（config/config.yaml）: グローバル変数、ビルド環境、モジュール マッピング（データ基盤とデータ プロダクトのターゲット）を定義します。
  • テーブル構成（table_settings.yaml）: モジュール固有のパフォーマンスとスキーマの仕様。BigQuery でベーステーブルがコンパイルされ、適合される方法を概説します。

このページでは、一般的なデプロイのユースケースとシナリオの手順ガイドも提供しています。

構成ファイル: config/config.yaml

config/config.yaml ファイル（通常は config/config.yaml.example テンプレートから初期化）は、Cortex Framework デプロイのメイン構成として機能します。構成は次の構造ブロックに分かれています。

  1. ビルド環境（buildEnvironment）: ビルド オーケストレーション レイヤを制御し、中間メタデータの計算、データベースの検証、スキーマのルックアップが課金および実行される中央の Google Cloud プロジェクトを指定します。
  2. データ（data）: 論理データ アーキテクチャを管理します。このブロックは、データセットのロケーション、名前空間の境界、未加工の取り込みソースの接続の詳細、宛先データセットを構成し、データ モジュール インスタンス（foundations、catalogs、products）を登録します。
  3. デプロイ（deployment）: 物理ターゲット システムのデプロイを構成します。コンパイルされた SQLX/JS 変換パイプラインがデプロイされる Dataform リポジトリの詳細（プロジェクト ID、ロケーション、リポジトリ名、開発ワークスペース）を指定します。

以降のセクションでは、各ブロックの詳細な内訳について説明します。

ビルド環境

ビルド環境プロジェクトは、DD03L を読み取る BigQuery ジョブなどのビルド アクションに対して課金されるプロジェクトです。

buildEnvironment:
  buildProjectId: YOUR_BUILD_PROJECT_ID

次の表に、ビルド環境パラメータを示します。

パラメータ 意味 デフォルト値 説明
buildEnvironment.buildProjectId ビルド プロジェクト ID YOUR_BUILD_PROJECT_ID Google Cloud : ビルド オペレーションが実行されるプロジェクト ID。

[データ] セクションの概要

構成ファイルの data: セクションでは、データソース、ターゲット、データ基盤とデータ プロダクトの特定のモジュールを定義します。一般的な構造は次のとおりです。

data:
   # Geographic location for BigQuery datasets (for example: US, EU, us-central1)
   # For full list see: https://docs.cloud.google.com/cortex/docs/supported-locations
  bigQueryLocation: US
  # List of namespaces for data foundation and product modules.
  namespaces:
    - name: cortex
      path: ../src/data_modules/cortex
  # List of datasets mapping.
  datasets:
    - ...

  # Configuration for data foundation, data product, and external catalog modules.
  modules:
    # List of foundation modules.
    foundations:
    - ... 
    # List of external catalog modules.
    catalogs:
    - ...
    # List of data product modules.
    products:
    - ...

データ: BigQuery のロケーション

BigQuery のソース データセットとターゲット データセットのロケーションを定義します。

パラメータ 意味 デフォルト値 説明
data.bigQueryLocation BigQuery のロケーション US BigQuery データセットのロケーション（US、us-central1、europe-west1 など）。

データ: Cortex 名前空間

Cortex Framework 名前空間を定義します。

パラメータ 意味 デフォルト値 説明
data.namespaces.name Namespace の名前 - Cortex Framework の Namespace 名。例: cortex
data.namespaces.path 名前空間パス - src フォルダと config フォルダ内で使用されるサブディレクトリの Cortex Framework Namespace パス。例: cortex

データ: BigQuery のソースとターゲットのデータセット

データセットのリストは、フレームワークのインバウンドの未加工データ接続ポイントとアウトバウンドの保存場所を定義します。各データセットは、特定の Google Cloud プロジェクトと BigQuery データセットにマッピングされた一意の識別子を登録します。

データセットは、固有の ID を使用してモジュールから参照されます。

# Dataset mapping
datasets:
  - id: sap_raw
    projectId: YOUR_SOURCE_PROJECT_ID
    datasetId: cortex_sap_raw
  - id: sap_foundation
    projectId: YOUR_TARGET_PROJECT_ID
    datasetId: cortex7_sap_data_foundation

次の表に、データセット マッピング パラメータを示します。

パラメータ 意味 デフォルト値 説明
data.datasets.id データセット ID - データセットの一意の識別子（sap_raw や sap_foundation など）を定義します。
data.datasets.projectId プロジェクト ID - データセットをホストしている Google Cloud プロジェクト ID を参照します。
data.datasets.datasetId BigQuery データセット ID - 実際の BigQuery データセット名を参照します。

データ: モジュール

モジュールは、Dataform データ パイプラインの構造とコンポーネントを定義します。

データ: モジュール: 基盤

このセクションでは、未加工レイヤのデータを処理して、ソースデータの標準化された最新のレコード表現にするデータ基盤レイヤ モジュールを構成します。ソースが最新のレコードのビューを直接提供する場合、またはそのような変換がソースシステムのコネクタによって実行される場合、モジュールは外部データ基盤ソースとして構成できます。

modules:
  # List of foundation modules.
  foundations:
    # Unique identifier for the module instance.
    - moduleId: erp
      # Path of the module format: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap}, for example, cortex.sap.foundations.sap.
      modulePath: cortex.sap.foundations.sap
      # Reference to the source dataset ID.
      dataSourceId: sap_raw
      # Reference to the target dataset ID.
      dataTargetId: sap_foundation
      # Module-specific configuration settings.
      moduleSettings:
        # SAP version (for example, ecc, s4).
        sapVersion: ecc
        # SAP client number.
        mandt: "100"
      # Whether the module is enabled.
      enabled: true
      # Whether the foundation is external (does not create target dataset).
      external: false
      # Custom table settings file, relative to 'config/' file directory
      # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml' (e.g. 'cortex/sap/foundations/sap/table_settings.yaml')
      # Default path: '../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'
      tableSettings: "custom_table_settings.yaml"

次の表に、modules.foundations 構成のデータ基盤モジュールのパラメータを示します。

パラメータ 意味 デフォルト値 説明
moduleId モジュール ID erp 特定のデータ基盤変換モジュール インスタンスの一意の識別子。
modulePath モジュール・パス cortex.sap.foundations.sap 適用されたモジュール、ビジネス ロジック、またはテンプレートの名前空間パスを定義します。形式: {namespace}.{systemtype:sap}.{module_type:foundations}.{subsystemtype:sap}（例: cortex.sap.foundations.sap）。
dataSourceId ソース リンク sap_raw data.datasets リストの「id」を参照して、データを取得します。
dataTargetId ターゲット リンク sap_foundation data.datasets リストの「id」を参照して、データを push します。
moduleSettings.sapVersion SAP システムのバージョン ecc SAP データソースにのみ適用されます。ecc（ECC）または s4（S/4HANA）システムのソース固有のロジックを決定します。
moduleSettings.mandt SAP クライアント（Mandant） 100 SAP データソースにのみ適用されます。データ行のフィルタリングに使用される 3 桁の SAP クライアント ID。
enabled モジュールの有効化 true モジュールが有効かどうかを指定します。
external 外部基盤 false 基盤が外部にあるかどうかを指定します（ターゲット データセットは作成されません）。
tableSettings テーブルの設定 src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml この構成ファイルに対するカスタムのテーブル設定構成ファイルのパス。
推奨パス: `config/` ディレクトリからの相対パス: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
デフォルト パス: '../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml'

データ: モジュール: カタログ

外部レイクハウス カタログを使用すると、Cortex Framework は BigLake Delta Sharing カタログと共有から外部テーブルを取り込み、物理マニフェストなしで共有できます。

modules:
  # List of external catalog modules.
  catalogs:
    # Unique identifier for the catalog.
    - id: sap_bdc_catalog
      # Type of the catalog.
      type: lakehouse_delta_share
      # Logical namespace prefixes bound by this catalog.
      bindsNamespaces: [sap_bdc]
      # Connection settings for the catalog.
      connectionSettings:
        # Unique identifier for the catalog.
        catalogId: sap_bdc_catalog
        # Unique identifier for the project hosting the catalog.
        projectId: sap_bdc_delta_share
        # Geographic region location for the catalog.
        location: europe-west3
        # List of shares to import.
        shares:
          - shareId: customer_v1_he2_100_p8123
          - shareId: salesorder_v1_he2_100_p8124
      # Whether the catalog is enabled.
      # enabled: true

次の表に、外部カタログの構成パラメータを示します。

パラメータ 意味 デフォルト値 説明
id カタログ ID - 特定の外部カタログ モジュール インスタンスの一意の識別子。
type カタログのタイプ lakehouse_delta_share カタログのタイプ。lakehouse_delta_share をサポートします。
bindsNamespaces バインドされた Namespace - このカタログによってバインドされる論理名前空間の接頭辞のリスト（例: [sap_bdc]）。
connectionSettings.catalogId 物理カタログ ID - 物理カタログ ID。通常はモジュール ID と同じです。
connectionSettings.projectId プロジェクト ID - カタログ接続が管理されている Google Cloud プロジェクト ID。
connectionSettings.location ロケーション - カタログの地理的リージョンの場所。
connectionSettings.shares 共有 - インポートする Delta Sharing の共有のリスト。各共有には shareId が含まれている必要があります。
enabled カタログの有効化 true カタログが有効かどうかを指定します。

データ: モジュール: 商品

データ プロダクト モジュールは、特定のビジネス ユースケースを満たす分析情報に未加工データを変換するために必要な集計、計算、結合を定義します。

データ プロダクトの構成では、一意の ID の設定、依存関係の定義、結果が保存されるデータ基盤モジュールとターゲット データセットの参照を行うことができます。

指定されたデータプロダクトの詳細な構成は、キー tableSettings で参照されるファイル内で定義されます。

modules:
  # List of data product modules.
  products:
    # Unique identifier for the data product instance.
    - moduleId: sap_purchasing_organizational_structure
      # Path of the data product (namespaced).
      modulePath: cortex.sap.products.purchasing_organizational_structure
      # Map of module dependencies.
      dependencyBindings:
        sapModule: erp
      # Reference to the target dataset ID.
      dataTargetId: product_target
      # Whether the module is enabled.
      enabled: true
      # Whether this data product is synced to the Knowledge Catalog. Defaults to true.
      syncToKc: true

      # Custom table settings file, relative to 'config/' file directory
      # Recommended path: '{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml'
      # If omitted, defaults to '../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml'
      # tableSettings: "custom_dataproduct_table_settings.yaml"

次の表に、modules.products 構成のデータ プロダクト モジュール パラメータを示します。

パラメータ 意味 デフォルト値 説明
moduleId モジュール ID - 特定の変換モジュール インスタンスの一意の識別子。
modulePath モジュール・パス - 適用されるモジュール、ビジネス ロジック、テンプレートへの名前空間パスを定義します。形式は {namespace}.{systemtype:sap}.{module_type:products}.{dataproduct_name} です。たとえば、cortex.sap.products.purchasing_organizational_structure（src/data_modules/{namespace_dir}/{system_type}/products/{product_name} フォルダで定義）。
dataTargetId ターゲット リンク product_target データを push するターゲット リストの「id」を参照します。
dependencyBindings アップストリームの依存関係 sapModule: erp モジュールの依存関係を満たすためのマッピングを指定します。たとえば、sapModule を erp にマッピングします。
enabled モジュールの有効化 true モジュールが有効かどうかを指定します。
syncToKc Knowledge Catalog の同期 true このデータ プロダクトが Knowledge Catalog に同期されているかどうか。
tableSettings テーブルの設定 src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml この構成ファイルに対するカスタムのテーブル設定構成ファイルのパス。
推奨パス: `config/` ディレクトリからの相対パス: '{namespace_dir}/{system_type}/products/{product_name}/table_settings.yaml'
デフォルト パス: '../src/data_modules/{namespace_dir}/{system_type}/products/{product_name}/table_settings.default.yaml'

デプロイ環境

Cortex Framework は、Dataform を使用して BigQuery 内の SQL 変換をオーケストレートします。deployment: ブロックは、リポジトリ プロジェクト、ロケーション、リポジトリ名、Dataform ワークスペース名など、データ パイプラインの実行を担当する Dataform 構成を定義します。

deployment:
  targets:
    - type: dataform
      enabled: true
      targetSettings:
        repositoryProjectId: YOUR_REPO_PROJECT_ID
        repositoryRegion: us-central1
        repositoryName: cortex-repository
        workspaceName: dev
        # serviceAccount: "example@example.com"

次の表に、デプロイ ターゲットのロケーション パラメータ（deployment.targets:）を示します。

パラメータ 意味 デフォルト値 説明
type デプロイタイプ dataform デプロイ ターゲットのタイプ。
enabled 有効/ 無効 true 指定されたデプロイ ターゲットが有効か無効かを指定します。
targetSettings.repositoryProjectId リポジトリ プロジェクト ID YOUR_REPO_PROJECT_ID Dataform リポジトリが管理されている Google Cloud プロジェクト ID。
targetSettings.repositoryRegion リポジトリ リージョン us-central1 Dataform リポジトリの Google Cloud リージョン（us-central1 や europe-west1 など）。
targetSettings.repositoryName リポジトリ名 cortex-repository Dataform リポジトリの固有の名前。
targetSettings.workspaceName ワークスペース名 dev デプロイ サイクルで使用される特定の Dataform ワークスペース。
targetSettings.serviceAccount サービス アカウントのメールアドレス - Dataform リポジトリの実行に使用されるデフォルトのサービス アカウントのメールアドレス。

構成ファイル: table_settings.yaml

このガイドでは、table_settings.yaml ファイルを使用して Google Cloud Cortex Framework のデータ基盤テーブルとデータ プロダクト テーブルを構成する方法について説明します。

データ モジュール固有の table_settings.yaml ファイルは、元となるソーステーブルがどのように準拠し、分析データモデルが BigQuery 内でどのように具体化されるかを制御します。このファイルを使用して、タグ、マテリアライズ戦略、パーティショニングやクラスタリングなどの高度な BigQuery パフォーマンス機能を構成できます。

動的依存関係の解決

デフォルトでは、Cortex Framework は、有効なデータ プロダクトの依存関係として必要な基盤テーブルのみをデプロイしてコンパイルすることで、デプロイ フットプリントと実行時間を最適化します。table_settings.yaml で構成されたテーブルに、依存するアクティブなダウンストリーム データ プロダクトがない場合、そのテーブルはデプロイから除外されます。

この最適化をオーバーライドして基盤テーブルのデプロイを強制するには、deployAlways 属性を true に設定します（データ基盤スタイル パラメータのリファレンスをご覧ください）。

Google Cloud Cortex Framework では、各モジュール（基盤またはプロダクト）に、デプロイ構成ファイル（config/config.yaml）で tableSettings プロパティを使用して特定のテーブル設定ファイルを割り当てることができます。

構成パス

  • カスタム設定（推奨）: テーブルの動作をカスタマイズするには、デフォルトのファイルを構成ディレクトリにコピーして変更し、config/config.yaml でそのパスを参照します。推奨されるパス（config/ ディレクトリに対する相対パス）は次のとおりです。
    • 基盤モジュール: namespace_dir/system_type/foundations/system_sub_type/custom_table_settings.yaml（例: config/cortex/sap/foundations/sap/table_settings.yaml）
    • プロダクト モジュール: namespace_dir/system_type/products/product_name/custom_table_settings.yaml（config/cortex/sap/products/accounting_documents/table_settings.yaml など）
  • デフォルトのフォールバック: tableSettings が省略されている場合、フレームワークは自動的に次のフォールバックを行います。
    • 基盤モジュール: ../src/data_modules/namespace_dir/system_type/foundations/system_sub_type/table_settings.default.yaml
    • プロダクト モジュール: ../src/data_modules/namespace_dir/system_type/products/product_name/table_settings.default.yaml

構成スタイル

モジュールのカテゴリに応じて、table_settings.yaml には 2 つの異なるスキーマ スタイルがあります。

  1. データ基盤スタイル: ソースからターゲットへのスキーマ関係、CDC（変更データ キャプチャ）処理、BigQuery レイアウトを定義するリストベースのマッピング。データ基盤テーブル設定レイアウトはソースシステム固有であることに注意してください。

  2. データ プロダクトのスタイル: 分析ビューまたはテーブルがマテリアライズ（ビュー、テーブル、増分テーブルなど）され、最適化される方法を定義するマップベースのマッピング（辞書）。

どちらのスタイルも、ソースシステム バージョン別に構成を分離する 3 つのルートレベル セクションをサポートしています（主に SAP Data Foundation と SAP 依存プロダクトで使用されます）。

  • ecc: SAP ECC ソースシステムをデプロイするときにのみ適用される設定。
  • s4: SAP S/4HANA ソースシステムのデプロイ時にのみ適用される設定。
  • common: SAP バージョンに関係なく適用される設定（準拠設定またはユニバーサル設定に使用）。

SAP ERP のデータ基盤スタイル

SAP ERP ソースシステムのデータ基盤モジュールでは、table_settings.yaml ファイルは ecc、s4、common キーの下のテーブル項目のリストとして構造化されています。各項目は、未加工のソーステーブルを準拠したターゲット テーブルにマッピングし、その BigQuery 設定を構成します。

YAML 構文の例

common:
  - source:
      tableName: bkpf
      isCdc: true
    target:
      tableName: bkpf # Optional: defaults to source tableName if omitted
      bigQueryLabels:
        - key: data_class
          value: transactional
        - key: line_of_business
          value: finance
      dataformTags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day
    deployAlways: false

パラメータ リファレンス

パラメータ タイプ 必須 デフォルト / 例 説明
[].source object ○ [] データ基盤のインバウンド ソースシステム（例: `sap_raw`）のテーブルについて説明します。ソース設定をご覧ください。
[].target object ○ [] データ基盤データセット（`sap_data_foundation` など）のターゲット テーブルについて説明します。ターゲット設定をご覧ください。
ecc | s4 | common string × [] ソースシステムのバージョンまたは言語。
[].deployAlways boolean × false true の場合、最適化ルールでスキップされる可能性がある場合でも、テーブルは常にデプロイされてビルドされます。動的依存関係の解決もご覧ください。
ソース設定

未加工のインバウンド テーブルの特性を定義します。

パラメータ タイプ 必須 デフォルト / 例 説明
tableName string はい bkpf BigQuery の未加工のソーステーブルの名前（大文字と小文字は区別されません）。
isCdc boolean × true ソーステーブルに変更データ キャプチャ（CDC）ログが含まれているかどうかを示します。

• true（デフォルト）: フレームワークは、CDC ログ（レコードのタイムスタンプとオペレーション フラグを使用）を処理して、最新の準拠状態を再構築します。

• false: テーブルは完全スナップショットとして処理されます。
ターゲット設定

ターゲット データセットの出力準拠テーブル レイアウトを定義します。

パラメータ タイプ 必須 デフォルト / 例 説明
tableName string × *(ソースと同じ)* 作成するターゲットの準拠テーブルの名前。省略した場合、フレームワークはデフォルトでソース tableName になります。
dataformTags array[string] × [sap, finance] Dataform の準拠アクションに適用されたメタデータタグのリスト。これらは任意の文字列であり、事前登録や他の構成での定義は必要ありません。これらは、パイプライン実行のフィルタリング（dataform run --tags ... の使用など）にすぐに使用できます。
bigQueryLabels array[map] × - ターゲット テーブルに適用する BigQuery ラベルを表す Key-Value ペアのリスト（例: key: data_class、value: transactional）。
clusterDetails map × — 省略可。BigQuery クラスタリングの構成。クラスタリングの詳細をご覧ください。
partitionDetails map × — 省略可。BigQuery のパーティショニング構成。パーティショニングの詳細をご覧ください。

データ プロダクトのスタイル

データ プロダクト モジュールでは、table_settings.yaml ファイル（ProductTableSettings ブロック）は ecc、s4、common のルートキーの下の辞書（マップ）として構造化されます。このディクショナリのキーは、ターゲットの分析テーブルまたはビューの名前（大文字と小文字は区別されません）を表します。各値は、マテリアライズ戦略、テーブルの有効化、パフォーマンスの最適化を定義する Product TableItem（ProductTableItem）構成ブロックです。

YAML 構文の例

common:
  currency_conversion:
    materializationType: table
    bigQueryLabels:
      - key: data_class
        value: transactional
      - key: line_of_business
        value: finance
    dataformTags: [sap, dataproduct, common]
    enabled: true
    retentionDays: 365 # Custom parameter passed to Dataform context
s4:
  customers:
    materializationType: incremental
    bigQueryLabels:
      - key: data_class
        value: master
    dataformTags: [sap, dataproduct, masterdata]
    enabled: true
    clusterDetails:
      columns: [mandt, ktokd]
    partitionDetails:
      column: erdat
      partitionType: time
      timeGrain: day

パラメータ リファレンス

パラメータ タイプ 必須 デフォルト / 例 説明
ecc | s4 | common map × {} ターゲット分析アセット（テーブルまたはビュー）とその ProductTableItem 構成記述子のマップ。
[table_name] map × {} 特定の分析アセットを構成する Product Table Item 記述子スキーマ ブロック。
[table_name].enabled boolean × true Dataform ワークスペースの構築時に、分析テーブルまたはビュー（[table_name]）が有効で、含まれているかどうかを制御します。

• true（デフォルト）: テーブル定義が処理され、table_config プロパティで拡充され、Dataform 出力ディレクトリにコピーされます。

• false: ビルド中にテーブル定義がスキップされます（SapProductBuilder ログに記録され、省略されます）。テーブルまたはビューはコピーされず、Dataform に組み込まれません。これにより、ソース定義ファイルを削除することなく、デプロイから効果的に除外されます。
[table_name].materializationType string × incremental BigQuery で分析アセットがどのように構築されるか。

使用できる値:

  • incremental（デフォルト）: 前回実行以降に新規または更新されたレコードのみを処理します。コストを削減するために、大規模なトランザクション データセットにおすすめします。
  • table: 実行のたびに、テーブルを最初から完全に再構築します。
  • view: アセットを BigQuery SQL ビュー（仮想テーブル）としてデプロイします。
[table_name].dataformTags array[string] × [sap, dataproduct] Dataform の分析アセットに付加されたメタデータタグ。これらは任意の文字列であり、事前登録する必要はありません。選択的なパイプライン実行（dataform run --tags ... の使用など）にすぐに使用できます。
[table_name].bigQueryLabels array[map] × - ターゲット分析アセットに適用する BigQuery ラベルを表す Key-Value ペアのリスト（例: キー: data_class、値: master）。
[table_name].clusterDetails map × — 省略可。BigQuery クラスタリングの構成。クラスタリングの詳細をご覧ください。
[table_name].partitionDetails map × — 省略可。BigQuery のパーティショニング構成。パーティショニングの詳細をご覧ください。

BigQuery の高度な構成

どちらのスタイルも、クラスタリングとパーティショニングを使用して BigQuery のストレージとクエリのパフォーマンスを最適化する同じ構造を共有しています。

クラスタリングの詳細

クラスタリングでは、特定の列の値に基づいてデータが配置されます。BigQuery は、これらの列を使用して各ストレージ ブロック内のデータを並べ替えます。これにより、これらの列でフィルタリング（WHERE）または結合（JOIN）するクエリが大幅に高速化されます。

clusterDetails:
  columns: [bukrs, gjahr]
パラメータ リファレンス
パラメータ タイプ 必須 例 説明
columns array[string] はい [bukrs, gjahr] テーブルをクラスタ化する最大 4 つの列名の順序付きリスト。

制約: 列は英数字で、アンダースコアのみを含める必要があります。リスト内の列の順序によって、並べ替えの階層が決まります。

パーティショニングの詳細

パーティショニングでは、日付列、タイムスタンプ列、または整数列の値に基づいて、大きなテーブルを小さな物理セグメントに分割します。これにより、クエリで特定の日付、月、ID の範囲のみがリクエストされた場合に、BigQuery がテーブル全体をスキャンすることを防ぐことができます。

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day
パラメータ リファレンス
パラメータ タイプ 必須 例 説明
column string はい budat テーブルのパーティショニングに使用される列名。英数字とアンダースコアのみを使用してください。列の型は partitionType と一致している必要があります。
partitionType string はい time パーティショニング戦略。

使用できる値:

  • time: 時間単位（Date、Timestamp、Datetime 列）で分割します。
  • DATE: Date 列で明示的にパーティション分割します。
  • integer: 整数範囲でパーティション分割します。
timeGrain string × day partitionType が time または DATE の場合は必須です。時間パーティションの粒度を定義します。

使用できる値: hour、day、month、year（大文字と小文字は区別されません）。
rangeStart integer × 1 partitionType が integer の場合は必須。最初のパーティションの開始値（この値を含む）。
rangeEnd integer × 1000 partitionType が integer の場合は必須。最後のパーティションの終了値（この値を含まない）。
rangeInterval integer × 10 partitionType が integer の場合は必須。各パーティション間隔の幅。

例

次の例は、データ基盤モジュールとデータ プロダクト モジュールの両方の構成テンプレートを示しています。ターゲット テーブルのカスタマイズ方法、BigQuery でのストレージ レイアウトの最適化方法、マテリアライズ タイプの設定方法について説明します。

1. カスタム データ基盤テーブルの設定の例

この例では、標準データテーブルとともに、クラスタ化されたパーティション分割されたトランザクション テーブル（bseg や ekbe など）を含む基盤レイヤを構成する方法を示します。

# ==============================================================================
# S/4HANA-Specific Tables
# ==============================================================================
s4:
  # ACDOCA is a massive table in S/4HANA; clustering is vital
  - source:
      tableName: acdoca
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, s4, finance, transactional, hourly]
      clusterDetails:
        columns: [rclnt, rbukrs, gjahr]

# ==============================================================================
# ECC-Specific Tables
# ==============================================================================
ecc:
  - source:
      tableName: faglflexa
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, ecc, finance, transactional, hourly]

# ==============================================================================
# Common Tables (ECC & S/4HANA)
# ==============================================================================
common:
  # Financial document header (partitioned by posting date)
  - source:
      tableName: bkpf
      isCdc: true
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, common, finance, hourly]
      clusterDetails:
        columns: [bukrs, gjahr]
      partitionDetails:
        column: budat
        partitionType: time
        timeGrain: day

  # Purchasing document items (partitioned by creation date)
  - source:
      tableName: ekpo
    target:
      bigQueryLabels:
        - key: data_class
          value: transactional
      dataformTags: [sap, common, logistics, purchasing, hourly]
      clusterDetails:
        columns: [mandt, ebeln]
      partitionDetails:
        column: aedat
        partitionType: time
        timeGrain: month

  # Standard master data table (no partitioning/clustering needed)
  - source:
      tableName: lfa1
    target:
      bigQueryLabels:
        - key: data_class
          value: master
      dataformTags: [sap, common, masterdata, vendor, daily]

2. カスタム データ プロダクト テーブル設定の例

この例では、ダウンストリームの分析データ プロダクトのマテリアライズ タイプを構成する方法を示します。ビルドのパフォーマンスを最適化して費用を節約するために、トランザクション sales_documents を増分として設定します。一方、customers などの非トランザクション データテーブルは標準テーブルとしてビルドされます。

# settings applied for both ECC and S/4HANA pipelines
common:
  # Transactional data product - incremental build
  sales_documents:
    materializationType: incremental
    bigQueryLabels:
      - key: data_class
        value: transactional
    dataformTags: [sap, dataproduct, sales, transactional]
    clusterDetails:
      columns: [vkorg, vbeln]
    partitionDetails:
      column: audat
      partitionType: time
      timeGrain: day

  # Master data product - full table rebuild
  customers:
    materializationType: table
    bigQueryLabels:
      - key: data_class
        value: master
    dataformTags: [sap, dataproduct, masterdata]
    clusterDetails:
      columns: [mandt, ktokd]

  # Aggregated reporting view - virtual view
  sales_performance_summary:
    materializationType: view
    bigQueryLabels:
      - key: data_class
        value: transactional
    dataformTags: [sap, dataproduct, sales, reporting]

入門ガイド

このセクションでは、一般的な構成タスクとカスタム デプロイ シナリオの手順ガイドを提供します。

データ基盤モジュールでテーブル スコープをカスタマイズする

新しいモジュールを作成したり、個別のパイプライン インスタンスを実行したりせずに、既存のデータ基盤モジュール内のテーブルを追加または削除するには:

  • デフォルトの table_settings.default.yaml 構成をワークスペース構成ディレクトリ（config/cortex/sap/foundations/sap/custom_table_settings.yaml など）にコピーします。
  • 新しいファイルで、必要に応じて ecc、s4、common キーの下にカスタム テーブルを追加するか、使用されていない標準テーブルを削除します。
common:
  - source:
      tableName: custom_table_name
    target:
      dataformTags: [custom_tag]
  • config/config.yaml を更新して、モジュールの tableSettings プロパティでカスタム テーブル設定のパスを参照します。
data:
  modules:
    foundations:
      - moduleId: erp
        modulePath: cortex.sap.foundations.sap
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
        tableSettings: 'cortex/sap/foundations/sap/custom_table_settings.yaml'
  • アノテーション（テーブルと列の説明）を使用して追加テーブルのテーブル スキーマを拡充するには、使用しているデータ基盤モジュールの名前空間にアノテーション ファイルを作成します。この例では、modulePath: cortex.sap.foundations.sap に基づいて、アノテーション ファイル custom_table_name.yaml を保存するパスは src/data_modules/cortex/sap/foundations/sap/annotations です。アノテーション ファイルの形式については、データ基盤の拡張性ガイドをご覧ください。

データ基盤モジュールの複数のインスタンスを構成する

同じモジュール タイプの 2 つ以上の個別のパイプライン インスタンスをデプロイする（たとえば、複数の SAP インスタンスをサポートして、テーブルのセグメント化、環境の分離、異なるターゲット データセットのターゲット設定を行う場合）。

始める前に:

  • ソーステーブルがソースの元データセットに存在することを確認します。
  • SAP データ基盤モジュールを使用する場合は、メタデータ テーブル DD03L に、取り込むカスタム テーブルの列と記述子情報が含まれていることを確認します。詳細については、SAP ERP の要件をご覧ください。

手順:

  • config/config.yaml ファイルで、data.targets の下にターゲット構成を追加して、各パイプライン インスタンスのターゲット データセットを定義します。
data:
  targets:
    - id: data_foundation_core
      projectId: target_project_id
      datasetId: data_foundation_sap_core
    - id: data_foundation_custom
      projectId: target_project_id
      datasetId: data_foundation_sap_custom
  • data.modules.foundations リストでモジュールの複数のインスタンスを定義します。各インスタンスに一意の moduleId、独自のターゲット データセット ID、必要に応じて tableSettings 構成を指定します。
data:
  modules:
    foundations:
      # Core SAP ERP foundation module instance
      - moduleId: erp_core
        modulePath: cortex.sap.foundations.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_core
        # If omitted, defaults to "../src/data_modules/{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.default.yaml"
        # tableSettings: "../src/data_modules/cortex/sap/foundations/sap/table_settings.default.yaml"
      # Custom tables pipeline instance
      - moduleId: erp_custom
        modulePath: cortex.sap.foundations.sap
        dataSourceId: sap_raw
        dataTargetId: data_foundation_custom
        # Custom table settings file, relative to configuration file directory
        # Recommended path: '{namespace_dir}/{system_type}/foundations/{system_sub_type}/table_settings.yaml'
        tableSettings: "cortex/sap/foundations/sap/custom_datafoundation_table_settings.yaml"
  • カスタム スコープを指定する config/cortex/data_foundation/sap/custom_datafoundation_table_settings.yaml ファイルを作成します。E.g.:
common:
  - source:
      tableName: custom_sap_table_name
    target:
      dataformTags: [sap, s4, hourly]
      clusterDetails:
        columns: [carrid, connid]
      partitionDetails:
        column: fldate
        partitionType: time
        timeGrain: day

  • アノテーション（テーブルと列の説明）を使用して追加テーブルのテーブル スキーマを拡充するには、使用しているデータ基盤モジュールの名前空間にアノテーション ファイルを作成します。この例では、modulePath: cortex.sap.foundations.sap に基づいて、アノテーション ファイル custom_table_name.yaml を保存するパスは src/data_modules/cortex/sap/foundations/sap/annotations です。アノテーション ファイルの形式については、データ基盤の拡張性ガイドをご覧ください。

  • デプロイ スクリプト（uv run cortex-build-and-deploy）を実行して変更を適用し、デプロイ後の手順の説明に沿って Dataform アクションを実行します。