Skip to content

PRDCT-502: add Semantic Layer documentation (private beta) - #999

Open
jordanrburger wants to merge 2 commits into
mainfrom
jordan/semantic-layer-docs
Open

PRDCT-502: add Semantic Layer documentation (private beta)#999
jordanrburger wants to merge 2 commits into
mainfrom
jordan/semantic-layer-docs

Conversation

@jordanrburger

@jordanrburger jordanrburger commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

What

Adds public documentation for the Semantic Layer (private beta) under AI Features:

  • New page: /ai/semantic-layer/ — what the semantic layer is, the six semantic object types (semantic-model, semantic-dataset, semantic-metric, semantic-relationship, semantic-glossary, semantic-constraint), how AI assistants use it through the MCP Server's four read-only semantic tools (search_semantic_context, get_semantic_context, get_semantic_schema, validate_semantic_query), the typical discover → load → validate → query flow, and how to build/migrate models with the AI Kit plugins.
  • AI Features index — new Semantic Layer entry.
  • MCP Server page — Semantic Layer added to the Available Tools list.
  • AI Kit page — documents the sl-toolkit and powerbi-to-sl plugins and adds them to the install snippet.
  • Sidebar — _data/navigation.yml entry + regenerated src/sidebar.mjs (npm run gen:sidebar).

Accuracy notes

  • Tool names, object types, and read-only behavior verified against keboola/mcp-server source (tools/semantic/).
  • Plugin commands and behavior verified against the keboola/ai-kit plugin READMEs (plugins/sl-toolkit, plugins/powerbi-to-sl).
  • The page presents the feature as private beta with enablement via the support team.

Verification

  • npm run build clean (259 pages).
  • node scripts/audit-phase2.mjs — no new issues on the touched pages (remaining flags are pre-existing).

🤖 Generated with Claude Code

@jordanrburger @claude
docs: add Semantic Layer documentation (private beta)
3d2cdac 
Add a dedicated Semantic Layer page under AI Features covering:
- what the semantic layer is and why to use it
- the six semantic object types (model, dataset, metric, relationship,
  glossary, constraint)
- the four read-only MCP tools (search_semantic_context,
  get_semantic_context, get_semantic_schema, validate_semantic_query)
  and the typical discover -> load -> validate -> query flow
- building models with the AI Kit plugins (sl-toolkit, powerbi-to-sl)

Also cross-link it from the AI Features index and the MCP Server tools
list, document the two semantic layer plugins on the AI Kit page, and
add the page to the sidebar navigation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@vercel

vercel Bot commented Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
connection-docs Ready Ready Preview Aug 8, 2026 12:08am

Request Review

@jordanrburger
jordanrburger marked this pull request as ready for review July 8, 2026 15:30
@jordanrburger
jordanrburger requested a review from davidesner July 8, 2026 15:30
keboola-pr-reviewer-bot
keboola-pr-reviewer-bot reviewed Jul 8, 2026
View reviewed changes

@keboola-pr-reviewer-bot keboola-pr-reviewer-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: needs_human (risk 2/5) · profile docs

Well-formed docs PR for the Semantic Layer, but nav-data changes and unverifiable product-behaviour claims require a maintainer.

Concerns:

  • _data/navigation.yml: Nav/structure data change — always needs human per policy.
  • src/content/docs/ai/semantic-layer/index.md: New product-behaviour claims (object types, MCP tools) unverifiable from diff.

Suggested reviewers: @keboola/docs

jordanrburger
jordanrburger commented Jul 9, 2026
View reviewed changes
Comment thread src/content/docs/ai/semantic-layer/index.md

## Using the Semantic Layer via MCP

Once the semantic layer is enabled for your project, four additional tools automatically appear in the [Keboola MCP Server](/ai/mcp-server/). All of them are read-only.

@jordanrburger jordanrburger Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to mention that this is feature-gated and must be turned on.

Also, we should make an explicit callout that Kai can automatically make use of the semantic layer if defined.

@jordanrburger

jordanrburger commented Jul 16, 2026

Copy link
Copy Markdown
Contributor Author

Review summary

Verdict: needs a trivial rebase, then ready.

Content is clean — valid frontmatter (title+slug+description), unique slug ai/semantic-layer, :::caution[Private Beta] framing consistent across all four touched pages, sidebar correctly regenerated (not hand-edited), and the #restricting-tool-access anchor resolves.

Only blocker:

  • One-file merge conflict in src/content/docs/ai/index.md. Both this PR and main inserted a new ### section at the same spot (after "MCP Server"). Main added "Machine-Readable API Index" (docs(ai): link machine-readable API index for agentic usage #1026); this PR adds "Semantic Layer". Resolution is trivial — keep both sibling sections, no overlap. (_data/navigation.yml does NOT conflict — the two edits are far apart and auto-merge.)

Product facts to verify (author checked against keboola/mcp-server + keboola/ai-kit, not verifiable from the diff): the six semantic object types; the four read-only MCP tools (search_semantic_context, get_semantic_context, get_semantic_schema, validate_semantic_query) and their availability under X-Read-Only-Mode; the private-beta enablement path (contact support@keboola.com); the powerbi-to-sl TMDL-export detail.

Automated review pass (Claude Code), flagged for a human maintainer — not an approval.

@cjayyy

cjayyy commented Jul 21, 2026

Copy link
Copy Markdown
Contributor

@jordanrburger What are u waiting for with this PR?

@jordanrburger

jordanrburger commented Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

@jordanrburger What are u waiting for with this PR?

Fair question 😅 I guess nothing. I have a few notes from David to add here. Then I'll merge it.

But if the UI is close to ready, maybe I should wait and update it with new info?

@Iamfle4ka Iamfle4ka changed the title docs: add Semantic Layer documentation (private beta) PRDCT-502: add Semantic Layer documentation (private beta) Aug 3, 2026
@linear-code

linear-code Bot commented Aug 3, 2026

Copy link
Copy Markdown

PRDCT-502

AI-3610

Nikita
Merge remote-tracking branch 'keboola/main' into jordan/semantic-laye…
b0313fd 
…r-docs

# Conflicts:
#	_data/navigation.yml
#	src/content/docs/ai/index.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@keboola-pr-reviewer-bot keboola-pr-reviewer-bot keboola-pr-reviewer-bot left review comments
@davidesner davidesner Awaiting requested review from davidesner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jordanrburger @cjayyy @keboola-pr-reviewer-bot