AI and agents

A semantic layer for AI agents: governed metrics over REST and MCP

A semantic layer defines each metric once, so dashboards, applications and AI agents compute it the same way. In DataNature, cubes are YAML files over Gold Iceberg tables that compile to warehouse SQL, can be materialized as warehouse views, carry row-level security per role, and are served over a REST endpoint and over MCP, which Voir agents use to answer numeric questions without guessing joins.

Published . Last updated

On this page

Natural-language analytics fails in a predictable way: the model writes plausible SQL with the wrong join or the wrong definition of "active customer", and the number looks fine. A semantic layer fixes the cause rather than the symptom. This guide explains how DataNature's semantic layer works, how agents reach it over the Model Context Protocol (MCP), and how to design cubes that give agents correct answers.

Why do AI agents need a semantic layer?

Because a metric is a decision, not a column. "Revenue" might mean net of refunds, in reporting currency, excluding test accounts. If every agent and dashboard rediscovers that from raw tables, they disagree. A semantic layer stores the definition once (measures, dimensions, joins, filters and time grains), so an agent asks for revenue by channel by month and the platform generates the SQL. Voir answers are most accurate when twins use cubes for exactly this reason.

What is a cube in DataNature?

A cube is a YAML file in semantic-models/cubes/ in the workspace repository. It names a Gold table and declares:

  • measures: full aggregates such as SUM(net_amount) or COUNT(DISTINCT order_id)
  • dimensions: bare columns, or {alias.column} from a join, including time dimensions
  • filter: an optional row condition, such as is_current = true for SCD2 tables
  • joins: many_to_one, one_to_many or one_to_one relationships
  • time_grains: for example day, week and month

An illustrative cube:

name: sales_daily
table: acme_iceberg.gold.fct_sales
filter: is_current = true
measures:
  - name: revenue
    sql: SUM(net_amount)
  - name: orders
    sql: COUNT(DISTINCT order_id)
dimensions:
  - name: channel
    sql: channel
  - name: order_date
    sql: order_date
    type: time
time_grains: [day, week, month]

Cubes compile to SQL for DN Warehouse, DataNature's low-latency serving compute. Lakehouse tables are referenced as <workspace>_iceberg.<schema>.<table>; the lakehouse.… form only works in Trino. See the documentation for the exact schema on your version.

How do agents and applications reach cubes?

Two interfaces:

  • REST at /semantic/query, with API keys from Settings → API Keys, for applications and services.
  • MCP, which Voir uses. A Voir twin with the semantic-layer integration can list cubes and query them as tools, inside its governance guards.

Reading cubes requires the Semantic Models: Use permission. Queries return 100 rows by default and 1,000 at most, which suits answers and charts, not bulk export.

How do materialized views speed things up?

Ticking Materialize as Warehouse MV creates mv_<cube> in DN Warehouse, and matching queries are rewritten to it automatically. Three rules apply:

  1. Cubes with a one_to_many join, or with measures only, cannot be materialized.
  2. Views over Iceberg tables do not detect new data on their own. Add a Refresh cubes node after Gold in your job, or press Refresh on the cube card.
  3. LIMIT, ORDER BY and window functions in a query defeat the rewrite.

The recommended job is: Connect pipeline → dbt Silver → dbt Gold → Refresh cubes.

How is row-level security applied to cubes?

Under Data & AI Security → Data Governance → Cube Security, each role gets a WHERE predicate, such as branch_code = 'KTM', that is injected into every cube query for that role. It applies whether the query comes from an application over REST or from an agent over MCP, which makes cubes the safest path for agents that answer questions about customer or financial data.

How should you design cubes for agents?

  • Build on Gold, never Bronze. Agents should see certified data only.
  • Pre-aggregate fan-out joins in dbt. One-to-many joins inflate sums; the editor warns, but live queries do not block it.
  • Name measures the way people ask. active_customers, not cnt_cust_flg.
  • Write descriptions. They become context the agent reads.
  • Keep cubes stable. Renaming a cube drops and recreates its materialized view, which breaks external references.
  • Add skills in Voir with worked examples of good questions and answers for each cube.

Frequently asked questions

Can Power BI or Superset use the cubes?

Yes. Superset and Power BI connect to the semantic layer, so dashboards use the same certified definitions as agents and applications. When a cube is materialized, its mv_<cube> view in DN Warehouse can also be queried by any BI tool that connects over SQL (JDBC or ODBC), such as Tableau, Excel or Looker. Applications and agents use cubes through REST and MCP.

Is the semantic layer the same as Atlas?

Atlas is the governance and semantic framework. Cubes and certified KPIs are the semantic models within it.

Can external agents use DataNature cubes?

Yes. Applications can call the REST endpoint with an API key, and the semantic layer is exposed over MCP, subject to the same permissions and cube security.

Sources

How does DataNature Atlas keep this secure and compliant?

Agents are governed like users: scoped, masked, logged and unable to act without approval. DataNature Atlas is the platform's governance module:

  • Knows your data: a catalog with automated PII detection and classification across Bronze, Silver and Gold.
  • Controls access: role-based grants plus attribute-based policies, row filters and column masks (null, redact, partial, hash, year only).
  • Governs AI: Voir agents are scoped principals; masks, row filters and PII guardrails apply to every tool call and answer.
  • Proves it: lineage from source to metric to decision, and an audit log of who or what accessed which data.
  • Stays local: Atlas runs inside your deployment, so policies, lineage and logs never leave your jurisdiction.

These controls support GDPR, PIPEDA, Quebec Law 25, CCPA, HIPAA and sector rules such as OSFI E-23. Read DataNature Atlas in depth or see security and compliance.

See it on your own data.

Book a demo

Demos and quotes are handled by Dlytica, the company behind DataNature.