mcpField
S
semantic-layer-usage

semantic-layer-usage

github.com/keboolaData & databases17166 installsUpdated 1d ago
Repository

About semantic-layer-usage

semantic-layer-usage is a skill for using Keboola's semantic layer without confusing business labels with physical database columns. It emphasizes checking dataset mappings and using metric SQL definitions before embedding queries in code.

Key features

  1. 01Check physical columns via tableId
  2. 02Use metric SQL definitions verbatim
  3. 03Distinguish labels from database columns
  4. 04Validate mappings before writing queries

Use cases

  1. 01Building dashboards from semantic models
  2. 02Writing queries for semantic datasets
  3. 03Embedding metric SQL in applications
  4. 04Handling searches with no matching model

MCP support

It guides use of the Keboola MCP semantic-layer workflow, including context search and inspection. It also recommends checking the dataset's physical columns with `get_table` and using the metric SQL provided by the semantic context.

Install

Copy the command and run it in a terminal.

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

After installing, type/semantic-layer-usagein Claude Code to confirm it loaded.

Details

From the project README

Using the Keboola semantic layer safely

The Keboola MCP system prompt already documents the semantic-layer workflow (discover with search_semantic_context, inspect with get_semantic_context, validate_semantic_query, then query_data). This skill adds the one failure mode that workflow does not spell out.

The semantic layer already carries the physical mapping — use it, don't bypass it. A semantic-dataset returns its tableId and fqn; a semantic-metric returns its SQL. The business-facing display names (a field labelled Total Revenue, an entity Trips) are not the physical columns — they are labels on top of the definition. The failure is writing SQL from those labels instead of from the definition the tools already gave you.

The one rule

Before you embed any SQL into app, transformation, or report code, confirm the real column names against Keboola MCP — e.g. get_table on the dataset's tableId — and use the metric's SQL verbatim rather than reinventing it. If search_semantic_context returns nothing relevant, there is no model to consult: say so and work against raw Storage. How you batch those checks is up to you.

Worked example — the failure this skill prevents

A user asked Kai to build a dashboard from the semantic layer over out.c-nyc-aggregations-duckdb.rpt_* tables. Kai read the semantic context but wrote the dashboard SQL from the semantic display names, never confirming the physical columns. They didn't match the rpt_* schema, so every query failed: the dashboard rendered empty even though the container was "running", and Kai reported success without verifying.

What grounds it instead:

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)

The label the user thinks in ("revenue") is the physical column fare_total; the semantic definition tells you that — read it instead of guessing.

Related

  • dataapp-development skill — full app lifecycle; its ../dataapp-development/references/storage-access.md covers FQN quoting per backend and ../dataapp-development/references/dev-workflow.md covers the validate-first loop. Load this skill alongside it when the data source is a semantic model.

Comments

Markdown supported