generate-analytics-star-schema

CDS 分析スター スキーマの生成

RAP ビジネスオブジェクトまたはプレーンな DDIC テーブルを基に、CDS 分析モデルを生成します。分析モデルは、キューブビュー（@Analytics.dataCategory: #CUBE）、1 つ以上のディメンションビュー（#DIMENSION）、およびテキストビュー（#TEXT）で構成されるスター スキーマです。

このスキルは、ARC-1（SAP システムへのアクセス）と mcp-sap-docs（ドキュメントとベストプラクティス）を組み合わせ、SAP Joule の「CDS Analytical Model Generation」機能（基本および拡張スコープ）を再現します。基本スコープでは、キューブを生成し、既存のディメンションを再利用します。拡張スコープでは、新しいディメンションも生成し、DDIC テーブル（RAP BO に限定されません）を起点にできます。

前提条件 — まずお読みください

• 分析アノテーションを利用できる SAP_BASIS 7.5x が必要です。 SAPManage(action="probe") で確認します（rap.available）。RAP/CDS が利用できない場合は中止してください。
• 出力は、相互依存する CDS ビューのセット（キューブ → ディメンション → テキスト）です。クロスリファレンスを SAP のアクティベーターが一度の処理で解決できるよう、非アクティブなドラフトとして作成し、まとめてアクティブ化する必要があります。このスキルでは、そのために SAPWrite(action="batch_create", activateAtEnd: true) を使用します。

スマートなデフォルト（黙って適用し、質問しないでください）

設定	デフォルト	理由
オブジェクトタイプ	DDLS	キューブ／ディメンション／テキストはすべて CDS データ定義です
パッケージ	$TMP	迅速なプロトタイピングに適しています。移送可能なパッケージを使う場合は確認してください
アクティブ化	batch_create + activateAtEnd: true	クロスリファレンスを一度の最終処理で解決します
権限	#NOT_REQUIRED（キューブ／ディメンション）	分析インターフェースビューの標準設定です
命名	ZI_<X>_Cube、ZI_<X>_Dim、ZI_<X>_Txt	スタースキーマでの役割が明確です（テンプレートで使われている大文字・小文字に合わせます）

入力

ユーザーは次のいずれかを指定します。

• RAP ビジネスオブジェクトのルートエンティティ／ビヘイビアプール（例：ZBP_R_TRAVEL または ZI_Travel）、または
• DDIC テーブル（例：ZTRAVEL）、または
• ファクトソースとして使う インターフェース CDS ビュー。

任意の指定項目：メジャーにする数値フィールド、ディメンションにするフィールド、対象パッケージ、新しいディメンションビューを生成するか既存のものを再利用するか。

ステップ 1：ソースを特定して読み込む

1a. RAP BO 入力 — バインドされた CDS ルートエンティティを特定する

ユーザーがビヘイビアプールクラス（ZBP_*）を指定した場合、クラスのメタデータを読み込み、バインド先のルートエンティティを特定します。

SAPRead(type="CLAS", name="<ZBP_class>", format="structured")

バインドされたルートエンティティへの参照を探します。次に、その CDS ルートエンティティを読み込みます（次のステップ）。ユーザーがすでに CDS ルートエンティティ／インターフェースビューを指定している場合は、1c に進みます。

1b. DDIC テーブル入力 — テーブル構造を読み込む

SAPRead(type="TABL", name="<table>")

型を含むフィールド一覧を取得します。候補となるキー、ディメンションフィールド（外部キー、特性）、数値メジャーフィールド（金額、数量、件数）を特定します。

1c. CDS ビュー入力 — ソースと要素を読み込む

SAPRead(type="DDLS", name="<view>")
SAPRead(type="DDLS", name="<view>", include="elements")

要素一覧でフィールドを分類します。それぞれについて、次のように判断します。

• メジャー：数値型で加算可能（金額／数量／件数）→ キューブに @Aggregation.default: #SUM を付けて配置します
• ディメンション：切り口として使う特性（地域、顧客、日付）→ 既存のディメンションビューを再利用するか、新しいものを生成します
• 通貨／単位：各金額／数量メジャーに対応付けます

ステップ 2：再利用可能なディメンションを特定する

各ディメンションフィールドについて、新しいものを生成する前に、再利用可能なディメンションビューがすでに存在するかを確認します。

SAPSearch(query="*<dimension_keyword>*", searchType="object", objectType="DDLS")

リリース済みの #DIMENSION ビュー（例：I_Country、I_CalendarDate）が存在する場合は、アソシエーションを通じて再利用します。存在しない場合は、新しい ZI_<X>_DIM を生成します（拡張スコープ）。

ステップ 3：現在のアノテーションを確認する

最新のドキュメントに基づいて生成します。

search("CDS analytical model cube Analytics.dataCategory CUBE dimension representativeKey")
search("ObjectModel.foreignKey.association text association Semantics.text")

要約にはドキュメント ID を記載してください。重要な事実（7.58）：

• キューブ：@Analytics: { dataCategory: #CUBE, internalName: #LOCAL } ＋ @ObjectModel: { supportedCapabilities: [ #ANALYTICAL_PROVIDER ], modelingPattern: #ANALYTICAL_CUBE }
• キューブには 1 つ以上のメジャーが必要です。メジャーには @Aggregation.default: #SUM（または #MIN／#MAX／#AVG）を設定します。@Aggregation.default のない数値フィールドはディメンションとして扱われます。
• キューブからディメンションへのアソシエーションは [1..1] である必要があります。@ObjectModel.foreignKey.association: '_Dim' は、キューブ内のディメンションキー項目に設定します。
• ディメンション：@Analytics.dataCategory: #DIMENSION ＋ @ObjectModel: { representativeKey: '<key>', supportedCapabilities: [ #ANALYTICAL_DIMENSION ], modelingPattern: #ANALYTICAL_DIMENSION }
• テキストビューでは @ObjectModel.dataCategory: #TEXT（ObjectModel. 名前空間です。@Analytics.dataCategory ではありません）＋ @Semantics.text: true ＋ @Semantics.language: true を使用します。

ステップ 4：モデルを作成する

キューブのテンプレート

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Sales Cube'
@Analytics: {
  dataCategory: #CUBE,
  internalName: #LOCAL
}
@ObjectModel: {
  supportedCapabilities: [ #ANALYTICAL_PROVIDER ],
  modelingPattern: #ANALYTICAL_CUBE
}
define view entity ZI_Sales_Cube
  as select from zsales_data
  association [1..1] to ZI_Region_Dim as _Region
    on _Region.RegionId = $projection.RegionId
{
      @ObjectModel.foreignKey.association: '_Region'
  key region_id   as RegionId,
  key calyear     as CalendarYear,

      @Semantics.amount.currencyCode: 'CurrencyCode'
      @Aggregation.default: #SUM
      amount       as SalesAmount,

      currency     as CurrencyCode,

      @Aggregation.default: #SUM
      @EndUserText.label: 'Number of Records'
      abap.int8'1' as RecordCount,

      _Region
}

ディメンションのテンプレート

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Region Dimension'
@Analytics.dataCategory: #DIMENSION
@ObjectModel: {
  representativeKey: 'RegionId',
  supportedCapabilities: [ #ANALYTICAL_DIMENSION ],
  modelingPattern: #ANALYTICAL_DIMENSION
}
define view entity ZI_Region_Dim
  as select from zregion
  association [0..1] to ZI_Region_Txt as _Text
    on _Text.RegionId = $projection.RegionId
{
      @ObjectModel.text.association: '_Text'
  key region_id as RegionId,
      _Text
}

テキストビューのテンプレート

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Region - Text'
@ObjectModel.dataCategory: #TEXT
@ObjectModel.representativeKey: 'RegionId'
define view entity ZI_Region_Txt
  as select from zregion_t
{
  key region_id as RegionId,

      @Semantics.language: true
  key spras     as Language,

      @Semantics.text: true
      regiontext  as RegionName
}

（テキストビューは単独で機能します。アソシエーションを宣言しないため、@ObjectModel.foreignKey.association は設定しません。リンクは一方向です。ディメンションから _Text ＋ @ObjectModel.text.association を介してこのテキストビューに関連付けます。逆方向ではありません。）

構成ルール（作成前に必ず適用してください）：

• キューブには 1 つ以上のメジャー（@Aggregation.default）が必要です。
• 各金額メジャーには @Semantics.amount.currencyCode を設定し、通貨フィールドを射影します。各数量メジャーには @Semantics.quantity.unitOfMeasure を設定し、単位フィールドを射影します。
• キューブからディメンションへの各アソシエーションは [1..1] とし、ディメンションキー項目には @ObjectModel.foreignKey.association を設定します。
• 各ディメンションには representativeKey が必要です。
• テキストビューでは @ObjectModel.dataCategory: #TEXT ＋ @Semantics.text/language を使用します。

ステップ 5：計画をツリーで示してから、一括作成する

書き込みの前に、モデルツリーをユーザーに提示します。

Cube: ZI_Sales_Cube  (from zsales_data)
  Measures: SalesAmount (SUM, currency CurrencyCode), RecordCount (SUM)
  Dimensions:
    ZI_Region_Dim (new) → ZI_Region_Txt (new)

確認後、相互参照をまとめて解決できるよう、アクティベーションを保留してすべてのビューを一括作成します。

SAPWrite(action="batch_create", activateAtEnd=true, objects=[
  { type: "DDLS", name: "ZI_Region_Txt",  source: "<text_ddl>",      package: "$TMP" },
  { type: "DDLS", name: "ZI_Region_Dim",  source: "<dimension_ddl>", package: "$TMP" },
  { type: "DDLS", name: "ZI_Sales_Cube",  source: "<cube_ddl>",      package: "$TMP" }
])

古いリリースで activateAtEnd がオブジェクトごとのアクティベーションにフォールバックした場合でも依存関係を解決できるよう、配列は依存関係の順（テキスト → ディメンション → キューブ）に並べます。activateAtEnd: true の場合、ARC-1 は 3 つすべてを非アクティブなドラフトとして書き込み、グラフ全体を対象に最後のアクティベーションを 1 回実行します。

activateAtEnd を指定した batch_create が適用されない場合（古いリリース）は、次の方法に切り替えます。各オブジェクトを SAPWrite(action="create", ...) で作成し、その後、作成したすべてのオブジェクトを対象に SAPActivate(objects=[...]) を 1 回実行します。

ステップ 6：検証する

SAPRead(type="DDLS", name="ZI_Sales_Cube", include="elements")

キューブが有効であり、ディメンションのアソシエーションとメジャーが解決されていることを確認します。

ステップ 7：クエリレイヤーを提案する

キューブは基盤です。エンドユーザーが利用するのはクエリです。次のように提案してください。

「このキューブを基に、分析クエリ（KPI を利用するためのビュー）を生成しましょうか？ → generate-cds-analytical-query」

エラー処理

エラー	原因	修正方法
キューブにメジャーがない	すべての数値フィールドがディメンションとして扱われている	少なくとも 1 つの数値フィールドに @Aggregation.default: #SUM を追加します
アソシエーションのカーディナリティエラー	キューブからディメンションへのアソシエーションが [1..1] ではない	カーディナリティを [1..1] に変更します
foreignKey.association の配置	アノテーションがキー項目ではなくアソシエーションに設定されている	キューブ内のディメンションキー項目に移動します
テキストビューが拒否される	#TEXT に @ObjectModel.dataCategory ではなく @Analytics.dataCategory を使用している	テキストビューでは ObjectModel 名前空間を使用します
相互参照が未解決	関連オブジェクトが作成される前に、各オブジェクトを個別にアクティベートした	activateAtEnd: true を指定した batch_create を使用します
代表キーがない	ディメンションに representativeKey がない	@ObjectModel.representativeKey を追加します

メモ

• 基本スコープと拡張スコープ： 基本では既存のディメンションを再利用します（ステップ 2 でリリース済みの #DIMENSION ビューを検索します）。拡張では、新しい ZI_*_DIM と ZI_*_TXT も生成し、ファクトソースとして DDIC テーブルを受け入れます（ステップ 1b）。
• このスキルはモデルを構築します。利用可能なクエリの作成は別のステップです（generate-cds-analytical-query）。
• 分析ではなく、トランザクション用の RAP サービスには、generate-rap-service を使用します。
• SAP 標準のディメンションがある場合（I_CalendarDate、I_Country、I_Currency）は、再生成せずに再利用します（ステップ 2 の SAPSearch）。