Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Deployment 設定

本頁說明 Cortex Framework 的部署設定選項，涵蓋下列領域：

部署設定 (config/config.yaml)：定義全域變數、建構環境和模組對應 (資料基礎和資料產品目標)。
資料表設定 (table_settings.yaml)：模組專屬的效能和結構定義規格，說明如何在 BigQuery 中編譯及符合基本資料表。

本頁面也提供操作指南，逐步說明常見的部署用途和情境。

設定檔：`config/config.yaml`

config/config.yaml 檔案 (通常是從 config/config.yaml.example 範本初始化) 是 Cortex Framework 部署作業的主要設定。設定分為以下結構區塊：

建構環境 (buildEnvironment)：控管建構調度管理層，指定中間中繼資料計算、資料庫驗證和結構定義查詢的計費和執行位置，也就是中央 Google Cloud 專案。
資料 (data)：管理邏輯資料架構。這個區塊會設定資料集位置、命名空間界線、原始擷取來源的連線詳細資料、目的地資料集，並註冊資料模組例項 (foundations、catalogs 和 products)。
部署 (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`	命名空間名稱	-	Cortex Framework 命名空間名稱。例如 `cortex`。
`data.namespaces.path`	命名空間路徑	-	src 和 config 資料夾中使用的子目錄 Cortex Framework 命名空間路徑。例如 `cortex`。

資料：BigQuery 來源和目標資料集

資料集清單會定義架構的輸入原始資料連線點和輸出儲存位置。每個資料集都會註冊對應特定 Google Cloud 專案和 BigQuery 資料集的專屬 ID。

模組會使用資料集的專屬 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	`-`	定義資料集的專屬 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`	特定資料基礎轉換模組執行個體的專屬 ID。
`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」，將資料推送至該清單。
`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 可透過外部 Lakehouse 目錄，從 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	-	特定外部目錄模組執行個體的專屬 ID。
`type`	目錄類型	`lakehouse_delta_share`	目錄類型。支援 `lakehouse_delta_share`。
`bindsNamespaces`	繫結的命名空間	-	這個目錄繫結的邏輯命名空間前置字串清單 (例如 `[sap_bdc]`)。
`connectionSettings.catalogId`	實體目錄 ID	-	實體目錄 ID。通常與模組 ID 相同。
`connectionSettings.projectId`	專案 ID	-	管理目錄連線的專案 ID。 Google Cloud
`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	-	特定轉換模組執行個體的專屬 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`	從目標清單參照「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 中，每個模組 (基礎或產品) 都可以在部署設定檔中指派特定表格設定檔：使用 tableSettings 屬性 config/config.yaml。

設定路徑

自訂設定 (建議)：如要自訂表格行為，請將預設檔案複製到設定目錄，然後修改該檔案，並在 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 有兩種不同的結構定義樣式：

資料基礎樣式：以清單為基礎的對應，定義來源到目標的結構定義關係、CDC (變更資料擷取) 處理方式和 BigQuery 版面配置。請注意，「資料基礎資料表設定」版面配置是來源系統專屬。
資料產品樣式：以地圖為基礎的對應 (字典)，定義如何具體化 (例如以檢視畫面、資料表或遞增資料表的形式) 及最佳化分析檢視畫面或資料表。

這兩種樣式都支援三個根層級區段，可依來源系統版本區隔設定 (主要用於 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 中原始來源資料表的名稱 (不區分大小寫)。

參數	類型	必填	預設 / 範例	說明
`tableName`	`string`	是	`bkpf`	BigQuery 中原始來源資料表的名稱 (不區分大小寫)。
`isCdc`	`boolean`	否	`true`	指出來源資料表是否包含變更資料擷取 (CDC) 記錄。 • `true` (預設)：架構會處理 CDC 記錄 (使用記錄時間戳記和作業旗標)，以重建最新的相符狀態。 • `false`：系統會將資料表視為完整快照進行處理。

isCdc

boolean

否

true

指出來源資料表是否包含變更資料擷取 (CDC) 記錄。

• true (預設)：架構會處理 CDC 記錄 (使用記錄時間戳記和作業旗標)，以重建最新的相符狀態。

• false：系統會將資料表視為完整快照進行處理。

指定目標設定

定義目標資料集中的輸出一致性資料表版面配置。

參數	類型	必填	預設 / 範例	說明
`tableName`	`string`	否	(與來源相同)	要建立的目標已調整一致資料表名稱。如果省略，架構會預設為來源 `tableName`。
`dataformTags`	`array[string]`	否	`[sap, finance]`	Dataform 中附加至已調整動作的中繼資料標記清單。這些是任意字串，不需要預先註冊或在其他設定中定義，可立即用於篩選管道執行作業 (例如使用 `dataform run --tags ...`)。
`bigQueryLabels`	`array[map]`	否	`-`	鍵/值組合清單，代表要套用至目標資料表的 BigQuery 標籤 (例如，鍵：`data_class`，值：`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`	否	`{}`	產品表格項目描述元結構定義區塊，用於設定特定分析資產。
`[table_name].enabled`	`boolean`	否	`true`	控管是否要啟用分析資料表或檢視區塊 (`[table_name]`)，並在建構 Dataform 工作區時納入這些項目。 • `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 標籤 (例如，鍵：`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]`	最多四個資料欄名稱的排序清單，用來對資料表進行分群。限制：欄位必須是英數字元，且只能包含底線。清單中的資料欄順序會決定排序階層。

分區詳細資料

分區程序會根據日期、時間戳記或整數欄位的值，將大型資料表切分成較小的實體區段。這樣一來，當查詢只要求特定日期、月份或 ID 範圍時，BigQuery 就不會掃描整個資料表。

partitionDetails:
  column: budat
  partitionType: time
  timeGrain: day

參數參照

參數	類型	必填	範例	說明
`column`	`string`	是	`budat`	用於對資料表進行分區的資料欄名稱。只能使用英數字元和底線，資料欄類型必須與 `partitionType` 相符。
`partitionType`	`string`	是	`time`	分區策略。允許值： `time`：依時間單位 (Date、Timestamp 或 Datetime 資料欄) 分區。 `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。如要瞭解註解檔案的格式，請參閱資料基礎的擴充性指南。

設定資料基礎模組的多個執行個體

部署相同模組類型的兩個以上獨立管道執行個體 (例如支援多個 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 動作。

Deployment 設定

設定檔：config/config.yaml

建構環境

「資料」專區總覽

資料：BigQuery 位置

資料：Cortex 命名空間

資料：BigQuery 來源和目標資料集

資料：模組

資料：模組：基礎

資料：模組：目錄

資料：模組：產品

部署環境

設定檔：table_settings.yaml

動態依附元件解析

設定路徑

設定樣式

SAP ERP 的資料基礎樣式

YAML 語法範例

參數參照

來源設定

指定目標設定

資料產品樣式

YAML 語法範例

參數參照

進階 BigQuery 設定

叢集詳細資料

參數參照

分區詳細資料

參數參照

範例

1. 自訂資料基礎表格設定範例

2. 自訂資料產品表格設定範例

使用指南

在資料基礎模組中自訂表格範圍

設定資料基礎模組的多個執行個體

設定檔：`config/config.yaml`

設定檔：`table_settings.yaml`