Semantic pack management and application-MaxCompute(MaxCompute)-阿里云帮助中心

Semantic packs address a common challenge for AI Query: without business context, it can only guess the semantics of your data from the table structure. By cataloging business knowledge—such as terms, metrics, joins, and verified queries distilled from historical SQL—into a semantic pack, you provide AI Query with a single source of truth. This allows it to answer business questions with consistent definitions and generate significantly more accurate SQL.

Overview

A semantic pack is a set of structured files that describes the business meaning of your data assets. The client mines business facts from historical MaxCompute SQL queries and uses LLM enhancement to generate definitions for terms, entities, metrics, and joins. The client then compiles this information into a runtime index that AI Query references when generating SQL.

Each semantic pack belongs to a domain. A domain is a logical container for a semantic pack and its assets, corresponding to a dedicated file directory. You can create different domains for different business lines or data topics.

semantic-pack-guide-zh

Use cases

Improve AI Query accuracy: After binding a semantic pack to a session, the AI can access term definitions, metric definitions, and table joins when planning SQL. This reduces field misuse and definition deviations.
Capture team knowledge: Codify recurring dimension names, metric formulas, and common join conditions. This allows new team members to get up to speed quickly without rediscovering established logic.
Validate SQL correctness: Verified queries are standard SQL statements that have been manually confirmed. The AI can reference these patterns to generate more reliable results and reduce hallucinations.

Feature index

Feature category	Features
Creation and building	Build from historical SQL, create an empty domain, import from dbt, and add tables incrementally.
Component editing	Add, update, and delete terms, entities, metrics, joins, verified queries, and playbooks.
Compilation and publishing	Compile into a runtime index, automatic/manual compilation, and view compilation reports.
Visualization	Semantic relationship graph: a topology view of entities, metrics, terms, and joins.
AI Query application	Bind a semantic pack to a session and have AI automatically reference semantic knowledge to generate SQL.
AI-assisted building	Instruct the AI to create, edit, or bind a semantic pack in an AI Query conversation.

Prerequisites

You have created and successfully connected to a MaxCompute data source, and have selected a project.
To use the "Build from historical SQL" feature, your project must have a sufficient volume of query history (at least 7 days is recommended).

Quick start

The following steps guide you through building a semantic pack from historical SQL and using it in AI Query.

In the semantic pack section of the sidebar, click + (New semantic pack).
Enter a pack name and description, select one to three seed tables, choose a mining window (2, 7, or 14 days), and click Start Building.
Wait for the mining process to complete. Its duration depends on the volume of historical SQL. The right-side panel displays the build progress. After mining, a confirmation step appears. Review the related tables and candidate joins, then click Confirm and Continue.
After the draft is generated, choose whether to initiate LLM enhancement, which adds descriptions and synonyms. Click Start Enhancing.
After the enhancement is complete, review the content. If everything is correct, click Publish. The semantic pack is automatically compiled and added to the runtime index.
Ask a question in an AI Query conversation. The AI automatically binds the published semantic pack and references its terms and metric definitions to generate SQL.

Semantic pack components

A semantic pack consists of the following components:

Component	File	Description
Pack metadata	`pack.json`	Defines the domain name, description, keywords, default tables, and default metrics and dimensions.
Term	`terms.json`	Provides Chinese and English synonyms and descriptions for business terms to help the AI understand vocabulary in natural language.
Entity	`entities.json`	Defines data entities (which correspond to tables), including their primary keys, descriptions, field meanings, and interfaces.
Metric	`metrics.json`	Defines calculation expressions, aggregation methods, related dimensions, and synonyms for business metrics.
Join	`joins.json`	Defines the join conditions and types between tables.
Verified query	`verified-queries.json`	Contains manually confirmed, standard SQL examples that provide patterns for the AI to reference.
Playbook	`playbooks.json`	Provides step-by-step guides for common analysis scenarios, including required tables and preferred metrics.

Build a semantic pack

Build from historical SQL (recommended)

This method is ideal for projects with an established history of queries. The build process consists of five stages:

Prepare → Mine → Draft → Enhance → Review and publish

Prepare: Enter the pack name, domain ID (auto-generated if left blank), and description. Select the seed tables and the mining window (2, 7, or 14 days).
Mine: Scans historical MaxCompute SQL queries related to the seed tables to extract join candidates, metric candidates, and co-occurrence statistics. After mining, the process pauses for you to review and confirm the related tables and candidate joins.
Draft: Based on the confirmed table metadata and sampled data, the client generates semantic assets, including terms, entities, metrics, joins, and verified queries.
Enhance: The LLM enriches the draft with descriptions, synonyms, and business explanations while preserving the evidence from the mining stage. You can choose to enhance all components or only specific ones.
Review and publish: Review all generated content and, after confirmation, publish it to the runtime index.

The build view in the right-side panel displays the build progress in real-time. After each stage, the build task pauses and waits for your confirmation before proceeding.

Note

The build process runs as a background task. You can switch to other pages and continue your work without losing progress.

Manually create an empty domain

In an AI Query conversation, tell the AI to "create an empty semantic pack named xxx." The AI calls a backend API to create an empty domain. You can then add components like terms, entities, and metrics in the editor. This approach is suitable when you have well-defined semantics and do not need to mine them from historical SQL.

Import from a dbt project

In the dbt panel, click Import semantic pack to convert semantic models and metrics from your dbt project into a semantic pack. For more details, see dbt and MaxCompute Ecosystem Integration.

Incrementally add tables

For an existing semantic pack, you can use the Add table operation to append new tables. The client reads the table's metadata and sample data to generate an entity definition, field descriptions, and join candidates.

Edit a semantic pack

In the sidebar, click an existing semantic pack to open its editor tab. The editor tab contains two subviews:

Pack manager

Displays all components (terms, entities, metrics, joins, verified queries, and playbooks) in a list and supports the following actions:

Add entry: Add a new entry for any component and fill in the required fields.
Edit entry: Modify the name, description, expression, synonyms, or other properties of an existing entry.
Delete entry: Remove entries that are no longer needed.
Enhance a single component: Use the LLM to add descriptions and synonyms for a specific component without affecting others.

After making changes, you must recompile the pack for AI Query to use the updated content.

Semantic relationship graph

Visually displays the relationships between elements in the pack, showing the topology of references and joins among entities, metrics, and terms. This graph helps you understand the pack's scope and structural integrity at a high level.

Compilation and publishing

Compilation merges the component files of a semantic pack into a single runtime index (index.json) that AI Query can load and use.

Triggering compilation

Automatic compilation on save: Saving changes in the editor tab automatically triggers a compilation for the domain.
Compilation on publish: Publishing automatically triggers a compilation during the "Review and publish" stage of a build task.
Recompilation after deletion: After you delete a domain, the client asynchronously recompiles the runtime index for the remaining domains.
AI-triggered compilation: In AI Query, say "compile the xxx domain" to make the AI trigger the compilation action.

Compilation results

After a successful compilation, the runtime index takes effect immediately and can be used in the next AI Query conversation. If the compilation finds issues, such as a field that references a non-existent table, it generates a validation report for you to troubleshoot.

The semantic pack list in the sidebar has two sections:

Published: Semantic packs that have been compiled successfully and are ready to use.
Failed/Uncompiled: Semantic packs that have not yet been compiled or failed compilation. They must be fixed before AI Query can reference them.

Using a semantic pack in AI Query

Explicit binding

AI Query does not automatically load all compiled semantic packs. You need to explicitly tell the AI in a conversation to "use the xxx semantic pack" or "bind the xxx domain." The AI then calls a bind action to add the specified domain to the current session's semantic context. Binding is session-scoped and only affects the current conversation.

Once bound, all subsequent questions within the same session will reference the semantic pack. You do not need to bind it again for each question.

How AI uses a semantic pack

Once a pack is bound, the AI gains the following enhancements during each planning and execution cycle:

Table schema pre-injection: The system pre-loads the table schemas for entities defined in the semantic pack into the context, so the AI does not need to query metadata separately.
Term understanding: When a user asks about "average price per customer," the AI uses term synonyms to map this to the corresponding calculation expression.
Metric definition adherence: When generating aggregation SQL, the AI refers to the expression and aggregationType in the metric definition to ensure consistent calculations.
Join path guidance: For multi-table queries, the AI refers to the defined joins to select the correct join conditions, reducing the risk of Cartesian products.
Verified query referencing: The AI benchmarks the structure of the generated SQL against known patterns from verified queries, which reduces the error rate.

AI-assisted pack management

You can manage semantic packs directly within an AI Query conversation using natural language. The AI supports the following actions:

View: "List all semantic packs" or "Show me the metrics in the sales domain."
Bind: "Use the ecommerce semantic pack for my next questions."
Build: "Create a new semantic pack for the sales_order table." The AI initiates a build task, and the build progress appears in the side panel.
Edit: "Add a new metric to the sales domain: daily average orders = COUNT(order_id) / DATEDIFF(...)."
Compile: "Compile the sales domain."

At each decision point in a build task (such as confirming the table list, choosing to enhance, or reviewing before publishing), the task pauses and waits for your manual confirmation. The AI cannot skip these steps.

Delete a semantic pack

In the semantic pack list in the sidebar, select the target domain and click the delete button. In the confirmation dialog, click Confirm deletion. The domain directory is removed, and the client asynchronously recompiles the runtime index for the remaining domains.

Important

This deletion is irreversible. If an AI Query conversation is using the domain, semantic enhancements for that session stop immediately upon deletion.