Admin reference

Semantic contexts: gedeelde betekenis voor datasources en AI

Semantic contexts leggen per tenant vast wat bedrijfsbegrippen, metrics, entiteiten, filters en relaties betekenen. Dashbot, MCP-tools en beheerders kunnen die definities gebruiken zodat analyses niet alleen op kolomnamen hoeven te gokken.

Dit is geen globale kennisbank. Elke context hoort bij de huidige tenant en toegang blijft bepaald door de datasource-rechten van de gebruiker.

Wat het is Rechten Velden Dashbot & MCP Veiligheidsgrenzen Workflow

1. Wat is een semantic context?

Een semantic context is een tenant-scoped definitielaag boven je datasources. Hij beschrijft betekenis, beleid en taalgebruik, maar bevat geen rijen of queryresultaten.

Gebruik hem voor

KPI-definities, formules, aggregaties, grains en eenheden.
Business-entiteiten zoals klanten, orders, tickets, winkels of producten.
Synoniemen en termen die gebruikers in prompts gebruiken.
Toegestane joinpaden, relaties en caveats tussen datasources.
Businessregels, standaardfilters, fiscal calendar regels en voorbeelden.

Gebruik hem niet voor

Ruwe data, sample rows, volledige datasets of exports.
rowsRef, __dashview_row_id of andere rijverwijzingen.
Audit-, tenant-, user-, branch- of repository-scopevelden.
Secrets, API keys, wachtwoorden of credentials.
Een bypass rond datasource-rechten of forced filters.

Semantic contexts helpen Dashbot en MCP om beter te redeneren over betekenis. Ze geven nooit zelfstandig toegang tot data en vervangen geen datasource-schema, rechtenmodel of queryvalidatie.

2. Rechten en scope

Tenant-scoped opslag

Contexts worden opgeslagen onder tenants/{tenantId}/semanticContexts. De tenant komt uit de actieve gebruikerssessie, niet uit een veld in de payload.

Lezen

Lijsten, zoeken en detailweergave worden gefilterd op datasource-toegang. Een gebruiker ziet alleen contexts voor bronnen die binnen zijn of haar scope vallen.

Schrijven

Aanmaken, wijzigen en verwijderen vereist datasource management of agent-edit rechten. Voor agent-edit gebruikers zijn schrijfacties beperkt tot contexts waarvan elke gekoppelde datasource toegankelijk is voor die gebruiker. De adminpagina is bedoeld voor gebruikers met datasourcebeheer.

Forced filters blijven van toepassing op dataquery's. Een semantic context mag dus nooit beschrijven dat een gebruiker buiten die filters kan werken.
Koppel contexts met datasourceIds aan de bronnen die ze beschrijven. Gebruik exacte datasource-ID's uit het datasource-overzicht.
Laat een context zonder datasourcekoppeling alleen algemeen tenantbeleid of terminologie beschrijven, niet brondata.
Dashbot en MCP sturen geen tenant-ID mee voor deze tools; de backend bepaalt tenant en user vanuit de bearer auth of MCP access key.

3. Velden in API en admin editor

Open Administration → Semantic Contexts om contexts te zoeken, aan te maken, te bewerken of te verwijderen. De editor combineert basisvelden met JSON-secties voor de semantische definitie.

Veld	Gebruik
`id`	Stabiele tenant-scoped context-ID voor URL's, diffing en toolverwijzingen. Gebruik een leesbare, blijvende naam.
`name` / `title`	Menselijke titel die zichtbaar is in lijsten en zoekresultaten.
`description`	Korte samenvatting van doel, bereik en wanneer deze context gebruikt moet worden.
`status`	`draft`, `active` of `archived`. Gebruik `active` voor definities die agents mogen volgen.
`tags`	Zoeklabels zoals `finance`, `sales`, `policy` of `calendar`.
`datasourceIds`	Datasource-ID's waarop deze betekenis van toepassing is. Deze koppeling helpt toegang en zoekresultaten beperken.
`entities`	Canonieke objecten, primaire sleutels, labels en rol in het datamodel.
`measures`	Goedgekeurde metrics, formules, aggregaties, eenheden, grain en uitzonderingen.
`dimensions`	Velden en attributen waarop gebruikers groeperen, filteren of segmenteren.
`relationships`	Relaties en joinpaden tussen entiteiten of datasources, inclusief cardinaliteit en caveats.
`businessRules`	Berekeningsregels, beleidsregels, wordingregels of queryregels die agents moeten respecteren.
`defaultFilters`	Standaardfilters of voorkeursfilters die bij een begrip horen. Dit vervangt geen forced filters.
`synonyms`	Woordenboek van gebruikerstaal naar canonieke termen, velden, metrics of entiteiten.
`examples`	Alleen gebruiksvoorbeelden, zoals vraag-naar-berekening of vraag-naar-SQL-vorm. Voeg geen resultaatrijen, row IDs of `rowsRef` toe.

4. Dashbot en MCP gebruik

Dashbot

Dashbot kan semantic contexts lijst/zoeken/ophalen om businessbetekenis te vinden voordat het SQL, dashboards of analyses maakt.
Dashbot kan contexts aanmaken, bijwerken of verwijderen wanneer de huidige gebruiker daarvoor rechten heeft en elke gekoppelde datasource voor die gebruiker toegankelijk is.
De Dashbot-tools gebruiken de huidige bearer auth en vragen geen tenant-ID als toolinput.
Toolresultaten zijn begrensd en compact zodat definities bruikbaar blijven zonder grote payloads terug te sturen.

Dashview MCP

Gebruik list_semantic_contexts, search_semantic_contexts en get_semantic_context voor inspectie.
Gebruik create_semantic_context, update_semantic_context, upsert_semantic_context en delete_semantic_context alleen voor bewuste beheeracties.
MCP stript audit-, tenant-, user- en scopevelden en blokkeert rijvelden voordat de payload naar de backend gaat.
Valideer aannames met datasource-schema's en querytools. Een semantic context is geen bewijs dat een veld of berekening runtime-geldig is.

Tool payloads

Dashbot gebruikt compacte velden: title, content, optioneel description, tags en datasourceIds.
MCP gebruikt een gestructureerd contextobject met velden zoals id, name/title, entities, measures/metrics, dimensions, relationships/joins, businessRules, defaultFilters, synonyms en examples.
API- en tooloutputs tonen semantische definitievelden, maar geen audit- of usermetadata zoals tenantId, userId, createdBy, updatedBy, createdAt of updatedAt.

API boundary

Frontend, Dashbot en MCP gebruiken dezelfde tenant-scoped /semantic-contexts backendgrens voor list, search, get, create, replace, patch en delete. De backend blijft de bron van waarheid voor scope, rechten en filtering.

Goede volgorde voor agents: zoek eerst relevante semantic contexts, haal daarna de volledige context op, controleer datasource-schema's, en voer pas daarna query's, dashboardwijzigingen of automationwijzigingen uit.

5. Veiligheidsgrenzen

Bewaar alleen definities, policies, gebruiksvoorbeelden en lineage. Sla nooit rows, rowsRef, row IDs, records, previewdata of datasets op.
Neem geen tenantId, userId, auditvelden, branchnaam of andere scopevelden op. Scope komt uit auth en backendregels.
Beschrijf forced filters als beleidscontext wanneer nodig, maar probeer ze niet te herdefiniëren of te omzeilen.
Gebruik datasourceIds om contexts aan bronnen te koppelen, maar ga er niet van uit dat iedere gebruiker die bronnen mag zien.
Zet vertrouwelijke businessregels alleen in contexts als alle gebruikers met toegang tot de gekoppelde datasources die regels ook mogen lezen.
Controleer contexts extra wanneer ze door agents zijn aangepast. Laat geen verouderde KPI-formules of te brede joinregels actief staan.

6. Aanbevolen beheerworkflow

Begin bij de datasource: refresh schema en controleer kolomnamen, types, labels en agenttoegang.
Maak in Administration → Semantic Contexts een context met duidelijke ID, naam, status en datasourcekoppeling.
Vul eerst measures, entities, dimensions en synonyms voor de belangrijkste gebruikersvragen.
Voeg daarna relationships, businessRules, defaultFilters en examples toe voor query- en promptsturing.
Laat Dashbot een paar representatieve vragen beantwoorden en controleer de activity trace, SQL-vorm en tabeloutput.
Werk de context bij wanneer dashboards, datasources, fiscal calendar regels of businessdefinities veranderen.
Archiveer contexts die niet meer geldig zijn in plaats van ze stilzwijgend actief te laten.