NVIDIA Auto Ontology explained: what it builds, what we found in the code, and when to use it

NVIDIA's Auto Ontology is a semantic layer for AI agents that a machine drafts and a person is supposed to approve. It reads your database metadata, writes a business glossary, proposes reusable SQL definitions, and lets agents ask questions through a read-only MCP server that returns the answer, the SQL and the rows. We read version 1.1.0 end to end. The architecture is the right one, and several of its choices deserve copying. The approval half is thinner than the README suggests: certification is recorded but, as far as we could find, never enforced on the query path. For an FDE that gap is the job. Below: what it builds, how a question becomes SQL, what we found, and how we would pilot it with a customer.

The problem it is aimed at

An agent with database access can write SQL that runs. That is the easy part, and it is the dangerous part, because a query that runs and returns a plausible wrong number produces no error. Finance has three columns that could be called revenue. Sales means bookings. A join to a one-to-many table doubles a total without complaint.

NVIDIA's README puts the requirement plainly: agents need a context layer that says "where data lives, what it means, whether to use it, how to use it, where it came from, and what is similar." That list is a good test for any semantic layer. Your warehouse schema answers the first item. The other five usually live in people's heads.

What it builds

Auto Ontology is a Python and TypeScript project (Apache-2.0; 1,354 commits since April 2026 and about 2,400 GitHub stars as of 3 November 2026). It runs as four services:

Models come from NVIDIA NIM by default: nvidia/nemotron-3-nano-30b-a3b for reasoning, a Nemotron embedding model and a Nemotron reranker. Every model role can point at any OpenAI-compatible endpoint, so you are not locked to NVIDIA's hosted API. Source databases supported today are Databricks, Postgres, Snowflake and DuckDB.

The interesting part is the compiler that drafts the layer. It walks the catalog table by table, samples up to 1,000 rows to profile each one, suggests foreign keys (including relationships no constraint declares), and asks a model to name a business term for each table and describe its columns. A second pass reads the SQL people have run against those tables, ranks expressions by three months of usage, and asks a model which of the top ten per term should become named definitions.

That second pass is clever, and it has a trap. Usage is good evidence that an expression matters to someone. It is no evidence that the expression is right. A wrong query inside an hourly dashboard refresh will be one of the most used expressions in the warehouse.

How a question becomes SQL

The query path is a LangGraph state machine, and reading it is the best way to understand what the tool promises.

Three things in that graph are worth copying into any text-to-SQL system you build. The SQL is constructed from retrieved definitions rather than from raw columns. Joins are checked against relationships the layer knows about before execution, because a matching column name is not evidence that two tables join. And there is a terminal state for "this cannot be answered from what I know," which ends in an explanation rather than a guess.

One check is softer than its label. The "does the SQL fit the question" step is a model reading the SQL. It catches some mistakes, such as a self-comparison or an incorrect filter. It cannot know that your finance team excludes sales to subsidiaries.

The MCP surface is well designed

Agents reach the layer through an MCP server with nine tools, all read-only. One asks a question and returns the answer, the SQL and the rows. One grades whether the layer covers a question before you spend a query on it. The rest look up glossary terms, the columns and SQL definitions behind them, and a table's role in the layer.

Two decisions in that list are worth more than the tools themselves. There is deliberately no tool for browsing databases, schemas or raw columns; the MCP docs explain that "a catalog browser invites an agent to reason about raw tables instead." And there is no way to give the server a token of its own: every call runs as the person who signed in through Auto Ontology's OAuth flow, so a viewer gets a viewer's answers. The common shortcut is the opposite on both counts, a schema browser and a shared service account, and each one turns a wrong answer into an access problem.

What we found reading version 1.1.0

We read the code at commit cdaf61e (3 November 2026). We did not run the stack, which needs Docker, Postgres and NIM keys. These are the findings that matter for a deployment:

Certification is a badge, not a gate. Terms carry certified flags for their name and description, and every column attribute and SQL definition has its own flag. A query rolls them up to certified, partial or pending for display. We found no reference to those flags anywhere in the text-to-SQL path, and NVIDIA's own management skill says the current certification fields "are not an atomic review/promotion system." So an agent can answer with a definition nobody has reviewed. If your customer's rule is that only reviewed definitions may answer finance questions, you write that check.

Credentials need Vault. Connections added through the UI are stored, password included, unencrypted on a row in Postgres unless HashiCorp Vault is configured. A partial Vault configuration falls back to plaintext with a warning. The README says so clearly; make sure the customer's security reviewer reads it before they find it.

The backend trusts a header. The Next.js gateway resolves the user and forwards an x-auto-ontology-user-id header to FastAPI, which does not verify it independently. The README says the FastAPI port "must not be exposed publicly." In a customer Kubernetes cluster that means a network policy, not a reminder.

It is open source, with an asterisk. The license is Apache-2.0 and the repository is public, but the project is "currently not accepting external contributions," the MCP install guide still describes Auto Ontology as "NVIDIA-internal today," and the MCP package was not on PyPI when we checked on 3 November. Plan on installing from the repository or the NGC container.

There are no published accuracy numbers. NVIDIA's companion repository, ontology-sql-eval, runs BIRD, FDABench-Lite, BEAVER, WideWorldImporters and BIRD-Interact against a schema-only control arm and scores by execution match, with no model judge. It publishes the harness, not results. A "90% faster ontology building" figure circulating in coverage appears in neither repository. Treat accuracy as unknown until you measure it on the customer's questions.

Model-replacement edge cases are documented. The publication skill lists three known issues in which importing a replacement model can retain an omitted foreign key or stale properties, or return a 500 error. When we checked on 3 November, one of the three was closed and two were still open. NVIDIA's guidance is to export the scope before a change, keep the original as the rollback artifact, and compare a fresh export afterward. Follow it.

Pros and cons

When an FDE should use it

Use it when a customer wants agents over a warehouse with dozens or hundreds of tables, has no semantic layer, and has people who will own definitions once they see a draft. The draft gets you from a blank page to a reviewable glossary in days, and the review conversation is the most valuable meeting of the engagement.

Think twice when the customer already has a maintained semantic layer in dbt, Cube, LookML or their warehouse vendor's product. Auto Ontology says it complements the semantic models customers already own and can connect to them, but two semantic layers with overlapping definitions is how the revenue argument starts. Wire the agent to the layer people already trust.

Skip it when the questions are few and fixed. Ten parameterized SQL tools, each reviewed, beat a general text-to-SQL system for a dashboard replacement.

How we would pilot it

1. Collect the questions the customer actually asks, from tickets and analyst requests, and cluster them. That list decides scope, not the table count.
2. Run the compiler, export the drafted glossary, and put the definitions those questions need in front of named owners. Certify them under distinct names where departments disagree.
3. Add the missing gate: every answer must list the definitions its SQL used, and finance-facing answers refuse when any of them is pending.
4. Build a golden set of questions, reference SQL and frozen result sets, stratified by single metric, cross-system, time window and should-refuse, and score execution accuracy per stratum.
5. Configure Vault, a network policy for the FastAPI port and SSO before any real credential touches it.
6. Release one question class at a time.

The tool does the part that used to take the first month. The part that makes finance trust the numbers is still yours, and the design question to bring to every customer meeting is the same one: who signs each definition, and where does the system check that they did.