generate-cds-analytical-query

CDS 分析クエリの生成

既存の分析キューブ（@Analytics.dataCategory: #CUBE）を基に、分析用 CDS クエリ（provider contract analytical_query を指定した一時プロジェクションビュー）を生成します。

このスキルは、ARC-1（SAP システムへのアクセス）と mcp-sap-docs（ドキュメントとベストプラクティス）を組み合わせて、SAP Joule の「CDS Analytical Query Generation」機能を再現します。クエリビューは、エンドユーザーが分析クライアント（SAP Analytics Cloud、Analysis for Office、組み込み分析）で利用するビューです。キューブからメジャーとディメンションを選択し、行／列／自由軸に配置します。

前提条件 — 最初にお読みください

• SAP_BASIS 7.57 以降（S/4HANA 2022 以降）が必要です。 provider contract analytical_query 形式は 7.56 以前では使用できません。SAPManage(action="probe") の rap.available が 必要条件ではありますが、十分条件ではない点に注意してください。RAP は 7.54 で提供されたため、true であっても 7.57 以上であることは確認できません。確実に判定するには、リリースを直接確認してください。たとえば、SAPQuery(sql="SELECT release FROM cvers WHERE component = 'SAP_BASIS'") を実行し、>= 757 を必須とします。そうしない場合は、ステップ 5 の有効化時にプロバイダーコントラクトの構文エラーが発生する可能性があるため、その時点で停止してください。
• 既存のキューブが必要です。 このスキルはキューブ上にプロジェクションを作成します。キューブがまだない場合は、先に generate-analytics-star-schema スキルを実行してキューブとディメンションを作成してから、ここに戻ってください。

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

設定	デフォルト	理由
オブジェクトタイプ	DDLS	分析クエリは CDS データ定義です
パッケージ	$TMP	迅速なプロトタイピングが可能です。移送可能なパッケージにする場合は、事前に確認してください
権限	#NOT_ALLOWED	分析クエリでは必須です。他の値を指定すると、有効化に失敗します
軸の配置	ディメンション → #ROWS、メジャー → #COLUMNS	標準的なグリッド配置です。ユーザーが変更できます
ATC	いいえ	ユーザーがコード品質について尋ねた場合にのみ実行します

入力

ユーザーはキューブ名（例：ZI_Sales_Cube）または業務上の説明（「地域別・月別の売上」など）を指定します。必須なのはキューブのみです。ユーザーが説明を指定した場合は、ステップ 1 でキューブを探してください。

任意：

• クエリ名（デフォルト：キューブ名から導出します。例：ZC_SalesQuery。28 文字以下である必要があります。分析エンジンが実行時の名前の先頭に 2C を付加するためです）
• パッケージ（デフォルト：$TMP）
• 公開するメジャー／ディメンション（デフォルト：キューブ内のすべてのメジャーとキーとなるディメンション）

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

1a. キューブを探す（ユーザーが名前ではなく説明を指定した場合）

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

分析キューブに該当する名前／説明の候補を選びます。複数の候補が一致する場合は、それらを一覧表示して確認してください。

1b. キューブのソースを読み込み、キューブであることを確認する

SAPRead(type="DDLS", name="<cube>")

ソースに @Analytics.dataCategory: #CUBE（または @Analytics: { dataCategory: #CUBE ... }）が含まれていることを確認してください。 含まれていない場合は停止してください。分析クエリでプロジェクションできるのは、キューブまたはディメンションのみです。先にキューブを作成するため、generate-analytics-star-schema を提案してください。

1c. 構造化された要素の一覧を取得する

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

これは、キーのマーカーと型を含むすべてのフィールドを返します。各要素を次のように分類してください。

• メジャー — キューブのソース内で @Aggregation.default（例：#SUM）が付与された数値フィールド
• ディメンション — キーフィールドと外部キー関連付けフィールド
• 単位／通貨 — @Semantics.amount.currencyCode／@Semantics.quantity.unitOfMeasure が参照するフィールド

ステップ 2：現在の分析クエリ構文を確認する

アノテーション名を記憶に頼らず、現在のドキュメントに基づいて生成します。

search("CDS analytical query provider contract analytical_query transient view")
search("AnalyticsDetails.query.axis ROWS COLUMNS FREE")

最終的な要約で、参照したドキュメント ID を明記してください。ドキュメントで確認できる重要な事実（7.58）：

• ヘッダー形式：define transient view entity <name> provider contract analytical_query as projection on <cube>
• @AccessControl.authorizationCheck: #NOT_ALLOWED は必須です（クエリは ABAP SQL で読み取れないため、DCL は許可されません。キューブのアクセス制御が適用されます）
• transient キーワードは必須です（HANA SQL ビューは生成されません）
• クエリビューでは、新しいアソシエーションを定義したり、KEY を使用したりできません
• 計算メジャー（算術演算／メジャーに対する CASE）には @Aggregation.default: #FORMULA が必要です

ステップ 3：分析クエリを作成する

リクエストに合ったテンプレートを選択します。

テンプレート A — シンプルなプロジェクション（行に 1 つ以上のディメンション、列に 1 つ以上のメジャー）

@EndUserText.label: 'Sales Analytical Query'
@AccessControl.authorizationCheck: #NOT_ALLOWED
define transient view entity ZC_SalesQuery
  provider contract analytical_query
  as projection on ZI_Sales_Cube
{
      @AnalyticsDetails.query.axis: #ROWS
  RegionId,

      @AnalyticsDetails.query.axis: #FREE
  CalendarYear,

      @AnalyticsDetails.query.axis: #COLUMNS
      @Semantics.amount.currencyCode: 'CurrencyCode'
  SalesAmount,

  CurrencyCode
}

テンプレート B — 制限付きメジャーと計算メジャー

@EndUserText.label: 'Sales KPI Query'
@AccessControl.authorizationCheck: #NOT_ALLOWED
define transient view entity ZC_SalesKpiQuery
  provider contract analytical_query
  as projection on ZI_Sales_Cube
{
      @AnalyticsDetails.query.axis: #ROWS
  RegionId,

      // restricted measure: selection-related CASE — WHEN must reference a DIMENSION
      @Semantics.amount.currencyCode: 'CurrencyCode'
  case when CalendarYear = '2025' then SalesAmount else null end as SalesAmount2025,

      // calculated measure: formula CASE — needs @Aggregation.default: #FORMULA
      @Aggregation.default: #FORMULA
  case when SalesAmount is initial then abap.int8'0' else abap.int8'1' end as HasSales,

  CurrencyCode
}

テンプレート C — 入力パラメーターを含むクエリ（フィルタープロンプト）

@EndUserText.label: 'Sales Query (parameterized)'
@AccessControl.authorizationCheck: #NOT_ALLOWED
define transient view entity ZC_SalesParamQuery
  provider contract analytical_query
  with parameters
    p_year : abap.numc(4)
  as projection on ZI_Sales_Cube
{
      @AnalyticsDetails.query.axis: #ROWS
  RegionId,
      @Semantics.amount.currencyCode: 'CurrencyCode'
  SalesAmount,
  CurrencyCode
}
where CalendarYear = $parameters.p_year

作成ルール（記述前に適用してください）：

• キューブから直接プロジェクションするすべての要素には、キューブ内の正確な要素名を使用してください（ステップ 1c で確認した名前です）。計算メジャーと制限付きメジャー（テンプレート B）は例外です。これらは新しいエイリアス（... as SalesAmount2025 など）を定義するため、キューブに存在する必要はありません。
• すべての金額メジャーには @Semantics.amount.currencyCode: '<field>' が必要で、通貨フィールドもプロジェクションする必要があります。
• すべての数量メジャーには @Semantics.quantity.unitOfMeasure: '<field>' が必要で、単位フィールドもプロジェクションする必要があります。
• クエリ名は 28 文字以内にしてください。

ステップ 4：計画を示してから作成する

作成前に、組み立てた DDL と軸の配置（行／列／フリーに配置するフィールド）をユーザーに提示してください。確認後：

SAPWrite(action="create", type="DDLS", name="<query>", source="<ddl>", package="$TMP")

移送可能なパッケージの場合は、package="<pkg>" と transport="<TR>" を渡してください（TR はユーザーが指定する必要があります。必要に応じて SAPTransport で作成してください）。

ステップ 5：有効化する

SAPActivate(name="<query>", type="DDLS")

有効化に失敗した場合は、診断メッセージをそのまま提示し、ユーザーからの再プロンプトを待ってください。黙って再試行してはいけません。よくある失敗：

• @AccessControl.authorizationCheck が #NOT_ALLOWED ではない → アノテーションを修正してください
• キューブに要素が見つからない → キューブに存在しない名前を使用しています（ステップ 1c を再確認してください）
• メジャーに通貨／単位の参照がない → @Semantics.* アノテーションを追加し、通貨／単位フィールドをプロジェクションしてください
• 名前が 28 文字を超えている → クエリ名を短くしてください

ステップ 6：検証する

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

クエリが使用可能であり、プロジェクションした要素が表示されることを確認してください。ランタイム名（2C<query>）を添えて、成功を報告してください。

エラー処理

エラー	原因	対処
プロジェクション対象がキューブではない	通常のビューに対してプロジェクションしようとした	まず generate-analytics-star-schema でキューブを作成してください
provider contract 構文エラー	SAP_BASIS < 7.57	中止してください。このリリースでは analytical_query はサポートされていません
有効化時の権限チェックエラー	#NOT_ALLOWED 以外の値を使用した	@AccessControl.authorizationCheck: #NOT_ALLOWED を設定してください
要素が存在しない	キューブの要素名と名前が一致しない	キューブの要素を再確認してください（ステップ 1c）
名前が長すぎる	クエリ名が 28 文字を超えている	名前を短くしてください

メモ

• このスキルで作成するのはクエリレイヤーのみです。基盤となるキューブ、ディメンション、テキストを作成するには、先に generate-analytics-star-schema を使用してください。この 2 つのスキルは連携します。star-schema がキューブを生成し、このスキルがそのキューブに対してプロジェクションを行います。
• 分析ではなくトランザクション（RAP）サービスを使う場合は、代わりに generate-rap-service を使用してください。
• BTP ABAP とオンプレミス 7.58 のどちらもサポートしています。7.57 では、まず search() で正確な provider contract 形式を確認してください。