🧠 Semantic Layer

Beta

The semantic layer is in beta. It runs on Keboola’s multi-tenant stacks and is not offered on single-tenant stacks. The Semantic Layer section in the UI is enabled per project separately from the semantic layer itself, so your project can already hold a semantic model — one built by Kai, for example — before the section appears. If your project has no Semantic Layer section, contact our support team.

Keboola’s semantic layer lets you describe your project’s data in business terms — datasets, metrics, relationships, glossary terms, and business rules. Kai, AI assistants connected to your project through the MCP Server, and the Keboola CLI all read these definitions to understand what your data means, not just how it is stored.

Instead of every AI conversation having to rediscover which table holds revenue, how orders join to customers, or which business rules a query must respect, you define these facts once. Every AI assistant working with your project then grounds its answers — and the SQL it generates — in the same shared definitions.

Why use a semantic layer?

• Consistent answersA metric such as “net revenue” is defined once, as a SQL expression, and every AI-generated query uses the same definition.
• Business vocabularyGlossary terms teach the AI your company’s language, so questions asked in business terms resolve to the right data.
• Guardrails for AI-generated SQLConstraints capture business rules (for example, “profit must never exceed revenue”), and queries can be validated against them before they are executed.
• Less schema explorationThe AI spends less time inspecting raw tables and columns because the relevant context is already curated.

Core concepts

A semantic model is a collection of semantic objects stored centrally in Keboola. Six semantic object types make up a model:

Object type	What it describes
semantic-model	The top-level container for a set of semantic definitions. It also records the SQL dialect used by the model’s SQL expressions.
semantic-dataset	Maps a Keboola table (by table ID) to a business entity, including its fields and primary key.
semantic-metric	A named business calculation defined as a SQL expression over a dataset — for example, revenue, order count, or margin.
semantic-relationship	How two datasets join: the from/to datasets, the join type, and the join condition.
semantic-glossary	A business term and its definition — your company vocabulary.
semantic-constraint	A business rule with a severity (error, warning, or info) that queries can be checked against.

A project can contain multiple semantic models. Each object is a JSON document validated against a published JSON schema.

There is also a seventh type, semantic-reference-data — a per-dimension member store holding the full member list for a dimension, such as a chart of accounts. It is not part of a model’s build, export, or diff, and is managed with kbagent semantic-layer reference-data.

Building a semantic model

Start here: a project with no semantic model has nothing for an AI assistant to ground on, and the semantic MCP tools stay hidden until at least one model exists. There are four ways to build one.

With Kai

The quickest way is to ask Kai, the assistant built into Keboola. Kai builds and maintains semantic models from a chat inside your project, with nothing to install:

“Build a semantic model from the tables in the out.c-sales bucket.” “Add a net profit margin metric to the sales model, and a rule that flags a margin above 100%.”

Kai reads your buckets and tables, asks which numbers the business actually tracks, drafts the model, and validates it before writing anything. It then asks for your approval, and the approval card names the model and how many objects of each type the call will write, so you see the whole change before it happens. Editing, removing, and sharing objects in a model you already have work the same way: describe the change in plain language, review it, approve it. See Action approval.

A model Kai creates is visible only in the project it was created in. Kai can also share it read-only with named sibling projects, or with every project in your organization; widening a model to the whole organization requires an organization admin.

In the Keboola UI

Your project’s Semantic Layer section lists the project’s semantic models:

A model opens as one tab per object type — datasets, metrics, constraints, relationships, and glossary terms:

Objects open read-only, showing exactly the definition an AI assistant reads — a metric, for example, shows its SQL expression and description — and are edited explicitly via Edit. A Metadata tab tracks the object’s revision, schema version, and branch:

With the CLI

The Keboola CLI carries a semantic-layer command group covering the whole lifecycle without an AI in the loop — build a model from a list of storage tables, show, export, diff, validate, promote a model between projects, and add or edit individual metrics, datasets, relationships, constraints, and glossary terms. It also reads the model the way an assistant does, with search-context and get-context:

kbagent semantic-layer --help

With AI Kit plugins

Two AI Kit plugins cover the two most common starting points from an AI coding assistant such as Claude Code: building a model from scratch, and migrating one you already have.

Semantic Layer Toolkit (sl-toolkit)

The Semantic Layer Toolkit lets you build, inspect, validate, and edit semantic models from your assistant.

Commands

• /sl-build – A greenfield wizard that builds a new semantic model from your Keboola project: schema discovery → SQL analysis → generation → validation → push.
• /sl-show – Lists all datasets, metrics, relationships, constraints, and glossary terms in a model.
• /sl-validate – Checks a model for consistency issues such as references to non-existent fields or dangling relationships.

Conversational editing:

Adding, editing, and removing semantic objects doesn’t need commands — just describe the change:

“Add a metric for net profit margin on the KPI dashboard table.” “Rename the Revenue metric to Total Revenue.”

Note

/sl-build and /sl-validate --deep read your project’s schemas through the kbagent binary from the Keboola CLI. Without it on your PATH they still run, but /sl-build asks you to describe your tables instead of reading them, and the deep checks are skipped. /sl-show, plain /sl-validate, and conversational edits don’t use it at all.

View the Semantic Layer Toolkit on GitHub

Power BI migration (powerbi-to-sl)

If you already maintain a semantic model in Microsoft Power BI, the powerbi-to-sl plugin translates it into Keboola semantic layer objects: Power BI tables become semantic datasets, measures become semantic metrics (DAX expressions are preserved verbatim for review), and relationships become semantic relationships. The recommended input is a TMDL export produced by Microsoft’s Power BI Modeling MCP server in read-only mode.

The plugin flags anything that needs human attention — such as complex DAX or unmapped data types — in a warnings report. Pushing the result to your project is not automatic — hand it to sl-toolkit, or push it yourself.

View the Power BI migration plugin on GitHub

Installing the plugins

Both plugins are installed from the AI Kit marketplace:

/plugin marketplace add keboola/ai-kit
/plugin install sl-toolkit
/plugin install powerbi-to-sl

Using the semantic layer via MCP

Once your project contains at least one semantic model, four additional tools appear in the Keboola MCP Server. All of them are read-only.

Note

The tools are hidden while a project has no semantic model — the server checks per request and keeps them hidden if it cannot reach the semantic layer. If your assistant reports that the semantic tools are unavailable, build a model first.

Tool	What it does
search_semantic_context	Searches semantic models and objects using regex patterns matched against names, descriptions, and attributes. Used to discover which semantic objects are relevant to a question.
get_semantic_context	Loads semantic objects by type — all objects of a type in compact form, or specific objects by ID with full attributes.
get_semantic_schema	Returns the published schema information for a semantic object type. It currently reports the available schema versions rather than the schema document itself; kbagent semantic-layer schema resolves the default version and returns the full JSON Schema.
validate_semantic_query	Performs a best-effort semantic validation of a SQL query against one or more semantic models: it detects which datasets, metrics, and relationships the query uses and surfaces constraint violations — without executing the query.

You don’t call these tools yourself. Ask questions in plain language (“What was our net revenue last quarter, by region?”) and your AI assistant uses them to ground its answer:

1. Discover – search_semantic_context finds the semantic objects related to your question, such as the “net revenue” metric and the datasets it is built on.
2. Load – get_semantic_context retrieves the full definitions of the relevant objects.
3. Validate – Before running any SQL, validate_semantic_query checks the query against the model and reports business-rule violations.
4. Query – The assistant executes the validated SQL with the standard query_data tool.

Note

Semantic query validation is heuristic — it matches the SQL text against semantic metadata rather than fully parsing the query. Treat it as a best-effort check, not a formal proof of correctness.

Because these four tools are read-only, they remain available when the MCP connection is restricted with the X-Read-Only-Mode header (see Restricting Tool Access).

Example prompts

Once your project has a populated semantic model and your AI assistant is connected via MCP, try:

• “What semantic models are defined in this project?”
• “What was our total revenue last month? Use the semantic layer definitions.”
• “Which business rules apply to queries on the orders dataset?”
• “Validate this SQL against the sales semantic model before running it.”

Support and feedback

If you run into issues or have feedback during the beta, contact our support team — beta feedback directly shapes where the semantic layer goes next.