generate-cds-analytical-query

生成 CDS 分析查询

生成一个分析型 CDS 查询——一个带有 provider contract analytical_query 的 临时投影视图，基于现有分析立方体（@Analytics.dataCategory: #CUBE）。

此技能结合 ARC-1（SAP 系统访问）与 mcp-sap-docs（文档和最佳实践），复现 SAP Joule 的“CDS 分析查询生成”功能。查询视图供最终用户在分析客户端（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）出现 provider contract 语法错误，并在那里停止。
• 需要现有立方体。 此技能基于立方体进行投影。如果立方体尚不存在，请先运行 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——这两个技能可以串联使用：star-schema 生成立方体，此技能基于立方体进行投影。
• 如需创建事务型（RAP）服务而非分析服务，请改用 generate-rap-service。
• BTP ABAP 和本地部署的 7.58 均支持此功能；对于 7.57，请先通过 search() 核实确切的 provider-contract 格式。