SEARCH SEMANTIC VIEW-AnalyticDB(AnalyticDB)-阿里云帮助中心

AnalyticDB for MySQL provides two ways to search for semantic views: an exact query through the information_schema.semantic_views system table, and a natural language similarity search through the sv_similar_search() function. AI Agents and NL2SQL workflows use these methods to discover the right semantic view before generating SQL.

Note

All SQL statements related to semantic views require the /*+ enable_semantic=true */ hint. Without this hint, the system cannot recognize semantic view syntax.

Query methods

Method	Query type	Matching	Best for
Exact query	Standard SQL WHERE	Column value matching	Looking up views by name or schema
sv_similar_search	Function call	Vector similarity	Natural language discovery for AI Agents

Method 1: Exact query

Use standard SQL WHERE conditions to match column values exactly and look up semantic views by name or schema.

Syntax

/*+ enable_semantic=true */
SELECT view_schema, view_name, definition
FROM information_schema.semantic_views
[WHERE view_schema = 'schema_name' AND view_name = 'view_name'];

Columns

Column	Description
view_schema	The schema that contains the semantic view.
view_name	The name of the semantic view.
definition	The complete YAML definition of the semantic view, including all tables, relationships, facts, dimensions, metrics.

Method 2: Natural language search

Use the sv_similar_search() function to find semantic views whose definitions are semantically similar to a natural language description.

sv_similar_search(definition, search_text, top_k) is a natural language similarity search function that returns the semantic views whose definitions are most similar to the search text, based on vector distance.

Syntax

/*+ enable_semantic=true */
SELECT view_schema, view_name, definition
FROM information_schema.semantic_views
WHERE sv_similar_search(definition, '<search_text>', <top_k>);

Parameters

Parameter	Description
definition	A fixed parameter that specifies the target column for the search.
search_text	Required. A natural language description of the data you are looking for. For example, `'revenue and profit analysis'`. The system vectorizes this text and searches for the most similar results in the vector index.
top_k	Required. The maximum number of results to return, a positive integer. Results are sorted by descending similarity score.

Typical AI Agent workflow

We recommend that AI Agents use natural language search to locate semantic views and then generate SQL from the definition. The typical workflow is as follows:

Search: Call sv_similar_search() with the user's natural language question to find relevant semantic views.
Read definition: Extract dimensions, metrics, and relationships from the definition column.
Generate query: Generate an accurate semantic SQL query with the /*+ enable_semantic=true, rewrite=true */ hint.
Execute: Execute the query, analyze the results, and return business insights.

-- Step 1: Search for relevant semantic views (metadata query, uses enable_semantic=true)
/*+ enable_semantic=true */
SELECT view_schema, view_name, definition
FROM information_schema.semantic_views
WHERE sv_similar_search(definition, 'total sales by region', 1);

-- Steps 2-3: Generate a query from the returned semantic definition (semantic query, uses rewrite=true)
/*+ enable_semantic=true, rewrite=true */
SELECT region, AGG(total_revenue)
FROM sales_analysis
GROUP BY region;

Usage notes

Vector similarity search depends on the Embedding service. When the service is unavailable, both sv_similar_search() and Hint-based queries may fail. Use the exact query method instead.
The vector index is updated automatically when a semantic view is created or modified, and becomes available for search immediately after the DDL completes.
Search results are sorted in descending order of similarity score.

Examples

List all semantic views.

/*+ enable_semantic=true */
SELECT view_schema, view_name, definition
FROM information_schema.semantic_views;

Use natural language search to find the three semantic views most relevant to revenue and profit for the Beijing market.

/*+ enable_semantic=true */
SELECT view_schema, view_name, definition
FROM information_schema.semantic_views
WHERE sv_similar_search(definition, 'revenue and profit for the Beijing market', 3);

View the complete definition of a specific semantic view.

/*+ enable_semantic=true */
SELECT view_schema, view_name, definition
FROM information_schema.semantic_views
WHERE view_schema='analytics' AND view_name='sales_analysis';