mcpField
S
semantic-layer-usage

semantic-layer-usage

github.com/keboola数据与数据库17166 次安装1 天前更新
代码仓库

关于 semantic-layer-usage

semantic-layer-usage 是一项技能，帮助使用 Keboola 语义层时避免将业务标签误当作数据库物理列。它强调核对数据集映射，并在将查询写入代码前采用指标定义中的 SQL。

主要功能

  1. 01通过 tableId 核对物理列
  2. 02直接使用指标 SQL 定义
  3. 03区分标签与数据库列
  4. 04编写查询前确认映射

适用场景

  1. 01基于语义模型构建仪表板
  2. 02为语义数据集编写查询
  3. 03在应用中嵌入指标 SQL
  4. 04搜索不到匹配模型时处理数据

MCP 相关

该技能指导使用 Keboola MCP 的语义层流程，包括搜索和检查上下文。它还建议通过 `get_table` 核对数据集的物理列，并使用语义上下文提供的指标 SQL。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/keboola/ai-kit --skill semantic-layer-usage

安装后在 Claude Code 中输入/semantic-layer-usage确认已加载。

详细介绍

安全使用 Keboola 语义层

Keboola MCP 系统提示词已经说明了语义层工作流 （使用 search_semantic_context 发现，通过 get_semantic_context 检查， 再使用 validate_semantic_query 验证，然后执行 query_data）。此技能补充了该工作流 未明确说明的一种失败模式。

语义层已经包含物理映射——请使用它，不要绕过它。 semantic-dataset 会返回其 tableId 和 fqn；semantic-metric 会返回其 SQL。面向业务的显示名称（标记为 Total Revenue 的字段、名为 Trips 的实体）并不是物理列—— 它们只是定义之上的标签。问题在于根据这些标签编写 SQL，而不是依据工具已经提供的定义。

唯一规则

在将任何 SQL 嵌入应用、转换或报告代码之前，请通过 Keboola MCP 确认真实列名—— 例如，对数据集的 tableId 调用 get_table——并原样使用指标的 SQL，不要重新编写。如果 search_semantic_context 没有返回相关内容，就没有可供参考的模型：请说明这一点，并针对原始 Storage 开展工作。如何批量执行这些检查，由你决定。

示例——此技能旨在避免的失败

一位用户要求 Kai 基于语义层构建一个仪表板，数据来自 out.c-nyc-aggregations-duckdb.rpt_* 表。Kai 阅读了语义上下文，却根据语义显示名称编写仪表板 SQL，没有确认物理列。这些名称与 rpt_* 架构不匹配，因此所有查询都失败了：尽管容器显示“正在运行”，仪表板仍然空白，而 Kai 未经验证便报告成功。

应以此为依据：

search_semantic_context(patterns=["nyc trips", "daily revenue"])
  → metric "daily_revenue", dataset with tableId out.c-nyc-aggregations-duckdb.rpt_daily
get_semantic_context(...)  → metric SQL + dataset tableId + fqn (the physical mapping)
get_table(table_id="out.c-nyc-aggregations-duckdb.rpt_daily")
  → real columns: pickup_date, fare_total, trip_count  (NOT the display labels)

用户认知中的标签（“revenue”）对应的物理列是 fare_total；语义定义会告诉你这一点——请阅读定义，不要猜测。

相关内容

  • dataapp-development 技能——完整的应用生命周期；其中的 ../dataapp-development/references/storage-access.md 介绍各后端的 FQN 引用方式， ../dataapp-development/references/dev-workflow.md 介绍先验证的工作循环。若数据源是语义模型，请同时加载此技能。

评论

支持 Markdown