与 AI 功能集成
语义视图提供了业务友好的查询层，与 AI 功能的结合主要有三种方式：直接在 SQL 中调用 AI 函数处理语义查询结果、通过 CZ-CLI 让 AI Agent 操作语义视图、通过 MCP Server 工具集成到 AI 工作流。
AI_COMPLETE 组合查询
semantic_view()
semantic_view()
的查询结果是普通结果集，可以直接在
SELECT
SELECT
列表中调用
AI_COMPLETE
AI_COMPLETE
对每行数据进行 AI 处理。
典型场景：对语义视图返回的指标结果做自然语言解读、异常分析或摘要生成。
-- 对每个部门的薪资数据生成 AI 分析评语
SELECT
department,
avg_salary,
AI_COMPLETE(
'<model-name>',
'请用一句话评价该部门薪资水平，部门：' || department
|| '，平均薪资：' || CAST(avg_salary AS STRING) || ' 元'
) AS ai_comment
FROM semantic_view(
doc_test.emp_dept_analysis,
DIMENSIONS emps.department,
METRICS emps.avg_salary
);
需要先配置 AI Gateway 并指定有效的模型名称。详见 AI 函数。
也可以将语义视图结果物化后再做批量 AI 处理：
-- 先物化查询结果
CREATE TABLE doc_test.dept_stats AS
SELECT * FROM semantic_view(
doc_test.emp_dept_analysis,
DIMENSIONS emps.department,
METRICS emps.avg_salary,
METRICS emps.total_employees
);
-- 再批量调用 AI 函数
SELECT department, AI_COMPLETE('<model>', '分析：' || department || ' 部门有 '
|| CAST(total_employees AS STRING) || ' 人，平均薪资 '
|| CAST(avg_salary AS STRING)) AS insight
FROM doc_test.dept_stats;
通过 CZ-CLI 使用
CZ-CLI 是当前推荐的 AI Agent 接入方式，支持自然语言驱动对语义视图的完整操作。
# 查看当前 schema 下的语义视图
cz-cli agent run "列出 doc_test schema 下所有语义视图" --profile aliyun_shanghai_prod
# 查询语义视图
cz-cli agent run "查询 doc_test.emp_dept_analysis，按部门统计员工数和平均薪资" \
--profile aliyun_shanghai_prod
# 创建语义视图
cz-cli agent run "在 doc_test 下创建一个分析员工薪资的语义视图，包含部门维度和平均薪资指标" \
--profile aliyun_shanghai_prod
详见 CZ-CLI 文档。
MCP Server 工具
云器 Lakehouse MCP Server 提供了一套专门面向语义视图的工具，可集成至 AI Agent 框架（Dify、N8N、Claude Desktop 等）。详见 MCP Server 文档。
工具总览
| 工具名称 | 操作 | 说明 |
|---|
LH-create-semantic-view
LH-create-semantic-view | 创建 | 从 YAML 定义创建语义视图 |
LH-desc-semantic-view
LH-desc-semantic-view | 查看 | 获取视图完整 YAML 定义 |
LH-desc-logical-table
LH-desc-logical-table | 查看 | 获取逻辑表结构与关系 |
LH-brief-semantic-view
LH-brief-semantic-view | 查看 | 快速浏览维度与指标字段 |
LH-get_semantic_view_dims
LH-get_semantic_view_dims | 查看 | 获取结构化维度列表 |
LH-semantic-view-dim-add
LH-semantic-view-dim-add | 修改 | 动态追加维度（无需重建） |
LH-semantic-view-dim-del
LH-semantic-view-dim-del | 修改 | 动态删除维度（无需重建） |
LH-query-semantic-value
LH-query-semantic-value | 查询 | 结构化参数驱动查询，Agent 推荐方式 |
典型 Agent 工作流
1. LH-brief-semantic-view → 了解视图有哪些维度和指标
2. LH-query-semantic-value → 按需查询，传入维度/指标/过滤条件
3. LH-semantic-view-dim-add → 若缺少所需维度，动态添加
4. LH-desc-semantic-view → 导出 YAML 用于备份或版本比对
5. LH-create-semantic-view → 基于 YAML 在新环境重建视图
LH-query-semantic-value
这是 AI Agent 查询语义视图的推荐方式，无需手写
semantic_view()
semantic_view()
SQL：
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
semantic_view_name
semantic_view_name | string | ✅ | 语义视图名称 |
selected_dimensions
selected_dimensions | array | ✅ | 要查询的维度列表 |
selected_metrics
selected_metrics | array | ✅ | 要查询的指标列表 |
filter_conditions
filter_conditions | array | — | 过滤条件（默认为空） |
示例：
mcp.call("LH-query-semantic-value",
semantic_view_name="tpch_rev_analysis",
selected_dimensions=[
{"logical_table": "customers", "dimensions_name": "customer_name"},
{"logical_table": "customers", "dimensions_name": "customer_city"}
],
selected_metrics=[
{"logical_table": "orders", "metrics_name": "order_average_value"}
],
filter_conditions=[
{"field_name": "customer_city", "expr": "= 'New York'"}
]
)
等效 SQL：
SELECT * FROM semantic_view(
tpch_rev_analysis,
DIMENSIONS customers.customer_name,
DIMENSIONS customers.customer_city,
METRICS orders.order_average_value
) WHERE customer_city = 'New York';
LH-semantic-view-dim-add
动态向已有语义视图追加维度，无需重建视图：
mcp.call("LH-semantic-view-dim-add",
semantic_view_name="tpch_rev_analysis",
dimensions=[{
"logical_table": "customers",
"dimension_name": "customer_city",
"column_name": "c_city",
"synonyms": ["city", "customer city"],
"comment": "City of the customer"
}]
)
LH-create-semantic-view
从 YAML 定义创建语义视图，适合声明式配置或跨环境迁移：
mcp.call("LH-create-semantic-view",
semantic_view_yaml=open("semantic_view.yaml").read(),
schema_name="my_schema"
)
YAML 格式兼容 Snowflake Cortex Analyst 规范。用
LH-desc-semantic-view
LH-desc-semantic-view
可将现有视图导出为 YAML。
相关文档
