Overview
This document describes how to create a semantic model in DataBuddy using the YAML editor. A semantic model is the smallest data unit for business analysis, serving as a semantic encapsulation of one or more physical tables and the foundation for defining metrics later. After creation, you can publish the model and define metrics and dimensions on it, as well as authorize business users to consume it. Prerequisites
Before you start this operation, make sure the following prerequisites are met:
You have activated the DataBuddy service and have the Read Write or Read Write & Delete feature permission for Ontology Modeling in the target workspace. Without the feature permission, the Model Management Tab is invisible or read-only. If you lack the required permission, contact the workspace administrator to apply for it.
You must have the Table.Select permission on the Catalog that contains the physical tables to be referenced. For each table referenced in the model YAML, your current account must have the Select permission, otherwise the validation will fail upon publishing.
Use Limits
|
Creation Permission | Only users with Read Write or higher feature permissions for Ontology Modeling can create. |
Editing Mode | Currently, only the YAML editor is supported, or you can use natural language to create with the assistance of Buddy. |
Owner | The model creator is the owner by default. Each model can have only one owner, and the ownership can be transferred. |
Operation Steps
Step 1: Go to Ontology Modeling -> Model Management
In the left navigation pane of the workspace, click Ontology Modeling and go to the Relational Model submenu. This page displays all models visible to you in the current workspace.
Each model card displays the model name, owner, number of tables and metrics, model description, English identifier, and status tag (Published or Offline).
Step 2: Initiate Creation
In the upper-right corner of the page, click + Create Model (YAML). The system opens the YAML editing panel, with the table selector on the left and the code editor on the right.
Note:
If you are unsure about the YAML syntax, you can click View Example in the upper-right corner to bring up an official example snippet, or use the Hi Buddy entry to have the AI assistant help generate the model YAML.
Step 3: Select a Referenced Physical Table
In the table selector on the left, select a data source and quickly insert the resources to be referenced in the YAML:
1. Data Catalog: You can select a data catalog from TC Catalog (native), or from directly connected data sources such as Doris and StarRocks, including their catalogs and Schema tables.
2. Logical View: You can select created logical views and the fields within them.
3. Relational Model: You can select relational models, tables and fields referenced within them, metrics created within them, and analysis dimensions supported by the metrics.
Step 4: Write the Model YAML
In the editor on the right, write the YAML according to the following structure:
# Version: 1.0============================================================
# [Required] Configuration file version, fixed at 1.0
version: 1.0
# ============================================================
# Semantic Model Definition
# type: DEF - Create a model (a complete definition is required)
# REF - Reference an existing model (only name + type required)
# ============================================================
model:
# [Required] Model name in English, 1-50 characters, supporting letters, digits, underscores, and parentheses.
name: ecommerce_order_model
# [Optional] List of model aliases. Multiple aliases are supported, and commas are not allowed.
# Defaults to name when empty. Stored as comma-separated values in the database.
label:
- E-commerce order model
- order_model_alias
# [Optional] Model description
description: "The primary e-commerce order model, associated with the user table and the product table"
# [Required] Model type: DEF (define a new model) | REF (reference an existing model)
type: DEF
# [Required for DEF] Path to the primary table data source. Format: catalogName.databaseName.tableName
source: default_catalog.ecommerce_db.orders
# [Optional] JOIN table configuration. Nested JOINs are supported.
joins:
- name: user_table # Alias of the joined table (required)
source: default_catalog.ecommerce_db.users # Path of the joined table (required)
on: # Join condition (required, at least one)
- source.user_id = user_table.id
# Nested joins (optional)
joins:
- name: user_address
source: default_catalog.ecommerce_db.addresses
on:
- user_table.id = user_address.user_id
- name: product_table
source: default_catalog.ecommerce_db.products
on:
- source.product_id = product_table.id
YAML key field description:
Field | Required | Description |
version
| Yes | YAML schema version, currently fixed at 1.0 |
model.name
| Yes | English model identifier, supporting only lowercase letters / digits / underscores, unique within the workspace. |
model.label
| Yes | Model alias, used for display on list cards and detail pages. |
description
| No | Model description, recommended to briefly describe the business domain and coverage scope. |
model.type
| Yes | Values: DEF (create a model, requiring a complete definition) / REF (reference an existing model, requiring only name + type). |
model.source
| Yes | Three-level path of the model primary table: catalog.schema.table |
model.joins
| Required for multiple tables | Join relationships between tables; must be declared only in multi-table models. |
Note:
Each table referenced in the model YAML must have the Table.Select permission under the current account. During publishing, the system validates each table. Tables lacking the permission are flagged with a warning in the YAML editor, and the publishing process is blocked.
Step 5: Publish the Model
After you finish editing the model YAML, click Publish in the lower-left corner:
1. The system first performs syntax validation. The validation items include YAML format, required fields, table Select permissions, whether dimension fields exist, and whether Join fields exist.
2. After the validation is passed, a confirmation dialog appears.
3. After you click Confirm, the model enters the Published state, and the model card displays a green Published tag.
After publishing, you can:
Grant other users the Manage / CreateMetric permissions on the Authorization Tab of the model details page.
Use Buddy to have AI assist you in creating metrics.
Step 6: Transfer Ownership (Optional)
Each model can have only one Owner, who is the creator by default. To transfer ownership:
1. Go to the model details page. In the drawer on the right, go to Basic Information > Owner. hover over the field to display a pencil ICON, and click it to transfer the Owner.
2. After you select the target user and submit, the system displays a second confirmation dialog.
3. After the transfer, the original Owner loses the permissions to delete and transfer the model. If the original Owner still needs to perform these operations, the new Owner can grant the Manage permission.
Creating a Model via Buddy
You can describe your requirements in natural language in Buddy, and AI will assist you in generating the model YAML and completing the publishing. Common conversation examples:
Help me create an Olist e-commerce sales model using the dlc.default_catalog.olist.orders and users tables, with user_id as the join key.
Before performing write operations (create, modify, publish, take offline, and delete), the Agent verifies permissions:
If you do not have the Model Management feature permission, Buddy will block the operation and prompt: "You currently do not have the permission to create a semantic model. Contact the workspace administrator XXX to apply for the read, write, and delete permissions of Semantic Model > Model Management before proceeding. Alternatively, you can directly submit your requirements, and the semantic layer administrator XXX will assist you in creating the model."
If you have the create permission but lack the Select permission on the required tables, Buddy will list the names of the tables for which you lack permissions and their corresponding table owners, guiding you to apply offline.
Model Details Page
After a model is published, click any model card on the Model Management list page to go to the model details page. The details page is the main entry for viewing the structure, managing metrics and dimensions, and configuring permissions after the model is online.
Overall Page Structure
The details page is divided into three areas:
Top bar: displays the model name and status label (Published / Offline). On the right, operation buttons are displayed based on the current Tab context, with Edit and Offline always available. When you go to the Permissions Tab, the Authorize button also appears.
Main content area: provides four views in the form of tabs, which are Entity Relationship (default), Associated Metrics, Associated Dimensions, and Permissions.
Right information panel (displayed under the Entity Relationship Tab): contains three groups of information.
Basic information: alias, description, owner, and status.
Technical information: creation time, creator, last updated time, and modifier.
Model information: number of associated tables, metrics, and dimensions.
Entity Relationship Tab
The default Tab visually displays the relationships between physical tables in the model in the form of a canvas:
Each table corresponds to a table card. The table name (including the three-part path catalog.schema.table) is displayed at the top, and the field names, data types, and Chinese descriptions are listed below in field order.
The lines between tables correspond to the joins relationships declared in the YAML file.
View controls such as zoom in, zoom out, widescreen, and fullscreen are provided in the upper-right corner of the canvas, making it easier to browse scenarios with many tables and fields.
Associated Metrics Tab
List all metrics defined on the model in the form of a table:
|
Metric Name / Metric Alias | English identifier and Chinese tag of the metric |
Metric Type | Atomic metric / Derived metric |
Derived Type | Displays the specific subtype when the metric type is derived metric (filtering / cumulative calculation / period-over-period calculation / hybrid calculation / conversion calculation). |
Metric definition | SQL summary of metric calculation |
Source Table | Physical table referenced by the metric |
Owner | Metric Owner |
Last Modified Time | Last edited or published time |
Operation | Edit or take offline a single item |
A Batch Authorization button is provided above the table. After selecting multiple metrics, you can grant authorization to them in a unified manner.
Associated Dimensions Tab
List all dimensions referenced by the model in the form of a table:
Column | Description |
Dimension Name / Dimension Alias | English identifier and Chinese tag of the dimension |
Description | Business description of the dimension |
Dimension Type | Standard dimension / time dimension / dictionary dimension, and so on. |
Dimension Value Information | Value characteristics of the dimension, for example, the time dimension displays "Minimum granularity: Day" |
Owner | Dimension Owner |
Associated Field | Physical field path corresponding to the dimension in the underlying table |
Last Modified Time | Last modified time of the dimension |
Permissions Tab
Display the authorization status of the model and its metrics in the form of a table:
|
Authorized object | Authorized user/user group |
Type | User/user group |
Permission Point | Specific permission points such as Manage / Create Metric / Query |
Table permission | Whether the authorized object has Table.Select permission on all physical tables referenced by the model (complete/missing) |
Dimension | Dimension range that the authorized object can query |
Dimension Value Range | Dimension value range that the authorized object can query (row permission) |
Filtering relationship | Relationship between multiple dimension values |
Grantor | User who initiated this authorization |
Authorization time. | Authorization effective time |
Operation | Edit/Revoke |
Above the table, you can search for users and user groups by keyword and filter by permission scope. Click Authorize in the upper-right corner to initiate a new authorization task, which opens the Model Authorization dialog box (see Model Authorization for details). In the table, the Edit button for each row allows you to change the permission points of an existing authorization, and the Revoke button allows you to revoke granted permissions. Model Authorization
After the Authorize button in the upper-right corner of the Permissions Tab is clicked, the Model Authorization | <Model Name> dialog box appears, which is used to grant one or more permissions of the model to specified users or user groups.
The dialog box contains three sections from top to bottom:
1. Authorized Entity (Required)
Selectable: User, User Group, Tag
2. Authorization Target (Required)
If User is selected as the authorization principal, the user selection panel is displayed here, allowing you to search for users. Add at least one user.
If User Group is selected as the authorization principal, the user group selection panel is displayed here, allowing you to search for user groups. Add at least one user group.
If Tag is selected as the authorization principal, you do not need to select an authorization object. You only need to select the authorization points below.
3. Authorization Point (Required, select at least 1 item)
Field label: Authorization Point *. Below are selectable permission point cards, each containing two lines of description: Capability Description and Applicable Scope.
|
Create Metric | Create a new metric based on this model. | Allows defining atomic metrics / derived metrics on this model, but cannot modify the model itself. |
Manage | Manage models | Allows editing / publishing / taking offline models. Only the Owner can delete models. Also requires authorized users to have Select and Browse permissions on all underlying tables in the model; otherwise, after authorization succeeds, the user will be blocked when performing actions on the underlying tables. |
Query All Metrics | Query all metrics | Quickly grants users query permissions on all metrics under this model. |
All three permission points can be selected at the same time, or only one of them can be selected.
Validation Rule: If you click Confirm Authorization without selecting any permission point, a red message Please select a permission point appears below the field, and no authorization request is initiated.
4. Authorization Reason (Optional)
Field label: Authorization Reason.
Control: a multi-line text input box with the placeholder Please briefly describe the business context of this authorization.
It is used for auditing and post-incident tracing. We recommend that you enter the business purpose of this authorization or the source ticket number. You can also submit the form without entering this information.
5. Submission and Activation
Two buttons are provided at the bottom right of the pop-up window: Cancel (closes the pop-up window and discards the entered content) and Confirm Authorization (submits the authorization task).
After clicking Confirm Authorization:
1.1 The system performs required field validation on the form (authorization object and authorization point). If validation fails, an error message is displayed below the corresponding field.
1.2 After validation passes, the authorization record is written, and the authorized object immediately obtains the corresponding permission points. The new authorization appears as a new row in the Permissions Tab table.
1.3 If the authorized user lacks the Select / Browse permission on the underlying model tables, the Table Permission column in the corresponding row on the Permissions Tab displays Missing, but this authorization still takes effect.
FAQs
Q1: Can the referenced tables be modified after a model is created?
Yes. On the model details page, click Edit to re-enter the YAML editor. After making changes, publish the model again to apply the new structure.
Q2: Can a model be taken offline after it is published?
Yes. On the model details page, click Take Offline, and the model status changes to Offline. Downstream metric queries against this model will fail immediately. An offline model can be republished.
Q3: Does deleting a model affect the metrics on it?
Yes. Before deleting a model, you must delete all metrics on the model first. Otherwise, the system blocks the deletion operation. A deleted model cannot be recovered.
Q4: What is the difference between a model Owner and a model administrator (Manage)?
An Owner has all permissions, including transferring the Owner role and deleting the model. A Manage user has all permissions except transferring and deleting. A model can have only one Owner, but multiple Manage users can exist at the same time.
References