Overview
A semantic Model is a semantic Layer that DataBuddy introduces between physical tables and business consumption. It abstracts fields scattered across tables in the data lake into three types of semantic objects from a business perspective: models, metrics, and dimensions, providing a unified, access-controlled semantic entry point for Buddy (AI Agent), reports, and downstream applications.
This document describes the design goals, overall architecture, and permission model of semantic models, helping you build a holistic understanding of the semantic layer. For subsequent operations, refer to Creating a Semantic Model, Defining Metrics and Dimensions, and Semantic Model Applications. Why a Semantic Layer Is Needed
In a traditional data warehouse without a semantic layer, common pain points include:
Inconsistent metric definitions: Different departments may define "GMV" as SUM(order_amount), SUM(pay_amount), or SUM(pay_amount) WHERE order_status='paid', leading to repeated disputes during reconciliation.
Business analysts rely heavily on data teams: Every time they ask for the average order value in Shanghai last week, they have to rewrite SQL and request access to the underlying tables.
Underlying table permissions are deeply coupled with business consumption: To use a single metric, business teams have to request Select permissions on all underlying tables that the metric depends on, making permission grants and revocations burdensome.
AI data retrieval is difficult to automate: If natural language queries are handled directly through the NL2SQL path, the hallucination rate is high, and issues such as table creation, table joins, and field semantics must be resolved every time.
The semantic layer addresses these issues in one place:
Define once, consume anywhere: metrics and dimensions become first-class citizens, and Buddy, reports, and other consumers share the same definitions.
Independent permissions and least privilege: business metric consumption does not depend on underlying table permissions at all.
Row-level security is manageable: dimension value range authorization can be used to achieve "Zhang San can only view East China."
Design Principles
Principle | Description |
Owner + Permission | Each type of semantic asset (model or metric) has only one Owner (transferable); grant the Manage / CreateMetric permissions on models, and grant the Manage / Query permissions on metrics |
Semantic layer independent of Catalog. | Creating a model requires the Select permission on the underlying table. Creating metrics and querying metric data do not depend on Catalog permissions at all. |
Least privilege | Creating metrics does not require viewing underlying data, only referencing models; querying metrics does not require model management permissions. |
Relational Model
A model is the smallest data unit for business analysis and represents the semantic encapsulation of one or more physical tables. A model declares the following:
Which Catalog tables are referenced, including the three-part path of Catalog / Schema / Table;
Join relationships between tables;
A model can be referenced by multiple metrics. Once a model is published, any changes to its structure require going through the publishing process again.
Metric
Metrics are business-consumable numeric measures defined on top of a model. Metrics are divided into two categories: atomic metrics and derived metrics.
Atomic metric (SIMPLE): the smallest statistical unit in a metric system, which performs aggregate calculations on a single field. For example, SUM(OrderAmount) represents the total transaction amount. Atomic metrics do not involve derived logic.
Derived metric: a metric processed from atomic metrics based on business rules, which is further divided into five types:
Filtered metric: a metric obtained by filtering atomic metrics based on specific dimensions such as time, region, or user attributes. For example, "Total Transaction Amount of Online Channels" = SUM(OrderAmount) with the filter Channel = Online.
Cumulative metric: a metric obtained by accumulating and aggregating atomic or filtered metrics over a time window. For example, "Total Transaction Amount of Online Channels in the Last 30 Days".
Period-over-period metric: a relative metric calculated by comparing cumulative metrics with data from the same period in the previous year (year-over-year) or the previous period (period-over-period). For example, "Period-over-Period Growth Rate of Total Transaction Amount of Online Channels in the Last 30 Days".
Hybrid calculated metric: a composite metric derived from two or more metrics through calculation rules such as addition, subtraction, multiplication, or division. For example, "Average Transaction Amount" = Total Transaction Amount / Transaction Quantity.
Conversion calculated metric: a metric calculated from atomic or filtered metrics at different stages to measure the conversion efficiency from A to B in a process. For example, "Registration-to-Order Conversion Rate" = Number of Orders / Number of Registrations.
Aggregation methods supported by metrics include SUM, COUNT, COUNT(DISTINCT), MAX, MIN, AVG, and custom expressions.
Dimension
Dimensions are used to define analytical perspectives. Based on the business semantics of fields, common dimensions can be divided into the following categories:
Time dimension: date and time fields used to slice metrics by time windows. They support aggregation at different granularities such as day, week, month, quarter, and year, serving as the core slicing basis for trend analysis such as period-over-period comparisons and the last N days.
Example: order_date (order creation date) and pay_time (payment completion time), which are often sliced by day, week, or month.
Dictionary dimension: a dimension field with a fixed and enumerable value range, corresponding to business classification systems such as "Category" and "Brand". Its values typically come from dictionary tables or predefined enumerations, and the field value range is limited and stable, facilitating normalization and standardized management.
Example: category_name (product category), brand (brand), and gender (gender).
Generic dimension: a general-purpose dimension field used to describe attributes of business entities, without special time or dictionary semantics. Common examples include user name, age, and user ID.
Example: user_name (user name), age (age), and user_id (user ID).
Dimensions are global dimensions that can be reused across models and can be defined centrally in Dimension Management.
Permission Model Overview
Semantic layer permissions are divided into three categories: Feature Permission, ACL Permission, and Data Permission, all of which are located under Workspace → Role Management → Semantic Modeling.
Permission Category | Control objective | Configuration Location |
Feature permission | Whether users can access the Model Management / Metric Management / Dimension Management tabs, and whether they can create / modify / delete items | Workspace → Role Management → Semantic Modeling Menu |
ACL permission (asset-level) | Specific capabilities of a user on a single model (Manage / CreateMetric); specific capabilities on a single metric (Manage / Query) | Model Details Page → Permissions Tab Metric Details Page → Permissions Tab |
Data permission (row-level) | Range of dimension values that users can query under the same metric | Dimension value range attached during metric authorization |
Model ACL Permission Matrix
Operation | Owner identity | Manage Permission Point | CreateMetric Permission |
View model structure | ✅ | ✅ | ✅ |
Edit model structure | ✅ | ✅ | ❌ |
Create a metric by referencing this model. | ✅ | ✅ | ✅ |
Publish or take offline a model. | ✅ | ✅ | ❌ |
Grant permissions to others | ✅ | ✅ | ❌ |
Transfer model ownership | ✅ | ❌ | ❌ |
Delete a model. | ✅ | ❌ | ❌ |
Metric ACL Permission Matrix
Operation | Owner identity | Manage Permission Point | Query Permission Point |
View Metric Metadata. | ✅ | ✅ | ✅ |
Query Metric Data. | ✅ | ✅ | ✅(Can be limited by dimension values) |
Edit Metric Definition. | ✅ | ✅ | ❌ |
Publish / Unpublish Metric. | ✅ | ✅ | ❌ |
Grant permissions to others. | ✅ | ✅ | ❌ |
Transfer Metric Owner. | ✅ | ❌ | ❌ |
Delete Metric. | ✅ | ❌ | ❌ |
Catalog and Semantic Layer Collaboration
The design principle of the semantic layer is "Creation requires Catalog permission, while consumption does not":
Scenario | Required Catalog permission | Required semantic layer permission |
Creating a Model. | Table.Select | Semantic modeling feature permission |
Managing Models (Granted Manage) | Table.Select + Table.Browse | Manage permission point of the model |
Creating a Metric (Granted CreateMetric) | Not required | CreateMetric permission point of the model |
Query Metric Data. | Not required | Query permission point of the metric |
Direct Table Query with NL2SQL | Table.Select + Table.Browse | Not required |
Tip
About Table.Browse: Browse is a preview permission on underlying tables at the Catalog level, independent of the full read permission of Select. In scenarios such as editing, publishing, and taking models offline where access to the underlying table structure is required, model Manage users must have the Browse permission in addition to Select. Otherwise, their operations will be blocked.
Therefore, even if a user's Select permission on underlying tables in the Catalog is revoked, queries on published metrics can still be executed normally, ensuring business continuity.
References
Create a semantic model.
Semantic Model Application