Back to blog
Semantic Layer vs Ontology: What AI Agents Need

This blog is written by AI for SEO

Semantic Layer vs Ontology: What AI Agents Need

HelixDB10 min read

A semantic layer defines your business metrics once so every BI tool and SQL query computes them the same way. An ontology models the entities, links, rules and sources behind your data so an AI agent can act on it correctly. They solve different problems, and most teams wiring agents to company data end up wanting both.

The confusion is understandable. But governing what "revenue" means in a dashboard is a different job from knowing that the Stripe customer, the CRM account and the invoice PDF are the same company, that a refund over a threshold needs approval, and which row a number came from. This post separates the two, gives the semantic layer its real win, and shows where Helix Foundry fits.

Semantic layer vs ontology in one answer

A semantic layer is a governed definition of metrics, dimensions and joins over your warehouse. An ontology is a model of the things in your business (customers, orders, vendors), how they link across systems, the rules they must obey, and where each fact came from.

The short version of the semantic layer vs ontology question:

Semantic layer Ontology
Main job Consistent metrics for BI, SQL and apps Consistent entities and rules for agents and workflows
Unit of meaning Measure, dimension, join Entity, link, rule, constraint
Cross-system matching Joins within modelled warehouse data Same customer or vendor matched across sources
Rules Access policies, metric logic Business rules and constraints checked at commit
Provenance Metric definition and lineage Each fact traced to a source row or document quote

Neither replaces the other. The semantic layer answers "how do we compute net revenue?" The ontology answers "which customer is this, and is this action allowed?"

What a semantic layer does well (and why you should keep it)

A semantic layer in layman's terms is a shared dictionary for your numbers. You define "active customer" or "monthly recurring revenue" once, and every dashboard, query and tool uses that same definition instead of each analyst rewriting it.

Is Cube a semantic layer? Yes. In Cube's model, cubes represent business entities that define measures (aggregations like counts and sums), dimensions (attributes you group or filter by, such as region or date), and joins, alongside views that expose curated, query-ready datasets. Models are written in YAML or JavaScript and served over SQL, REST and GraphQL. Cube says AI agents can query the model through MCP or its Chat API, with queries validated and access policies applied before they reach the warehouse.

Honeydew takes a similar approach. Definitions carry SQL logic, descriptions and owners, are stored as YAML in Git so changes have history, and can be published to catalogs such as Atlan and Collibra.

That is a real win. If your pain is two dashboards disagreeing about churn, a semantic layer fixes it, and an ontology won't do that job better. Keep it. Anything an agent computes over warehouse metrics should still go through those governed definitions.

Where a semantic layer stops when an agent is the consumer

A semantic layer stops at the edge of modelled warehouse data, and an agent usually needs to reason past that edge.

Three gaps show up fast.

Entities across systems. Your Stripe customer, your CRM account and the company named in a signed contract PDF are one customer under three names. A metric layer joins tables you have already modelled. It doesn't decide that "Acme Corp" in Salesforce and "ACME Corporation Ltd" in a contract are the same entity.

Rules at the point of action. A metric definition says how to compute a number. It doesn't say "a vendor payment above an approval threshold must link to an approved contract," and it doesn't reject a write that breaks that rule. An agent that can take actions needs constraints enforced when data is committed, with violations routed to a person.

Where a fact came from. When an agent says "this customer is at risk," someone will ask why. A governed metric tells you the formula. It doesn't tell you which row, or which sentence in which document, produced the specific value the agent used.

None of this is a flaw in Cube or Honeydew. It is a different layer of the problem, and agents hit it first.

An ontology adds four things a semantic layer does not: typed entities, links between them across sources, rules and constraints, and provenance for every fact.

On the common confusion, the difference between an ontology and semantics: semantics is the broad idea of meaning, and a semantic layer applies it to metrics. An ontology is a concrete, explicit model of a domain, with types such as Customer, Order and Vendor, the links between them, and the rules that must hold. Semantics is the subject. An ontology is a structure you can build, query and check.

Here is semantic AI in practice. An agent is asked "which customers have an unpaid invoice and an open support escalation?" Answering it needs entities (customer, invoice, ticket) matched across billing, finance and support tools, links between them, and a rule for what counts as unpaid. It also needs to show where each fact came from. That is semantic AI working over an ontology, not just over a metric catalog.

The four parts, concretely:

  • Entities and links. Types with properties, and relationships such as customer-has-invoice, resolved across systems.

  • Rules. Declarations about what follows from the data.

  • Constraints. Conditions checked at commit, with violations held for human review instead of silently written.

  • Provenance. Each loaded value traced to its source table row or document evidence, such as a quote.

For more on the neighbouring distinction, see Ontology vs Knowledge Graph: Which Your AI Workflows Need. For how this compares with one vendor's AI context layer, see Helix Foundry vs Cube: AI Context Layer or Ontology?.

How to build one with any tool: entities, cross-source matching, constraints

You can build an ontology with any toolchain by doing three things in order: pick the entities, match them across sources, then write constraints.

1. Start from the questions, not the tables. List the five or ten questions an agent must answer, such as "which accounts have overdue invoices and an open escalation?" The nouns in those questions are your entity types. Keep the list short. You can add types later.

2. Map each source to those types. For each system (Stripe, your CRM, Postgres, a folder of contracts), decide which table or document fills which type, and which columns become properties. Keep a note of the source row or document for every value. You will want that trail later.

3. Match the same entity across sources. Choose match keys per type: email domain, tax ID, a shared customer ID, a normalised legal name. Decide what happens on a near-match: auto-link, or send to a person. Wrong links are the most expensive error here, so prefer review over a silent guess.

4. Write constraints before agents write data. Express business rules as checks that run when data is committed: required links, allowed values, thresholds that need an approval. Decide up front whether a violation blocks the write or flags it for review.

5. Plan for change. Sources add columns and teams rename things. Treat the ontology as versioned, so a schema change is a reviewed new version and not an edit in place.

This works with a spreadsheet, a graph database and a rules engine if you are patient. It is also the grind that Foundry is built to take on. For how to handle step 5 in practice, see How to Update an Ontology When Your Data Changes.

Build it in Helix Foundry: local with Docker or Helix Cloud

Helix Foundry connects your databases, tools and documents, drafts an ontology over them with an agent, and loads it into HelixDB as one connected graph. HelixDB is the open-source graph-vector database underneath. Foundry is the app on top of it, open source under Apache 2.0.

Run it locally.

git clone https://github.com/helixdb/helix-foundry.git
cd helix-foundry
docker compose up -d --wait

Then open http://localhost:3000. The local install is for one person on their own computer, so don't expose it to a network. Prefer a hosted setup? Use Helix Cloud at foundry.helix-db.com and choose Set up with your agent.

The flow:

  1. Connect data: add your data sources, test them and sync their tables. Documents can be added as sets too. Foundry never writes to your sources.

  2. Generate an ontology: describe what you want to understand, and the agent drafts types, links, mappings, document routes, rules, constraints and the questions the ontology should answer.

  3. Review it. The Rules view lists constraints and rules, and you can add or edit them. Treat generated rules as proposals: confirm which are real business requirements and whether a violation should block or flag for review.

  4. Check provenance. The Sources view shows what fills each type and link, and loaded values trace back to the source table row or document quote.

  5. Make it current. Versions are immutable, so a change creates a new version, and loading the current version writes it to the ontology's database.

  6. Ask questions in plain language, or connect an agent through the Helix MCP.

For enterprise setups, Foundry can run locally or be deployed BYOC (bring your own cloud), and it works with self-hosted models, your own inference and bring-your-own-model. It is built on object storage with encryption at rest, and RBAC and enterprise directory sync are on by default. Access to sources and to the ontology is authenticated, and because every fact is grounded in a source, a user who can't see a source can't see anything grounded by it. See Ontology Access Control: Who Sees What Your Agents Know and Build an Ontology With a Local LLM.

The full flow is in the Foundry docs, and the code is at github.com/HelixDB/helix-foundry.

Trade-offs: when a semantic layer is enough and when it is not

A semantic layer is enough when your consumers are dashboards and analysts and your pain is metric drift. An ontology earns its cost when an agent acts across systems.

Stay with a semantic layer alone when:

  • Your data lives mostly in one warehouse and is already modelled.

  • The questions are aggregations: revenue by region, churn by cohort.

  • Nothing writes back, and no one needs to trace a number to a source document.

Add an ontology when:

  • The same customer, order or vendor lives in several tools under different names.

  • Answers depend on documents (contracts, PDFs, notes) as well as tables.

  • Agents or workflows take actions, so rules must be checked before data is written.

  • Someone will ask "where did that come from?" and need a row or a quote as the answer.

The cost of the ontology side is real. You have to decide entity types and match keys, review generated rules, and keep the ontology current as sources change. Foundry drafts the types, links and rules for you and versions the result, but a person still approves what counts as a real business rule. A semantic layer is lighter to start.

The practical pattern is to keep both. Let Cube or Honeydew own metric definitions for BI and SQL, and let the ontology own entities, rules and provenance for agents. If you're unsure which side you're on, Do You Need an Ontology? Five Signs Your Data Needs One is a quick check.

Keep the semantic layer, add the ontology agents need

Don't swap your semantic layer for an ontology. Stack them. Metrics stay governed in Cube or Honeydew, and the ontology covers what agents need that a metric catalog can't: the same customer matched across systems, rules checked before data is written, and every fact traced to its source. To see the difference on your own data, run Helix Foundry locally with Docker (clone github.com/helixdb/helix-foundry, then docker compose up -d --wait), connect one database and one document set, and read the Rules and Sources views of the first ontology it drafts.

Build with HelixDB

Give your coding agent the setup prompt, or sign up and deploy a database.

Sign up