A schema dump into the context window is the cheapest way to give an agent database access, and it is also the reason agents confidently return wrong revenue numbers. The column names are there. The meaning is not. NVIDIA's auto-ontology takes a different route: it compiles database metadata into an ontology — business terms mapped to columns, reviewed metric SQL, and relationships between tables — and lets the agent query through that layer.
The project is Python, Apache-2.0, and sits at 4406 stars on the original repository. A Chinese translation of its documentation was published on 2026-11-05 at https://github.com/yangshun2005/auto-ontology-cn. That translation is what this article is about, plus what the tool actually does.
What the service is
Auto-Ontology runs next to your database. It ingests metadata and compiles an ontology from it. The ontology holds three things:
- business terms mapped to specific columns
- reviewed SQL expressions for metrics
- relationships between tables
An agent queries through the ontology instead of through raw schema. Before answering, it checks whether the question is answerable at all. When it does answer, it returns the SQL it ran and the reasoning steps, so a human can check the work.
The README frames the problem in terms of reliability rather than speed: a revenue figure computed quickly is worthless if it is wrong. The agent needs to know where the data lives, what it means, whether it should be used, how to use it, where it came from, and which data is similar. That is the context layer.
The comparison that matters
The README includes a table contrasting schema-in-context with the ontology tool approach. It is worth reproducing because it is the clearest statement of the design intent:
| Schema in context window | Auto-Ontology tools | |
|---|---|---|
| Token | Grows with every table and column | Only terms and tables relevant to the question |
| Meaning | Column names only, rest inferred by the agent | Business terms mapped to columns and SQL |
| Joins and metrics | Improvised per question | Resolved relationships and reviewed SQL expressions |
| Unanswerable questions | Confident answers, often wrong | Answerability check, agent asks for clarification |
The last row is the one that changes behavior most. An agent that can say "I can't answer this from the available definitions" is more useful than one that produces a plausible-looking number.
Quickstart, as documented
The README's quickstart uses Docker Compose against the Wide World Importers sample database. The steps, in order:
Clone and configure:
git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology cp .env.example .env Then set DEFAULT_MODELS_API_KEY (an nvapi-... key), AUTH_SECRET, APP_URL=http://localhost:3000, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD, and PGADMIN_PASSWORD in .env. The README gives a full example of each value.
Start Postgres and seed the sample database. The seed script lives in the separate auto-ontology-eval repository:
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=' ' \ uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop) Build and start the remaining services:
docker compose up -d --build Open the app, log in with AUTO_ONTOLOGY_ADMIN_EMAIL and AUTO_ONTOLOGY_ADMIN_PASSWORD from .env, go to Settings → Semantic Compilation, and turn it on. Ingestion runs at startup; when compilation finishes you should see Semantic compilation is ready.
Then ask a question in Chat. The README's example concerns revenue for a product in Pennsylvania in June 2015. The answer comes back with SQL and reasoning steps attached.
Requirements
Docker and Compose v2 are required by the quickstart, as is uv. The project's pyproject.toml requires Python >=3.12. The Dockerfile is based on nvcr.io/nvidia/base/ubuntu (jammy), and the Makefile's default multi-arch release targets are linux/amd64,linux/arm64. The README does not specify special hardware requirements, and does not constrain the host OS beyond what Docker implies.
What the Chinese version adds
The translation repository is explicit about its structure. The README body is a translation of the original documentation, kept close to the source. On top of that, the page opens with a section labeled 中文快速上手 ("Chinese quick start") that is marked as supplementary material, not part of the original text.
That distinction is the useful part. A translated README is helpful; a translated README with a short path to a running instance in front of it is more helpful. The quick-start section answers four questions before the reader hits the full documentation: what this is, what problem it solves, what the shortest path to a working setup looks like, and what the environment needs.
For a project whose setup involves a .env file with seven or eight variables, a second repository for seed data, and a settings toggle that must be flipped before anything works, that ordering matters. The barrier for a Chinese-speaking developer is not usually the English prose in the middle of the README — it is the sequence of shell commands and the config values, where a single mistyped variable name produces an opaque failure.
The translation also states its own limits: inaccuracies should be reported as an Issue or PR. That is the right posture for a translated technical document, since the original is the authority and will keep moving.
How the pieces fit
The system has five verbs in the README's own framing, and they describe the workflow rather than the architecture:
- Discover — generate an ontology from database metadata, import existing semantic models, explore the result as a semantic graph.
- Anchor — give each business concept a single definition, mapped across tables and databases.
- Certify — review, edit, and certify definitions in the UI or via API.
- Validate — check answerability before querying, return SQL and agent steps with every answer.
- Expose — serve the context to any agent framework through MCP, agent skills, and a REST API.
The MCP and REST surfaces are what make this framework-agnostic. The ontology is not tied to a particular agent runtime.
Evaluation
The companion repository auto-ontology-eval measures ontology performance on benchmarks. The README names BIRD, BEAVER, FDABench-Lite, and Wide World Importers, with each evaluation item pairing a question against gold-standard SQL. I have not run these benchmarks myself, so I can't speak to the numbers — the eval repository is where to look for them.
Who this is for
If you are building agents over an enterprise database and you have already hit the failure mode where the agent answers confidently and wrongly, the ontology approach is worth evaluating. The cost is real: you have to define business terms, review metric SQL, and certify definitions. That is human work, and it does not disappear because a service compiles metadata.
The Chinese translation lowers the entry cost for teams whose developers read Chinese more comfortably than English. It does not change what the tool does. The original repository is still the source of truth, and the translation says so.
The Chinese version is new — published 2026-11-05, with no stars yet. The original has 4406. If you are working through the quickstart and something in the translated text does not match what you see, the original README is the place to check first.
Chinese documentation: https://github.com/yangshun2005/auto-ontology-cn
I'm an independent enterprise AI delivery consultant — private LLM deployment, RAG, agent workflows, AIOps. If your team is stuck somewhere in that stack, my inbox is open.
