Semantic Layer

The Semantic Layer is where you describe what your data means in business terms, mark the assets your team can trust, and set the rules Knowi should follow when it interprets a question. It is the governed context that sits between your raw data and the people (and AI) asking questions of it.

Two audiences rely on it:

• Your team gets a single place to see what has been reviewed and certified, so people know which widget, dashboard, or dataset is the trusted one to reuse.
• Agentic BI gets a reliable layer to draw from. Instead of guessing from raw field names, the agent resolves business terms, matches questions to the right assets, and prefers work that has already been verified.

The Semantic Layer supplements your assets; it never changes them. Source field names, query definitions, native descriptions, and data all stay exactly as they are. Everything you add here (descriptions, business terms, certification, interpretation rules) is layered on top and can be edited or removed independently.

Where to Find It

Open Data > Semantic. The Semantic tab sits alongside Queries, Data Sources, Widgets, Dashboards, and Documents, and it has three views:

You do not have to start in the Semantic tab. An asset's Semantic Details can be opened from wherever you are working, which is covered in Semantic Details below.

Business Glossary

The Glossary is your shared business vocabulary. It maps the language people actually use ("customer", "bookings", "MRR") to the datasets and fields that hold that data, so a question phrased in business terms resolves correctly. It replaces account-wide field synonyms: rather than one-off synonym lists, you define a canonical term once and attach every accepted alias to it.

Open Data > Semantic > Glossary to see every term, its definition, whether it is Global or Dataset scoped, and when it was last modified. Admins select New Term to add one, or open an existing term to edit it.

A term has four parts:

Global vs Dataset terms. A Global term applies across your account. A Dataset term is scoped to one dataset and shows its source dataset in the editor. If the same word has more than one applicable meaning, Knowi surfaces the ambiguity rather than silently picking one.

To map a Cloud9QL expression or a calculation rather than a plain field, use the dataset's Synonyms in Question Interpretation instead of a glossary mapping.

Catalog

The Catalog is the inventory view. It lists every asset you can access with its semantic setup and certification side by side, so you can tell at a glance what is documented and what is trusted. Open Data > Semantic > Catalog.

Narrow the list with the asset-type filter, the Only certified toggle, or the search box. Select a row, or its Semantic setup or Certification status, to open that asset's Semantic Details. Large catalogs load the first 500 matching assets; use the filter or search to narrow the list.

Semantic Details

Semantic Details is the panel where you describe and certify a single asset. The panel is identical no matter where you open it, so the experience is consistent across every asset type. You can reach it from:

• The Catalog - select an asset row or its status.
• A listing - select the certification check mark on a certified widget, data source, dashboard, or query.
• The asset itself - Dashboard settings > Open Semantic Details for a dashboard, the Open Semantic Details button on a query, or a widget's own semantic action. Certified widgets also show a certification badge in their header on a dashboard, and certified datasets show a badge on the dataset page.

Until you save anything, the panel notes that "Semantic details have not been saved yet." The sections below are the building blocks. Which ones appear depends on the asset type, summarized in What You Configure by Asset Type.

Trust and Certification

Certification marks a specific asset as reviewed and trusted. It is a human judgment, independent of AI: its purpose is to show, across the company, what has been vetted, so people can answer "has someone reviewed this, and can we reuse it?" With certification permission you switch an asset between Not certified and Certified; one authorized reviewer is enough.

• It is asset-specific. Certifying a dashboard does not certify its widgets or datasets, and certifying a widget does not certify its dataset. Each asset is reviewed on its own.
• It is visible everywhere the asset appears. A certified asset shows a check mark in the Catalog and in its listing, a badge on certified widgets in a dashboard, and a badge on the dataset page. Hovering shows who certified it and when ("Certified asset by [name] on [date]").
• It influences ranking, not applicability. Certified assets are surfaced first in search and Agentic BI answers, but certification is a trust signal only; it cannot override a materially more relevant result.
• It can go stale. If an asset changes after it was certified, the panel shows a readiness warning (for example, that a relationship needs a fanout or cardinality review) so a reviewer can re-confirm it.

Basic Information

This section is the plain-language explanation of what the asset is and when to use it.

• Asset description. This text is used in AI asset matching. For a dataset or data source, you write the description here. For a widget or dashboard, the description from the asset's own settings is shown, and you add Additional semantic context in a separate field. Keeping them separate matters: what Knowi uses for matching is not always what is displayed on the asset, so the extra context you add for AI does not have to change what users see. Select Generate to have AI draft a description for you to review.
• Business terms. On datasets and data sources, link published glossary terms that describe the asset. This sharpens matching without touching the asset's data or logic.
• Business display name. On a dataset field, give the field a clear business name people recognize. It improves how the field appears in search and AI answers without renaming the source field.

Question Interpretation

Datasets have an additional section that defines the language and rules Knowi uses when it interprets natural language questions about that dataset. This is where a dataset's AI and NLP interpretation settings live (they are managed here rather than on a separate settings page). Data processing and indexing controls remain under AI Processing.

• Synonyms. Associate the words people use with a dataset field, a calculation, or a Cloud9QL expression. Synonyms that come from a mapped glossary term appear separately under a From glossary note, so you can tell dataset-specific synonyms apart from inherited ones.
• Primary date for questions. The date field Knowi should use when a question names a time period but no specific date field, for example "revenue last quarter."
• Dataset AI instructions. Dataset-specific interpretation rules, for example "use the Flags column, not the JSON field, for flag questions." Instructions guide interpretation only; they never override data access or security.

Connected Assets

This read-only section shows how the asset relates to others. Automatic native connections (a widget using a dataset, a dashboard containing widgets) are listed separately from Governed data relationships, which capture explicit meaning such as joins, rollups, derivations, drill-through paths, lookups, and replacements. Select View full lineage to open the complete dependency graph.

What You Configure by Asset Type

The panel adapts to the asset, so the sections you see differ by type:

A few notes that follow from this:

• A dataset is the richest asset: it carries description, business terms, question-interpretation rules, per-field business display names, and certification. It is also the certification source for its queries, since queries are certified through their dataset rather than on their own.
• A data source can be certified too, and a certified data source is flagged in the Data Sources listing, so people know which connection is the trusted one to build from.
• A widget and a dashboard are the simplest: certification, a description with added semantic context, and their connected assets.
• The dashboard description shown here is the dashboard's own native description from Dashboard settings. It is separate from the semantic context you add for AI, and separate again from certification.

Global Settings

Global Settings holds account-wide interpretation rules and is available to Admins.

• Global Alias Datasets. Choose small two-column reference datasets whose first column is the canonical value and whose second column contains accepted aliases, for example mapping California to CA. Select up to 10 account-wide sources. They apply across any dataset whose fields match a column in the reference dataset; a dataset with no matching field is skipped.
• Global AI Instructions. Business rules AI should apply when it interprets questions across datasets, such as fiscal calendars, currency conventions, or aggregation policy. For example: "Fiscal year starts April 1. Report revenue in USD."

For rules that apply to a single dataset rather than the whole account, use Dataset AI instructions in that dataset's Question Interpretation.

Choosing the Semantic AI Model

The AI that drafts descriptions, glossary definitions, and business term suggestions is the Semantic AI model. Choose it under Settings > User Settings > AI Settings > AI Models. Until you set one, Semantic AI uses the AI Agents model. Every suggestion stays in the form for you to review; nothing is saved or published automatically.

Access via MCP

The Semantic Layer is also available through the MCP Server, so connected AI tools and scripts can work with it programmatically. You can list and read glossary terms, create and map terms, publish them, set dataset-level semantics (synonyms, primary date, and dataset AI instructions), and resolve or explain how a question maps to assets - the same operations as the UI, subject to the same permissions. See the Semantic Layer Tools section in MCP Server for the full list.

Permissions

Permissions are enforced before an asset is shown and again before its details or data are used, so the Semantic Layer never surfaces an asset a user could not otherwise access.

How Agentic BI Uses the Semantic Layer

When you ask a question, the Semantic Layer is the trusted context Agentic BI resolves against before it answers or builds anything:

• Asset matching. Glossary terms, aliases, and asset descriptions map your question to the right datasets, fields, and existing assets. Global Alias Datasets normalize stored values (so "California" finds CA).
• Reuse before rebuild. Certified assets are surfaced first, so an answer can come from a widget or dashboard you already trust instead of new work built from scratch.
• Correct interpretation. Primary date fields, dataset and global AI instructions, and governed relationships guide how a question is read, how values are aggregated, and how results feed into recommendations.

Because the Semantic Layer is the source of truth for this business metadata, it can be reviewed and governed independently while your assets keep their native names, definitions, and data throughout.