NVIDIA Auto Ontology: A Semantic Layer for AI Agents Querying Business Data

At the start-of-month meeting, sales asks the internal AI agent: “What was June revenue?” It answers at once: 4.2 billion. By week’s end, accounting finds the real figure is 3.7 billion: the agent counted gross revenue without subtracting returns, and used the invoice date instead of the delivery date. It read the database correctly — but guessed what “revenue” means and how to JOIN the tables. The flaw is architectural: no shared layer of definitions sits between database and agent. NVIDIA Auto Ontology fills that gap — a human-certified semantic layer, so the agent answers only from verified definitions, with SQL and provenance attached.

What Is Auto Ontology?

Auto Ontology is an open-source NVIDIA library (repo NVIDIA/auto-ontology, Apache 2.0, around 6,469 stars) that builds a semantic layer from enterprise metadata and exposes it to any agent via MCP, CLI, and API. An ontology consists of Terms (business concepts mapped to data columns), SQL attributes (human-reviewed SQL expressions, such as the margin formula), and Relationships (how tables JOIN, including through bridge tables). Its five capabilities — Discover, Ground, Validate, Expose, Learn — cover generating the ontology, attaching business meaning, validating queries, exposing it, and folding certified corrections back in.

The workflow has three steps. Generate: ingestion scans the source database, proposes terms, relationships, and SQL attributes, and saves a draft to Postgres — in the project’s example, one compilation of the Wide World Importers sample database produced 31 terms. Certify: a human reviews each definition in the web UI and certifies it; only certified definitions answer questions, so trust comes from certification discipline, not model strength. Answer: the agent generates SQL only from certified definitions and returns the answer with the SQL and resolution steps. Out-of-scope questions are refused, not answered with invented numbers: asking about “return on ad spend” on a database with no advertising data, check_answerable reports coverage of 0.5 and no term covers “ad spend”, so the agent asks for clarification.

It suits sysadmins, DevOps/SRE engineers, backend/full-stack developers, self-hosters, and BI/data teams standardizing metric definitions.

Architecture and Verified SQL Generation

Five services: a Next.js 16 frontend (React 19, TypeScript, Tailwind 4) with Better Auth and Prisma on port 3000, the single entry point; a FastAPI backend (Python 3.12+, LangChain) on port 3001 for chat, NL-to-SQL, and the catalog; an ingestion worker (also FastAPI) on port 3002; an MCP server (FastMCP) on port 3003 with read-only tools; and Postgres 17 with pgvector on port 5432 for metadata, ontology, and vectors.

Models run through NVIDIA NIM (hosted at integrate.api.nvidia.com or self-hosted), configured with the triplet <ROLE>_ENDPOINT / <ROLE>_API_KEY / <ROLE>_MODEL, falling back to DEFAULT_MODELS_*. Four roles: REASONING (chat, NL-to-SQL), NON_REASONING (entity extraction, SQL checking and repair), EMBED, and RERANK; the default reasoning model is nvidia/nemotron-3.5-lightning-30b-a3b. Note: the documentation is inconsistent about the default embed and rerank models — the NIM introduction, following .env.example, lists nvidia/nemotron-3-embed-1b and nvidia/llama-nemotron-rerank-vl-1b-v2, while the Models table lists nvidia/nemotron-3.5-embed-1b and nvidia/nemotron-3.5-rerank-8b. In my view, treat .env.example as authoritative when deploying, and use the same embedding model at ingestion and query time.

flowchart TD
    User["User / external AI agent\n(Cursor, Claude Desktop, script via API)"]
    UI["Web UI Next.js 16 — port 3000\nSingle entry point, Better Auth + RBAC"]
    Backend["Backend FastAPI — port 3001\nGenerates answers, orchestrates"]
    Worker["Ingestion worker FastAPI — port 3002\nScans metadata, compiles ontology"]
    MCP["MCP server FastMCP — port 3003\n9 read-only tools: check_readiness, search_terms,\nget_term, check_answerable, ask_question..."]
    OntologyDB["Postgres 17 + pgvector — port 5432\nStore for Terms, certified SQL attributes, Relationships"]
    SourceDBs["Source databases\nPostgreSQL, MySQL, Snowflake, ClickHouse,\nTrino, DuckDB, SQLite... — 10 engines"]
    NIM["NVIDIA NIM\nReasoning nemotron-3.5-lightning-30b-a3b,\nembed, rerank"]
    Gate["check_answerable gate\nDecides to answer or refuse"]
    Answer["Answer with SQL + provenance"]

    User --> UI
    User --> MCP
    MCP --> Backend
    UI --> Backend
    Backend --> OntologyDB
    Backend --> NIM
    Worker --> SourceDBs
    Worker --> NIM
    Worker --> OntologyDB
    UI -->|human reviews & certifies| OntologyDB
    Backend --> Gate
    Gate --> Answer
    Gate -->|unanswerable — ask again, never invent numbers| User
    Backend --> SourceDBs
    SourceDBs --> Answer

Deploying with Docker Compose

You need Docker with Compose v2, uv, and an NVIDIA API key (nvapi-...) from build.nvidia.com. Clone https://github.com/NVIDIA/auto-ontology.git. Required variables in .env (copy from .env.example): DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL=http://localhost:3000, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD, PGADMIN_PASSWORD. Change every default password before exposing the stack beyond localhost; never commit .env.

Step 1 — Clone the repo and create .env:

git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env

Replace each nvapi-your-api-key-here with a real key, or remove it to fall back to DEFAULT_MODELS_API_KEY. For the quickstart, CONNECTION_STRINGS points at the sample database: postgresql://postgres:<your chosen password>@postgres:5432/wideworldimporters.

Step 2 — Start Postgres and seed the sample database (seed script in the separate repo NVIDIA/auto-ontology-eval):

docker compose up -d --wait postgres
git clone https://github.com/NVIDIA/auto-ontology-eval.git ../auto-ontology-eval
(cd ../auto-ontology-eval && uv sync && cp .env.example .env && \
  POSTGRES_PASSWORD=<your chosen password> \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)

Step 3 — Build and run the full stack, open http://localhost:3000, sign in with the admin account from .env, enable Settings → Semantic Compilation, and wait for the ready report.

docker compose up -d --build

Post-install verification

Run docker compose ps, sign in to the web UI, and check Semantic Compilation reports ready and generates terms. Try asking in Chat: “What was revenue for the USB food flash drive - sushi roll in Pennsylvania in June 2015?” Expected result: $588.80, from 3 invoice lines, with SQL and resolution steps. Then ask an out-of-scope question (e.g. about advertising costs) and confirm the agent refuses via check_answerable instead of inventing a number.

Common errors

• Wrong NVIDIA API key: compilation or chat reports a model-call error — check DEFAULT_MODELS_API_KEY starts with nvapi-.
• Missing .env variable: the backend or worker crashes on startup — check logs against .env.example.
• Postgres not ready before the build: ingestion fails, ontology empty — wait for Postgres to be healthy (docker compose up -d --wait postgres) before seeding and building.
• Wide World Importers seed fails: the wideworldimporters database is empty or missing — check uv, the database name, and POSTGRES_PASSWORD.
• Semantic Compilation not enabled: Chat gives generic answers with no terms — enable Settings → Semantic Compilation and wait for ready.

Connecting Your Database and Using It via MCP, API, and Agent Skills

Auto Ontology connects to PostgreSQL, MySQL, Databricks, Snowflake, ClickHouse, Trino, Apache Kyuubi, HeavyDB, DuckDB, and SQLite — via Settings → Connections or CONNECTION_STRINGS; DuckDB and SQLite need only a connection string.

The MCP server exposes 9 read-only tools: check_readiness, search_terms, get_term, get_term_columns, get_term_sql_attributes, get_sql_attribute, describe_table, check_answerable, and ask_question. Read-only matters: an agent can ask questions but cannot modify the ontology through MCP:

AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
  uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp

Configure Cursor (~/.cursor/mcp.json, URL http://localhost:3003/mcp) or Claude Desktop (npx mcp-remote http://localhost:3003/mcp), restart the client, and sign in when prompted. Typical flow: search_terms → get_term_sql_attributes → check_answerable → ask_question.

Ask questions via POST /api/chat/completions, with the x-api-key header (a token created in the user menu → API Tokens). The response is an SSE stream: the result event carries the answer, data: [DONE] ends it:

curl -N http://localhost:3000/api/chat/completions \
  -H "x-api-key: $AUTO_ONTOLOGY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "How many orders shipped last week?"}'

Three coding-agent skills (from AGENTS.md): nvidia-ontology-setup, nvidia-ontology-management, and nvidia-ontology-query. Import/export Apache Ossie models via Settings → Import/Export or POST /api/model/import|export.

Evaluation: Pros, Cons, Security, and Operations

Pros. Every answer comes with SQL and provenance, and out-of-scope questions are refused instead of answered with invented numbers. Definitions are separated from prompts and models. The system is open: Apache 2.0, MCP/CLI/API, Ossie import/export, 10 connectors, Compose or Helm deployment.

Cons. The biggest cost is certification: the larger the ontology, the more effort it takes to maintain and the easier it goes stale when the schema changes. It depends on NVIDIA NIM and an API key — plan to self-host NIM if you want independence. Maturity is still low: 0 releases, no external PRs accepted — pin a checked commit (2a24f5d, dated 2026-11-04) for production use.

Security. Auth and RBAC come from Better Auth, but the key point is the network boundary: keep ports 3001 and 3002 on a private network. The FastAPI backend trusts the x-auto-ontology-user-id header forwarded by the frontend, and the ingestion endpoints (ingest, delete, reset, compile) have no auth of their own — clients should only reach the system through the web app on port 3000. Change every default password in .env, use a read-only database account, and review carefully before enabling Predictions (KumoRFM): when enabled, the agent uploads the connected tables to a hosted service (default maximum 20 tables, KUMO_MAX_TABLES). Predictions is opt-in — without KUMO_RFM_API_KEY it does not run.

Operations. There are no benchmark numbers to cite; what matters is schema size, term count, whether the NIM model is hosted or self-hosted, and pgvector. Measure in practice with the Wide World Importers compilation time and the sample-question response time. Back up Postgres and export Ossie YAML regularly; after every schema change, recompile, recertify, then publish. Before each recompilation or new ontology import, export Ossie YAML and snapshot Postgres — if the new ontology is wrong, restore that backup instead of fixing terms by hand.

Comparison with Alternatives in the Same Space

Raw text-to-SQL — the LLM generates SQL directly from the schema, with no semantic layer. Quick to try and free of certification effort, but the model guesses JOINs and formulas with no refusal gate — fine for demos, not for numbers that drive decisions.

Graphify — already covered on the blog (Graphify: knowledge graph for AI agents). Graphify turns a codebase, documentation, and SQL schema into a knowledge graph for a coding agent. Auto Ontology is quite different: a certified semantic layer over live business databases so an analytics agent returns correct numbers, with check_answerable, provenance, RBAC, MCP, and a web UI.

Traditional BI semantic layers — these also define each metric once for shared use. Auto Ontology differs by generating the ontology automatically from metadata and exposing it directly to agents via MCP. In my view, if you only need dashboards and already have a good BI semantic layer, you may not need Auto Ontology as well.

Real-World Use Cases

Business: “Revenue”, “active customers”, and “margin” are defined and certified once, shared by every agent and report; when a definition changes, the data team reviews it in one place.

Homelab: run the stack with Docker Compose against Postgres, MySQL, DuckDB, or SQLite at home, with a read-only account, on the internal network.

AI workflows: attach Auto Ontology to a coding or multi-step agent via MCP — the agent calls search_terms → get_term_sql_attributes → check_answerable → ask_question, and the SQL with provenance becomes evidence attached to the workflow.

DevOps / IT admin: deploy with Compose or Helm, back up with Postgres snapshots and Ossie YAML exports; when the schema changes, recompile → recertify → publish; roll back from the previous export.

Conclusion

Worth using when your team has a business database, someone owns metric definitions, you need agents to return verifiable numbers, and you accept the certification cost. Not yet worth it for quick Q&A over a small database, with no definitions to standardize or no one to certify.

Next step: run the Quickstart with Wide World Importers, see the $588.80 answer with SQL and provenance, then connect your real database with a read-only account and certify a small group of terms first.

Lessons Learned

1. Wrong numbers usually come not from a weak model but from a missing certified shared definition — fix it at the ontology layer.
2. The value lies in the refusal gate (check_answerable): a timely “cannot answer” beats an invented number.
3. Human certification is the bottleneck — ontology maintenance cost, not inference cost, decides whether the project survives past its first week.
4. A semantic layer is only trustworthy when the network boundary is right: exposing the backend and worker ports breaks its own security promise.
5. Do not scale up before proving a small group of terms works end to end: sample question → SQL → provenance → reconcilable numbers.

Verification Scope

Checked on 2026-11-05 against the official documentation and GitHub API of the NVIDIA/auto-ontology repo (6,469 stars, 510 forks, commit 2a24f5d, 0 releases). Install steps come from the official documentation, not run in the blog’s lab. The 31-term and $588.80 figures are project documentation examples, not independently reproduced; no BIRD scores are cited because the documentation provides none. The embed/rerank default-model conflict is stated in the article — when deploying, use .env.example as the standard.

References

• NVIDIA Auto Ontology — official repo: https://github.com/NVIDIA/auto-ontology
• MCP server documentation: https://github.com/NVIDIA/auto-ontology/blob/main/docs/mcp.md
• Data source connection documentation: https://github.com/NVIDIA/auto-ontology/blob/main/docs/connections.md
• NVIDIA API catalog (for the nvapi-... API key): https://build.nvidia.com/
• Related article on phamnam.me — Graphify: knowledge graph for AI agents: https://phamnam.me/posts/graphify-knowledge-graph-cho-ai-agent/