语义包功能介绍-云原生大数据计算服务 MaxCompute(MaxCompute)-阿里云帮助中心

语义包（SemanticSpec）用于集中维护 MaxCompute 数据的业务含义，将表、字段、指标和分析规则关联起来。数据负责人可以生成建议、编辑并发布业务口径，供 DataAgent 或其他智能体复用。本文介绍语义包的主要内容、版本关系、开通条件和使用权限。

什么是语义包

语义包是按业务主题组织的数据说明和分析规则。例如，订单表记录了支付金额和订单状态，语义包进一步说明金额单位、统计时间、退款处理方式，以及同一订单的多条快照如何去重。这些说明帮助 DataAgent 等智能体理解业务问题并生成 SQL，具体口径需要由熟悉业务的数据负责人确认。

一个语义包最多引用 20 张 MaxCompute 表。在选定的表范围内，可以补充业务定义，并通过草稿和发布版本管理后续变化。语义包只保存表引用和业务定义，不复制或修改底层业务数据。

从组织层次看，语义包包含名称、描述、标签和数据范围等基本信息，并按以下七类内容区组织业务定义。可以先填写当前分析所需的部分，再逐步完善。其中，语义模型进一步包含逻辑表、维度及表之间的关联关系。

内容区	主要用途
数据引用	说明语义包使用哪些项目和表。
语义模型	将表和字段组织为逻辑表、维度、时间维度、过滤条件及已确认的关联关系。
使用说明	记录 SQL 使用规则、去重方式、时间口径、默认过滤条件和业务规则。
指标定义	说明指标如何计算，包括表达式、聚合方式、统计粒度和适用条件。
已验证查询	保存经过核验的典型问题及 SQL，供后续分析参考。
业务术语	解释业务词汇、别名及其与指标或维度的对应关系。
测试问题	保存用于检查语义内容的问题和预期结果；控制台当前显示为评测集。

例如，可以在语义模型中说明订单与渠道的关联，在使用说明中记录订单快照去重和退款规则，在指标定义中维护支付金额口径。表结构、业务定义和验证示例相互补充，减少分析时对同一规则的重复解释。

控制台分别展示以下四类内容：

控制台页签	业务用途
智能建议	保存 DataScan（MaxCompute 数据扫描服务）生成的系统建议，供维护者审阅。
工作草稿	保存人工编辑的内容和已应用的建议，用于完善和验证业务口径。
当前发布	展示已发布版本，供 DataAgent 或其他应用读取。
发布历史	发布历史记录。

维护语义包时，通常先生成并审阅系统建议，将需要的内容应用到工作草稿，再补充业务规则。核对业务定义、SQL 和查询结果，并对自动生成的参考查询进行业务核验后，发布草稿供 DataAgent 或其他智能体使用。

重要

应用系统建议会整体替换所选内容区。如果该内容区已有人工定义，请先另行保存需要保留的内容，应用后检查并补齐草稿，再发布。

生成建议和保存草稿都不会影响已发布版本，口径变化时编辑草稿并重新发布即可。每个已发布版本都有独立的修订号，可用于追溯某次分析所依据的业务定义。由于已发布版本只固定业务定义，复现历史查询结果时，还需要核对 SQL、查询时间、数据范围及源数据的变化。

使用语义包功能前，需要先开通 MaxAgent。开通方式及相关说明，请参见MaxAgent。开通后，还需按下文完成语义包管理和数据访问授权。

使用语义包前，需要分别确认语义包管理权限，以及扫描和分析所需的数据权限。

按成员、资源和操作控制权限时，可以通过 CatalogAPI（MaxCompute 数据目录管理接口）的角色和策略进行细粒度授权。接入及授权能力，请参见CatalogAPI SDK 使用指南。
需要快速为维护人员授予管理权限时，可以由已有管理权限的人员在控制台添加 admin 管理员。这是按管理员角色授权的方式，授权范围较大，应根据成员的维护职责选择范围。

配置步骤如下：

为提升语义扫描的效果和质量，建议扫描使用的身份具有对应数据表和租户级 Information Schema 的访问权限。Information Schema 提供元数据和使用历史信息，可为分析表结构、关联关系和使用模式提供参考；对应数据表的权限用于读取扫描所需的表信息和数据。

admin 管理员授权与数据表、Information Schema 的访问权限需要分别确认，不能将管理员添加成功视为已完成全部数据授权。生成建议和执行分析时，还需具备执行项目及相应作业所需的权限。