@clickzetta/cz-cli-darwin-x64 0.3.92 → 0.3.93

package/bin/skills/clickzetta-semantic-view/SKILL.md

@@ -1,79 +1,81 @@
 ---
 name: clickzetta-semantic-view
 description: |
-  创建和查询 ClickZetta Lakehouse 语义视图（Semantic View）。语义视图是架构级逻辑
-  数据模型对象，通过声明逻辑表、维度、指标、过滤器，将复杂的多表 JOIN 和聚合逻辑封装
-  为业务友好的语义层，使用 semantic_view() 函数查询，无需手写 JOIN。
-  当前为邀测功能（1.3 版本起）。
-  当用户说"创建语义视图"、"semantic view"、"语义层"、"定义指标"、"定义维度"、
-  "semantic_view() 怎么用"、"统一指标口径"、"业务语义模型"、"逻辑表"、
-  "DIMENSIONS"、"METRICS"、"FILTERS"、"DROP SEMANTIC VIEW"、
-  "SHOW SEMANTIC VIEWS"时触发。
+  Create and query ClickZetta Lakehouse Semantic Views. A Semantic View is a schema-level logical
+  data model object that encapsulates complex multi-table JOINs and aggregation logic into a
+  business-friendly semantic layer by declaring logical tables, dimensions, metrics, and filters.
+  Query using the semantic_view() function without writing JOINs manually.
+  Currently in invite-only preview (since version 1.3).
+  Triggered when user says "create semantic view", "semantic view", "semantic layer",
+  "define metrics", "define dimensions", "how to use semantic_view()",
+  "unified metric definitions", "business semantic model", "logical table",
+  "DIMENSIONS", "METRICS", "FILTERS", "DROP SEMANTIC VIEW",
+  "SHOW SEMANTIC VIEWS".
   Keywords: semantic view, dimension, metric, logical model, unified metrics, semantic layer
 ---
 
-# ClickZetta 语义视图（Semantic View）
+# ClickZetta Semantic View
 
-阅读 [references/semantic-view-reference.md](references/semantic-view-reference.md) 了解完整语法。
+Read [references/semantic-view-reference.md](references/semantic-view-reference.md) for the complete syntax reference.
 
 ---
 
-## 概述
+## Overview
 
-语义视图是 ClickZetta Lakehouse 的**架构级逻辑数据模型对象**，解决两类核心问题：
+A Semantic View is a **schema-level logical data model object** in ClickZetta Lakehouse that solves two core problems:
 
-- **数据分析**：统一维度和指标定义，业务用户无需编写复杂 JOIN 即可查询跨表数据
-- **数据治理**：集中管理表关系、维度、指标定义，确保全组织使用相同数据口径
+- **Data Analysis**: Unifies dimension and metric definitions so business users can query cross-table data without writing complex JOINs
+- **Data Governance**: Centrally manages table relationships, dimension and metric definitions, ensuring the entire organization uses consistent data definitions
 
-> ⚠️ 当前为**邀测功能**（1.3 版本），需联系技术支持开通。
+> ⚠️ Currently in **invite-only preview** (version 1.3). Contact technical support to enable.
 
 ---
 
-## 四大组件
+## Four Core Components
 
-| 组件 | 关键字 | 说明 |
+| Component | Keyword | Description |
 |---|---|---|
-| 逻辑表 | `TABLES` | 映射物理表，声明主键和外键关系，引擎自动处理 JOIN |
-| 维度 | `DIMENSIONS` | 分类属性（谁/什么/哪里/何时），支持计算维度 |
-| 指标 | `METRICS` | 聚合度量（SUM/AVG/COUNT/MIN/MAX），业务 KPI |
-| 过滤器 | `FILTERS` | 预定义可重用过滤条件（语义注解，不可直接传入查询） |
+| Logical Tables | `TABLES` | Maps physical tables, declares primary and foreign key relationships; the engine handles JOINs automatically |
+| Dimensions | `DIMENSIONS` | Categorical attributes (who/what/where/when), supports computed dimensions |
+| Metrics | `METRICS` | Aggregate measures (SUM/AVG/COUNT/MIN/MAX), business KPIs |
+| Filters | `FILTERS` | Predefined reusable filter conditions (semantic annotations, cannot be passed directly to queries) |
 
 ---
 
-## 创建语义视图
+## Creating a Semantic View
 
 ```sql
-CREATE SEMANTIC VIEW <视图名>
+CREATE SEMANTIC VIEW <view_name>
 TABLES (
-    <表别名> AS <schema>.<物理表>
-        PRIMARY KEY (<列名>)
-        [ FOREIGN KEY (<列名>) REFERENCES <其他表别名> ]
-        [ WITH SYNONYMS ('<同义词>') ]
-        [ COMMENT = '<说明>' ]
+    <table_alias> AS <schema>.<physical_table>
+        PRIMARY KEY (<column_name>)
+        [ FOREIGN KEY (<column_name>) REFERENCES <other_table_alias> ]
+        [ WITH SYNONYMS ('<synonym>') ]
+        [ COMMENT = '<description>' ]
     [ , ... ]
 )
 [ FILTERS (
-    <表别名>.<过滤器名> AS <布尔表达式>
+    <table_alias>.<filter_name> AS <boolean_expression>
     [ , ... ]
 ) ]
 DIMENSIONS (
-    { <表别名>.<维度名> | <维度名> } AS <表达式>
-        [ WITH SYNONYMS = ('<同义词>' [ , ... ]) ]
+    { <table_alias>.<dimension_name> | <dimension_name> } AS <expression>
+        [ WITH SYNONYMS = ('<synonym>' [ , ... ]) ]
         [ is_unique = { true | false } ]
         [ is_time = { true | false } ]
-        [ enum_values = [ <值1>, <值2>, ... ] ]
-        [ COMMENT = '<说明>' ]
+        [ enum_values = [ <value1>, <value2>, ... ] ]
+        [ COMMENT = '<description>' ]
     [ , ... ]
 )
 METRICS (
-    <表别名>.<指标名> AS <聚合表达式>
-        [ COMMENT = '<说明>' ]
+    <table_alias>.<metric_name> AS <aggregate_expression>
+        [ COMMENT = '<description>' ]
     [ , ... ]
 )
-[ COMMENT = '<视图说明>' ];
+[ COMMENT = '<view_description>' ];
 ```
 
-### 完整示例（TPC-H 收入分析）
+### Complete Example (TPC-H Revenue Analysis)
 
 ```sql
 DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis;
@@ -81,60 +83,60 @@ CREATE SEMANTIC VIEW tpch_rev_analysis
 TABLES (
     customers AS tpch.customer
         PRIMARY KEY (c_custkey)
-        COMMENT = '客户主表',
+        COMMENT = 'Customer master table',
     orders AS tpch.orders
         PRIMARY KEY (o_orderkey)
         FOREIGN KEY (o_custkey) REFERENCES customers
-        WITH SYNONYMS ('销售订单')
-        COMMENT = '订单表',
+        WITH SYNONYMS ('sales orders')
+        COMMENT = 'Orders table',
     line_items AS tpch.lineitem
         PRIMARY KEY (l_orderkey, l_linenumber)
         FOREIGN KEY (l_orderkey) REFERENCES orders
-        COMMENT = '订单明细'
+        COMMENT = 'Order line items'
 )
 FILTERS (
     customers.is_building AS customers.c_mktsegment = 'BUILDING'
 )
 DIMENSIONS (
     customers.customer_name AS c_name
-        WITH SYNONYMS = ('客户名称', 'customer name')
+        WITH SYNONYMS = ('customer name')
         is_unique = true
-        COMMENT = '客户名称',
+        COMMENT = 'Customer name',
     orders.order_date AS o_orderdate
         is_time = true
-        COMMENT = '下单日期',
+        COMMENT = 'Order date',
     orders.order_year AS YEAR(o_orderdate)
-        COMMENT = '下单年份',
+        COMMENT = 'Order year',
     orders.order_status AS o_orderstatus
         enum_values = ['O', 'F', 'P']
-        COMMENT = '订单状态'
+        COMMENT = 'Order status'
 )
 METRICS (
     customers.customer_count AS COUNT(c_custkey)
-        COMMENT = '客户总数',
+        COMMENT = 'Total customer count',
     orders.avg_order_value AS AVG(o_totalprice)
-        COMMENT = '平均订单金额',
+        COMMENT = 'Average order value',
     orders.total_revenue AS SUM(o_totalprice)
-        COMMENT = '总收入'
+        COMMENT = 'Total revenue'
 )
-COMMENT = '收入分析语义视图';
+COMMENT = 'Revenue analysis semantic view';
 ```
 
 ---
 
-## 查询语义视图
+## Querying a Semantic View
 
-使用 `semantic_view()` 表函数，**无需手写 JOIN 和 GROUP BY**：
+Use the `semantic_view()` table function — **no need to write JOINs or GROUP BY manually**:
 
 ```sql
--- 基础查询：按订单日期统计平均订单金额
+-- Basic query: average order value by order date
 SELECT * FROM semantic_view(
     tpch_rev_analysis,
     DIMENSIONS orders.order_date,
     METRICS orders.avg_order_value
 );
 
--- 多维度查询：按日期和客户名称
+-- Multi-dimension query: by date and customer name
 SELECT * FROM semantic_view(
     tpch_rev_analysis,
     DIMENSIONS orders.order_date,
@@ -142,7 +144,7 @@ SELECT * FROM semantic_view(
     METRICS orders.avg_order_value
 );
 
--- 使用短名称（名称唯一时可省略表别名前缀）
+-- Using short names (table alias prefix can be omitted when names are unique)
 SELECT * FROM semantic_view(
     tpch_rev_analysis,
     DIMENSIONS order_date,
@@ -150,7 +152,7 @@ SELECT * FROM semantic_view(
     METRICS avg_order_value
 );
 
--- 加 WHERE 过滤（需将过滤列定义为 DIMENSION）
+-- Adding WHERE filter (filter columns must be defined as DIMENSIONS)
 SELECT * FROM semantic_view(
     tpch_rev_analysis,
     DIMENSIONS customers.customer_name,
@@ -159,16 +161,16 @@ SELECT * FROM semantic_view(
 ) WHERE order_status = 'O';
 ```
 
-### 与传统 SQL 对比
+### Comparison with Traditional SQL
 
 ```sql
--- 传统 SQL（需手写 JOIN + GROUP BY）
+-- Traditional SQL (requires manual JOIN + GROUP BY)
 SELECT o.o_orderdate, c.c_name, AVG(o.o_totalprice)
 FROM tpch.orders o
 JOIN tpch.customer c ON o.o_custkey = c.c_custkey
 GROUP BY o.o_orderdate, c.c_name;
 
--- 语义视图（自动处理 JOIN 和聚合）
+-- Semantic View (JOINs and aggregation handled automatically)
 SELECT * FROM semantic_view(
     tpch_rev_analysis,
     DIMENSIONS order_date,
@@ -179,29 +181,29 @@ SELECT * FROM semantic_view(
 
 ---
 
-## 管理命令
+## Management Commands
 
 ```sql
--- 删除（推荐先删再建，确保幂等）
+-- Drop (recommended: drop before create for idempotency)
 DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis;
 
--- 列出当前 Schema 的所有语义视图
+-- List all semantic views in the current schema
 SHOW SEMANTIC VIEWS;
 SHOW SEMANTIC VIEWS IN my_schema;
 
--- 查看详细定义（逻辑表、维度、指标、外键）
+-- View detailed definition (logical tables, dimensions, metrics, foreign keys)
 DESC EXTENDED tpch_rev_analysis;
 ```
 
 ---
 
-## 注意事项
+## Important Notes
 
-1. **TABLES 定义顺序**：被外键引用的表必须先定义（如 `customers` 必须在 `orders` 之前）
-2. **FILTERS 是语义注解**：`FILTERS` 中的命名过滤器不能作为 `semantic_view()` 的参数，WHERE 子句只能引用 `DIMENSIONS` 中定义的列名（短名），不能用物理列名
-3. **WHERE 只能用 DIMENSION 短名**：`WHERE customer_name = 'Alice'` ✅，`WHERE c_name = 'Alice'` ❌
-4. **短名称 vs 限定名称**：名称在视图内唯一时可用短名称，有冲突时必须用 `表别名.名称`
-5. **幂等创建**：始终先 `DROP SEMANTIC VIEW IF EXISTS` 再创建，避免重复执行报错
-6. **计算维度**：DIMENSIONS 支持表达式，如 `YEAR(CAST(order_date AS DATE))` 提取年份
-7. **指标聚合函数**：仅支持 `COUNT`、`AVG`、`SUM`、`MIN`、`MAX`
-8. **DIMENSIONS 和 METRICS 可单独使用**：可以只查 METRICS（全局聚合），也可以只查 DIMENSIONS（去重列表）
+1. **TABLES definition order**: Tables referenced by foreign keys must be defined first (e.g., `customers` must come before `orders`)
+2. **FILTERS are semantic annotations**: Named filters in `FILTERS` cannot be passed as parameters to `semantic_view()`; WHERE clauses can only reference column short names defined in `DIMENSIONS`, not physical column names
+3. **WHERE only accepts DIMENSION short names**: `WHERE customer_name = 'Alice'` ✅, `WHERE c_name = 'Alice'` ❌
+4. **Short names vs qualified names**: Use short names when unique within the view; use `table_alias.name` when there are conflicts
+5. **Idempotent creation**: Always `DROP SEMANTIC VIEW IF EXISTS` before creating to avoid errors on repeated execution
+6. **Computed dimensions**: DIMENSIONS supports expressions, e.g., `YEAR(CAST(order_date AS DATE))` to extract year
+7. **Metric aggregate functions**: Only `COUNT`, `AVG`, `SUM`, `MIN`, `MAX` are supported
+8. **DIMENSIONS and METRICS can be used independently**: You can query only METRICS (global aggregation) or only DIMENSIONS (deduplicated list)

package/bin/skills/clickzetta-semantic-view/eval_cases.jsonl

@@ -1,12 +1,12 @@
-{"case_id":"001","type":"should_call","user_input":"怎么创建语义视图","expected_skill":"clickzetta-semantic-view","expected_output_contains":["CREATE SEMANTIC VIEW"]}
-{"case_id":"002","type":"should_call","user_input":"semantic_view() 函数怎么查询","expected_skill":"clickzetta-semantic-view","expected_output_contains":["semantic_view"]}
-{"case_id":"003","type":"should_call","user_input":"语义视图里怎么定义维度和指标","expected_skill":"clickzetta-semantic-view","expected_output_contains":["DIMENSIONS","METRICS"]}
-{"case_id":"004","type":"should_call","user_input":"怎么用语义层统一指标口径","expected_skill":"clickzetta-semantic-view","expected_output_contains":["语义"]}
-{"case_id":"005","type":"should_call","user_input":"SHOW SEMANTIC VIEWS 怎么用","expected_skill":"clickzetta-semantic-view","expected_output_contains":["SHOW SEMANTIC VIEWS"]}
-{"case_id":"006","type":"should_call","user_input":"语义视图的 FILTERS 怎么定义","expected_skill":"clickzetta-semantic-view","expected_output_contains":["FILTERS"]}
-{"case_id":"007","type":"should_call","user_input":"DROP SEMANTIC VIEW 怎么删除","expected_skill":"clickzetta-semantic-view","expected_output_contains":["DROP SEMANTIC VIEW"]}
-{"case_id":"008","type":"should_not_call","user_input":"怎么创建普通视图","forbidden_skill":"clickzetta-semantic-view"}
-{"case_id":"009","type":"should_not_call","user_input":"帮我写一个数据看板","forbidden_skill":"clickzetta-semantic-view"}
-{"case_id":"010","type":"should_not_call","user_input":"怎么做数据建模","forbidden_skill":"clickzetta-semantic-view"}
-{"case_id":"011","type":"should_not_call","user_input":"Superset 怎么连接","forbidden_skill":"clickzetta-semantic-view"}
-{"case_id":"012","type":"should_not_call","user_input":"怎么创建物化视图","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"001","type":"should_call","user_input":"How to create a semantic view","expected_skill":"clickzetta-semantic-view","expected_output_contains":["CREATE SEMANTIC VIEW"]}
+{"case_id":"002","type":"should_call","user_input":"How to query with semantic_view() function","expected_skill":"clickzetta-semantic-view","expected_output_contains":["semantic_view"]}
+{"case_id":"003","type":"should_call","user_input":"How to define dimensions and metrics in a semantic view","expected_skill":"clickzetta-semantic-view","expected_output_contains":["DIMENSIONS","METRICS"]}
+{"case_id":"004","type":"should_call","user_input":"How to use the semantic layer to unify metric definitions","expected_skill":"clickzetta-semantic-view","expected_output_contains":["semantic"]}
+{"case_id":"005","type":"should_call","user_input":"How to use SHOW SEMANTIC VIEWS","expected_skill":"clickzetta-semantic-view","expected_output_contains":["SHOW SEMANTIC VIEWS"]}
+{"case_id":"006","type":"should_call","user_input":"How to define FILTERS in a semantic view","expected_skill":"clickzetta-semantic-view","expected_output_contains":["FILTERS"]}
+{"case_id":"007","type":"should_call","user_input":"How to drop a semantic view with DROP SEMANTIC VIEW","expected_skill":"clickzetta-semantic-view","expected_output_contains":["DROP SEMANTIC VIEW"]}
+{"case_id":"008","type":"should_not_call","user_input":"How to create a regular view","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"009","type":"should_not_call","user_input":"Help me build a data dashboard","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"010","type":"should_not_call","user_input":"How to do data modeling","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"011","type":"should_not_call","user_input":"How to connect Superset","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"012","type":"should_not_call","user_input":"How to create a materialized view","forbidden_skill":"clickzetta-semantic-view"}

package/bin/skills/clickzetta-semantic-view/references/semantic-view-reference.md

@@ -1,61 +1,61 @@
-# 语义视图完整语法参考
+# Semantic View Complete Syntax Reference
 
-> 来源：https://www.yunqi.tech/documents/semantic_view
-> 功能状态：邀测（1.3 版本起）
+> Source: https://www.yunqi.tech/documents/semantic_view
+> Feature status: Invite-only preview (since version 1.3)
 
 ---
 
-## CREATE SEMANTIC VIEW 完整语法
+## CREATE SEMANTIC VIEW Full Syntax
 
 ```sql
-CREATE SEMANTIC VIEW <视图名称>
+CREATE SEMANTIC VIEW <view_name>
 TABLES (
-    <逻辑表定义> [ , ... ]
+    <logical_table_definition> [ , ... ]
 )
 [ FILTERS (
-    <过滤器定义> [ , ... ]
+    <filter_definition> [ , ... ]
 ) ]
 DIMENSIONS (
-    <维度定义> [ , ... ]
+    <dimension_definition> [ , ... ]
 )
 METRICS (
-    <指标定义> [ , ... ]
+    <metric_definition> [ , ... ]
 )
-[ COMMENT = '<视图说明>' ];
+[ COMMENT = '<view_description>' ];
 ```
 
-**约束**：`DIMENSIONS` 和 `METRICS` 至少包含其中一个。
+**Constraint**: At least one of `DIMENSIONS` or `METRICS` must be included.
 
 ---
 
-## 逻辑表定义语法
+## Logical Table Definition Syntax
 
 ```sql
-<表别名> AS <schema>.<物理表名>
-    PRIMARY KEY ( <列名> [ , ... ] )
-    [ FOREIGN KEY ( <列名> ) REFERENCES <其他逻辑表别名> ]
-    [ WITH SYNONYMS ( '<同义词>' [ , ... ] ) ]
-    [ COMMENT = '<说明>' ]
+<table_alias> AS <schema>.<physical_table_name>
+    PRIMARY KEY ( <column_name> [ , ... ] )
+    [ FOREIGN KEY ( <column_name> ) REFERENCES <other_logical_table_alias> ]
+    [ WITH SYNONYMS ( '<synonym>' [ , ... ] ) ]
+    [ COMMENT = '<description>' ]
 ```
 
-| 参数 | 说明 |
+| Parameter | Description |
 |---|---|
-| `<表别名> AS <schema>.<物理表>` | 为物理表指定逻辑别名，后续维度/指标/外键均用此别名引用 |
-| `PRIMARY KEY` | 主键列，用于确定表间关系类型（一对多/一对一） |
-| `FOREIGN KEY ... REFERENCES` | 外键关系，引擎据此自动处理 JOIN；引用目标必须是逻辑表别名 |
-| `WITH SYNONYMS` | 逻辑表同义词，增强可发现性 |
+| `<table_alias> AS <schema>.<physical_table>` | Assigns a logical alias to a physical table; dimensions/metrics/foreign keys reference this alias |
+| `PRIMARY KEY` | Primary key columns, used to determine relationship types between tables (one-to-many/one-to-one) |
+| `FOREIGN KEY ... REFERENCES` | Foreign key relationship; the engine uses this to handle JOINs automatically; target must be a logical table alias |
+| `WITH SYNONYMS` | Logical table synonyms to enhance discoverability |
 
-**注意**：被外键引用的表必须在 TABLES 子句中先定义。
+**Note**: Tables referenced by foreign keys must be defined first in the TABLES clause.
 
 ---
 
-## 过滤器定义语法
+## Filter Definition Syntax
 
 ```sql
-<逻辑表别名>.<过滤器名> AS <布尔表达式>
+<logical_table_alias>.<filter_name> AS <boolean_expression>
 ```
 
-示例：
+Example:
 ```sql
 FILTERS (
     customers.is_building AS customers.c_mktsegment = 'BUILDING',
@@ -63,105 +63,105 @@ FILTERS (
 )
 ```
 
-**重要**：FILTERS 是面向 AI/元数据层的语义注解，**不能**作为 `semantic_view()` 函数参数直接传入。若要在查询中过滤，需将对应列定义为 DIMENSION，再用外层 WHERE 子句。
+**Important**: FILTERS are semantic annotations for AI/metadata layers and **cannot** be passed directly as parameters to the `semantic_view()` function. To filter in queries, define the corresponding column as a DIMENSION and use an outer WHERE clause.
 
 ---
 
-## 维度定义语法
+## Dimension Definition Syntax
 
 ```sql
-{ <逻辑表别名>.<维度名> | <维度名> } AS <表达式>
-    [ WITH SYNONYMS = ( '<同义词>' [ , ... ] ) ]
+{ <logical_table_alias>.<dimension_name> | <dimension_name> } AS <expression>
+    [ WITH SYNONYMS = ( '<synonym>' [ , ... ] ) ]
     [ is_unique = { true | false } ]
     [ is_time = { true | false } ]
-    [ enum_values = [ <值1>, <值2>, ... ] ]
-    [ COMMENT = '<说明>' ]
+    [ enum_values = [ <value1>, <value2>, ... ] ]
+    [ COMMENT = '<description>' ]
 ```
 
-| 参数 | 说明 |
+| Parameter | Description |
 |---|---|
-| `AS <表达式>` | 可以是列名，也可以是计算表达式（如 `YEAR(o_orderdate)`） |
-| `WITH SYNONYMS` | 维度同义词，用户可用不同业务术语引用同一维度 |
-| `is_unique = true` | 标识该维度值唯一（如客户名称），帮助引擎优化 |
-| `is_time = true` | 标识为时间类型维度（如订单日期） |
-| `enum_values` | 限定允许的枚举值，提升查询准确性 |
+| `AS <expression>` | Can be a column name or a computed expression (e.g., `YEAR(o_orderdate)`) |
+| `WITH SYNONYMS` | Dimension synonyms allowing users to reference the same dimension with different business terms |
+| `is_unique = true` | Indicates the dimension values are unique (e.g., customer name), helps the engine optimize |
+| `is_time = true` | Identifies as a time-type dimension (e.g., order date) |
+| `enum_values` | Restricts allowed enumeration values, improves query accuracy |
 
 ---
 
-## 指标定义语法
+## Metric Definition Syntax
 
 ```sql
-<逻辑表别名>.<指标名> AS <聚合表达式>
-    [ COMMENT = '<说明>' ]
+<logical_table_alias>.<metric_name> AS <aggregate_expression>
+    [ COMMENT = '<description>' ]
 ```
 
-支持的聚合函数：`COUNT`、`AVG`、`SUM`、`MIN`、`MAX`
+Supported aggregate functions: `COUNT`, `AVG`, `SUM`, `MIN`, `MAX`
 
-示例：
+Example:
 ```sql
 METRICS (
     orders.total_revenue AS SUM(o_totalprice)
-        COMMENT = '总收入',
+        COMMENT = 'Total revenue',
     orders.avg_order_value AS AVG(o_totalprice)
-        COMMENT = '平均订单金额',
+        COMMENT = 'Average order value',
     customers.customer_count AS COUNT(c_custkey)
-        COMMENT = '客户总数'
+        COMMENT = 'Total customer count'
 )
 ```
 
 ---
 
-## semantic_view() 查询函数语法
+## semantic_view() Query Function Syntax
 
 ```sql
 SELECT *
 FROM semantic_view(
-    <视图名称>,
-    DIMENSIONS <维度名> [ , DIMENSIONS <维度名> ... ],
-    METRICS <指标名> [ , METRICS <指标名> ... ]
+    <view_name>,
+    DIMENSIONS <dimension_name> [ , DIMENSIONS <dimension_name> ... ],
+    METRICS <metric_name> [ , METRICS <metric_name> ... ]
 )
-[ WHERE <过滤条件> ];
+[ WHERE <filter_condition> ];
 ```
 
-- 维度名可用限定名（`表别名.维度名`）或短名（名称唯一时）
-- 结果自动按指定维度分组，无需写 GROUP BY
-- WHERE 子句中的列名使用短名（不含表别名前缀）
+- Dimension names can use qualified names (`table_alias.dimension_name`) or short names (when unique)
+- Results are automatically grouped by specified dimensions — no GROUP BY needed
+- Column names in WHERE clauses use short names (without table alias prefix)
 
 ---
 
-## 管理命令
+## Management Commands
 
-| 命令 | 说明 |
+| Command | Description |
 |---|---|
-| `CREATE SEMANTIC VIEW` | 创建语义视图 |
-| `DROP SEMANTIC VIEW IF EXISTS <名称>` | 删除语义视图 |
-| `SHOW SEMANTIC VIEWS` | 列出当前 Schema 所有语义视图 |
-| `SHOW SEMANTIC VIEWS IN <schema>` | 列出指定 Schema 的语义视图 |
-| `DESC EXTENDED <名称>` | 查看详细定义（逻辑表/维度/指标/外键/索引） |
+| `CREATE SEMANTIC VIEW` | Create a semantic view |
+| `DROP SEMANTIC VIEW IF EXISTS <name>` | Drop a semantic view |
+| `SHOW SEMANTIC VIEWS` | List all semantic views in the current schema |
+| `SHOW SEMANTIC VIEWS IN <schema>` | List semantic views in a specified schema |
+| `DESC EXTENDED <name>` | View detailed definition (logical tables/dimensions/metrics/foreign keys/indexes) |
 
 ---
 
-## 最佳实践
+## Best Practices
 
 ```sql
--- 1. 幂等创建（始终先删再建）
+-- 1. Idempotent creation (always drop before create)
 DROP SEMANTIC VIEW IF EXISTS my_view;
 CREATE SEMANTIC VIEW my_view ...;
 
--- 2. 使用有意义的业务术语命名
--- 好：customer_name, total_revenue, order_date
--- 差：c_name, sum_totalprice, o_orderdate
+-- 2. Use meaningful business terminology for naming
+-- Good: customer_name, total_revenue, order_date
+-- Bad: c_name, sum_totalprice, o_orderdate
 
--- 3. 合理设置维度元数据
--- is_time=true 用于日期/时间维度
--- is_unique=true 用于主键类维度（如客户ID、订单号）
--- enum_values 用于状态类维度（如订单状态）
+-- 3. Set dimension metadata appropriately
+-- is_time=true for date/time dimensions
+-- is_unique=true for primary-key-like dimensions (e.g., customer ID, order number)
+-- enum_values for status-type dimensions (e.g., order status)
 
--- 4. 计算维度示例
+-- 4. Computed dimension examples
 DIMENSIONS (
-    orders.order_year AS YEAR(o_orderdate)   -- 从日期提取年份
-        COMMENT = '下单年份',
-    orders.order_month AS MONTH(o_orderdate) -- 从日期提取月份
-        COMMENT = '下单月份'
+    orders.order_year AS YEAR(o_orderdate)   -- Extract year from date
+        COMMENT = 'Order year',
+    orders.order_month AS MONTH(o_orderdate) -- Extract month from date
+        COMMENT = 'Order month'
 )
 ```