Semantic package overview
A semantic package (SemanticSpec) centrally maintains the business meaning of MaxCompute data by associating tables, fields, metrics, and analysis rules. Data owners can generate suggestions, edit business definitions, and publish them for reuse by DataAgent or other agents. This topic describes the main content, version relationships, activation requirements, and usage permissions of semantic packages.
What is a semantic package
A semantic package consists of data descriptions and analysis rules organized by business topic. For example, an order table records the payment amount and order status. A semantic package further describes the unit of the amount, the time basis for statistics, how refunds are handled, and how multiple snapshots of the same order are deduplicated. These descriptions help agents such as DataAgent understand business questions and generate SQL. The specific business definitions must be confirmed by data owners who are familiar with the business.
A semantic package can reference up to 20 MaxCompute tables. Business definitions can be added within the selected table scope, and subsequent changes are managed through drafts and published versions. A semantic package stores only table references and business definitions, and does not copy or modify the underlying business data.
Components of a semantic package
Structurally, a semantic package contains basic information such as a name, a description, tags, and a data scope, and organizes business definitions into the following seven content sections. The sections required for the current analysis can be filled in first and then refined over time. The semantic model further contains logical tables, dimensions, and the relationships between tables.
Content section | Purpose |
Data References | Specifies the projects and tables that the semantic package uses. |
Semantic Model | Organizes tables and fields into logical tables, dimensions, time dimensions, filter conditions, and confirmed relationships. |
Instructions | Records SQL usage rules, deduplication methods, time definitions, default filter conditions, and business rules. |
Metric Definitions | Describes how metrics are calculated, including expressions, aggregation methods, statistical granularity, and applicable conditions. |
Verified Queries | Stores verified typical questions and their SQL for reference in subsequent analysis. |
Business Glossary | Explains business terms, their aliases, and how they map to metrics or dimensions. |
Test questions | Stores questions and expected results that are used to check the semantic content. This section is currently displayed as Benchmark Set in the console. |
For example, the relationship between orders and channels can be described in Semantic Model, the deduplication rule for order snapshots and the refund rule can be recorded in Instructions, and the definition of the payment amount can be maintained in Metric Definitions. Table schemas, business definitions, and verification examples complement each other, which reduces repeated explanations of the same rules during analysis.
Maintain and publish a semantic package
The console displays the following four types of content separately:
Console tab | Purpose |
Smart Suggestions | Stores the system suggestions generated by DataScan (the MaxCompute data scanning service) for maintainers to review. |
Work Draft | Stores manually edited content and applied suggestions, which are used to refine and verify business definitions. |
Current Release | Displays the published version for DataAgent or other applications to read. |
Release History | Records the publishing history. |
To maintain a semantic package, the typical workflow is to generate and review system suggestions, apply the required content to the working draft, and then add business rules. After the business definitions, SQL, and query results are checked and the automatically generated reference queries are verified against the business, publish the draft for use by DataAgent or other agents.
Applying system suggestions replaces the selected content section as a whole. If the content section already contains manual definitions, save the content to be retained separately first. After the suggestions are applied, check and complete the draft before publishing it.
Generating suggestions and saving drafts do not affect the published version. When business definitions change, edit the draft and publish it again. Each published version has its own revision number, which can be used to trace the business definitions on which an analysis was based. A published version fixes only the business definitions. Therefore, to reproduce historical query results, also check for changes in the SQL, query time, data scope, and source data.
Prerequisites
MaxAgent must be activated before the semantic package feature can be used. For more information about how to activate MaxAgent, see MaxAgent. After activation, configure the semantic package management permissions and data access permissions as described in the following sections.
Configure permissions
Before semantic packages are used, confirm both the semantic package management permissions and the data permissions required for scanning and analysis.
Configure semantic package management permissions
To control permissions by member, resource, and operation, use the roles and policies of CatalogAPI (the MaxCompute data catalog management API) for fine-grained authorization. For more information about integration and authorization capabilities, see CatalogAPI SDK User Guide.
To quickly grant management permissions to maintainers, a user who already has management permissions can add an admin administrator in the console. This method grants permissions based on the administrator role and covers a broad scope. Select the scope based on the maintenance responsibilities of each member.
Procedure:
Log on to the MaxCompute console and select a region in the upper-left corner.
In the left-side navigation pane, choose . On the Tenant Property tab, click Add Members in the MaxCompute IAM permission administrator section.
In the Add Member dialog box, check the authorization scope, and make sure that is set to tenant-level admin.
Search for or manually add the members to be authorized, and click OK.
In the member list, make sure that the authorization scope is as expected.
Configure data permissions for scanning and analysis
To improve the effectiveness and quality of semantic scans, make sure that the identity used for scanning has access permissions on the corresponding data tables and on the tenant-level Information Schema. Information Schema provides metadata and usage history, which serve as a reference for analyzing table schemas, relationships, and usage patterns. Permissions on the corresponding data tables are used to read the table information and data required for scanning.
The admin administrator authorization and the access permissions on data tables and Information Schema must be confirmed separately. A successfully added administrator does not mean that all data authorization is complete. Generating suggestions and performing analysis also require the permissions on the project and the permissions to run the corresponding jobs.
For more information about Information Schema authorization, see Tenant-level Information Schema: RAM user authorization.
For more information about project and table permissions, see Permissions overview and Authorization operations.
What to do next
To learn how DataAgent works with semantic packages, see DataAgent.
To create, maintain, and use a semantic package step by step with screenshots, see Manage and use semantic packages in the console.
To connect a custom agent, see MaxCompute MCP service guide.