View and manage semantic views
View and edit semantic views in the AnalyticDB for MySQL data catalog. Use DryRun to inspect generated semantic SQL and its rewritten executable SQL.
For automatic build tasks and draft management, see Automatically build semantic views.
Prerequisites
Semantic views are in public preview and are not available in all regions. Submit a ticket or contact technical support to request access.
A RAM user is associated with a database account. For the procedure, see Associate or disassociate a database account with or from a RAM user.
A semantic view exists in the database. All physical databases, tables, and columns referenced by its definition also exist.
Semantic views require the same database permissions as regular AnalyticDB for MySQL views:
Operation | Database permissions |
View a definition | SHOW VIEW and SELECT on the target view. |
Create a view | CREATE VIEW on the target object scope and SELECT on referenced objects. |
Replace a definition | The permissions required to create a view, plus DROP on the target view. |
For permission inspection and authorization, see Database permission model.
Find semantic views
Log on to the AnalyticDB for MySQL console, select a region, and go to the target cluster.
Open the target database under Data Management > Data Catalog and click the Semantic Views tab.
The list shows view names, databases, and descriptions. Use Search to find a view by name and Refresh to update the list. Click a view name to open its details.
For other data catalog features, see Manage the data catalog in the console.
View details
The details page shows view information, semantic objects, and the complete YAML definition. It provides these controls:
Page area | Available operations |
View information | View the database, name, and description. Edit the name or description. |
Overview | View object counts and expand groups for logical tables, dimensions, facts, metrics, derived metrics, filters, relationships, and verified queries. Edit objects through the available controls. |
YAML | View the complete definition. Use Copy YAML or Download to retain a copy. This tab is read-only. |
DryRun validation | Inspect generated candidate questions, semantic SQL, and rewritten executable SQL. |
Names and descriptions
Click Rename or Modify Description beside the view name or description to open its form. The list also provides Rename. Saving updates the list and details. Reopen them to verify the changes.
After renaming a view, check queries and applications that depend on its original name.
View and edit semantic objects
Semantic objects appear under Overview. Expand a group to inspect its entries. For an entry with an Edit control, click Edit to open its form. The following sections describe where to find objects and what to review. Editable fields depend on the form.
Logical tables
The logical table group shows physical table mappings, primary keys, descriptions, and synonyms. Use the table's Edit control to change available fields. Expand the table to inspect its dimensions, facts, metrics, and named filters.
Dimensions, facts, metrics, and filters
These objects appear in groups under their logical table. Use the details and edit forms to review the following items:
Object | Items to review |
Dimension | Name, column expression, data type, description, and synonyms. |
Fact | Name, column expression, data type, description, and synonyms. |
Metric | Name, calculation expression, relationships used, description, and synonyms. |
Filter | Name, filter expression, description, and synonyms. |
Derived metrics, relationships, and verified queries
These objects appear in their view-level groups. Open a form through the entry's Edit control.
Object | Items to review |
Derived metric | Name, calculation expression, metric dependencies, description, and synonyms. |
Relationship | Relationship name, left and right logical tables, and join columns. |
Verified query | Question, SQL, verifier, and verification time. |
Follow the object structure in Semantic YAML specification. Relationship definitions do not require explicit join_type or relationship_type settings. The system infers relationship types from the data and primary key definitions.
Save changes
Click Save and Synchronize YAML to save an object and update the complete definition. Click Cancel to discard changes in the current form. The save control may be disabled if nothing has changed.
Before saving, copy or download the current definition from the YAML tab. After saving, reopen the object to verify its fields. Check YAML to confirm that the definition was synchronized.
The description field for logical tables and dimensions is labeled Description in adopted views and Business Description in drafts. Saving a draft changes only its pending definition. Saving an adopted view updates the database object. Check affected queries after changing expressions, referenced names, relationships, or filters.
DryRun validation
Use DryRun Validation on the details page to generate candidate questions and inspect SQL generated and rewritten from the current semantic view.
Page content | Information to review |
Candidate questions | Generated business questions that show the query requirements covered by this validation. |
Semantic SQL | Dimensions, metrics, filters, and grouping referenced by the query. The SQL can be copied. |
Executable SQL | Physical tables, join columns and types, WHERE conditions, aggregations, and grouping after rewriting. The SQL can be copied. |
If the generated SQL is not as expected, edit the relevant semantic object definition, save it, and rerun DryRun.
DryRun generates or rewrites SQL; it does not execute queries against business data. Each candidate question covers only its referenced objects and calculations. To verify actual results, execute the generated SQL and corresponding business SQL against the same data range and compare their results.
Troubleshooting
Issue | Resolution |
A view is missing from the list | Confirm that draft adoption succeeded. Refresh the list and verify the database, view name, and account permissions. |
No edit control is available for an object | Check whether you opened a draft or an adopted view, and expand the relevant object group. Editable fields depend on the available form. |
Saving fails | Retain your edits and the error message. Check permissions and required fields. Reopen the object to confirm its saved definition. |
DryRun fails or produces unexpected SQL | Retain the candidate question, error, or generated SQL. Check object references and expressions, correct and save the definition, and retry. |
If the issue persists, retain the view name and error details and contact technical support.