Auto Ontology: Traceable semantic querying for agentic enterprise data
A Postgres semantic layer for enterprise data agents that returns verifiable SQL and provenance.
GitHub NVIDIA/auto-ontology Updated 2026-11-05 Branch main Stars 5.0K Forks 398
Python TypeScript Postgres NVIDIA NIM MCP Natural-language-to-SQL Enterprise knowledge graphs Docker Compose

🧭 Decision Guide

Try it if you

  • You need an LLM agent to query relational databases and return SQL together with execution steps
    Step 5 of the README Quickstart shows a natural-language question, generated SQL, and execution Steps.
  • You already have enterprise semantic models and want to connect them into AI-ready knowledge graphs
    The README Discover section supports connecting existing ontologies and semantic models and building AI-ready knowledge graphs.
  • Your agent integration uses MCP, CLI, or API and requires authentication and RBAC
    The README says context is exposed through MCP, CLI, and API, while Key Features lists Better Auth authentication and RBAC.

Skip it if you

  • Your data includes advertising spend while the connected source is only Wide World Importers
    Step 6 of the Quickstart explicitly says Wide World Importers has no advertising data, so ad spend cannot be resolved.
  • You need external contributions or stable releases to extend the project
    The Licensing & contributions section says external contributions are currently not accepted, and project metadata shows 0 releases.
  • Your data-governance policy forbids uploading connected tables to a hosted prediction service
    The Predictions section says KumoRFM uploads connected tables and limits their number with KUMO_MAX_TABLES.

Requirements

  • Docker with Compose v2, uv, and an NVIDIA API key from build.nvidia.com (README Quickstart)
  • You must configure DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL, POSTGRES_PASSWORD, and CONNECTION_STRINGS
  • The Quickstart uses Postgres, pgAdmin, and the Web app, and loads the Wide World Importers sample database
  • The embedding model must match between ingest and query; model roles use the _ENDPOINT, _API_KEY, and _MODEL triplet

First step (verbatim from README)

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

Watch out

  • Replace default passwords in .env before startup or Compose will expose default credentials
    Quickstart step 1 requires replacing every default password, including POSTGRES_PASSWORD, AUTO_ONTOLOGY_ADMIN_PASSWORD, and PGADMIN_PASSWORD.
  • You must manually enable compilation under Settings → Semantic Compilation on first use
    Quickstart step 4 requires opening Settings → Semantic Compilation and enabling it.
  • A missing left navigation after restart may come from a stale localhost:3000 session cookie
    The Quickstart troubleshooting note says to clear site data for localhost:3000 and sign in again.
  • KUMO_MAX_ROWS_PER_TABLE is unlimited by default for KumoRFM
    The Predictions section states that KUMO_MAX_ROWS_PER_TABLE is unlimited unless set.

Not stated in the README

  • The README does not provide supported Postgres versions, a complete connector list, or limits for non-Wide World Importers sources.
  • The README does not list specific NVIDIA NIM model names, endpoint requirements, or costs.
  • The README does not state the CPU, memory, GPU, or concurrency requirements for production.
  • The README does not provide the complete permission model or interface details for MCP, REST API, and Web UI.
  • The README does not clarify whether 0 releases means the API is unstable or provide compatibility commitments.

💡 Deep Analysis

6
Yes I need to support revenue queries, but when Wide World Importers has no advertising data, the agent must explicitly refuse ROAS. Can Auto Ontology satisfy this answerability constraint?
For: A developer responsible for a business-analytics Copilot that must refuse ROAS calculations when the source has no advertising-spend data instead of generating plausible SQL

Yes. The README directly demonstrates the required behavior with Wide World Importers: determine answerability before running a query.

  • The revenue example resolves revenue, product, and state and follows ontology relationships to build the required joins.
  • For a return-on-ad-spend request, the README states that Wide World Importers has no advertising data, so there is no ad-spend term to resolve.
  • The MCP-connected agent calls check_answerable first, explains that it can find revenue but cannot compute ROAS, and asks whether to query June 2015 revenue instead or connect another source.
  • This fits a Copilot that must expose data boundaries rather than force every natural-language request into SQL.

The behavior still depends on the ontology and its coverage. The README does not define coverage thresholds, ambiguous-term handling, or how answerability is combined when multiple sources each contain only part of a metric.

  • README, Quickstart: “Wide World Importers has no advertising data”
  • README, Quickstart: “check_answerable -> coverage 0.5; no term covers ‘ad spend’”
  • README, Quickstart: “I can find revenue ... but this data has no advertising spend, so I can't compute return on ad spend”
  • README, Introduction: “whether to use it” and “where it came from”
Not stated in the README:The README does not explain how coverage values such as 0.5 are calculated or whether the threshold is configurable.;It does not define answerability rules for partial coverage, same-named metric conflicts, or inconsistent time ranges across sources.
Yes I have PostgreSQL relational data and the Wide World Importers sample database, and my team wants to validate natural-language querying locally with Docker Compose. Is Auto Ontology suitable for this path?
For: A data engineer maintaining relational databases and an enterprise data platform who wants to expose structured data such as Wide World Importers to an agent

Yes, because the README provides a complete Quickstart for PostgreSQL, Wide World Importers, and Docker Compose. However, it is not a tool where connecting a database alone is sufficient.

  • It generates an ontology from enterprise metadata and stores the semantic catalog in Postgres; natural-language questions are translated into executable SQL.
  • After startup, the sample database must be loaded and semantic compilation must be enabled under Settings → Semantic Compilation. Queries should not be treated as ready before compilation finishes.
  • Results include SQL and reasoning steps, such as resolved revenue, product, and state terms and the actual join path, which supports source-level verification.
  • Docker Compose publishes Postgres, pgAdmin, and the web app; the README requires replacing default passwords and configuring an NVIDIA API key.

This is therefore a good local validation path. Production integration still depends on the completeness of metadata, metric definitions, and database permissions.

  • README, Quickstart: “This runs Auto-Ontology with Docker Compose against Wide World Importers”
  • README, Key Features: “Natural-language querying of structured data” and “Semantic catalog / ontology layer over relational sources”
  • README, Quickstart: “Go to Settings → Semantic Compilation”
  • README, Quickstart: “The answer comes back with its SQL and the steps that produced it”
git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env
Not stated in the README:The README does not define the production boundary for federated queries across multiple relational databases.;It does not specify performance limits for high concurrency, real-time updates, or large-scale metadata ingestion.
Yes I am building an enterprise agent based on MCP, using NVIDIA NIM for reasoning, and I need to preserve SQL, parsing steps, and provenance. Is Auto Ontology more suitable than asking an LLM to generate SQL directly?
For: An AI engineer building an enterprise Copilot or MCP agent who needs structured-query capabilities through NVIDIA NIM, MCP, CLI, or an API

Yes, because it places semantic grounding, query generation, validation, and provenance in one agent-context flow instead of returning only a SQL string.

  • The README explicitly exposes context through MCP, CLI, and API to any agent harness, so an existing MCP agent can integrate without adopting the project’s Web UI.
  • Natural-language querying is powered by NVIDIA NIM and translates questions into SQL executed against connected databases.
  • The example response returns the Answer, SQL, and Steps, including resolved business terms, join paths, and validated filter values.
  • For an uncovered request such as advertising spend, the MCP agent runs check_answerable first and explains that ROAS cannot be computed rather than fabricating a query.

However, the README gives no latency, cost, model-hosting, or authorization-isolation targets. Explainability alone should not be interpreted as a production SLA.

  • README, Introduction: “exposes it to any agent harness through MCP, CLI, and API”
  • README, Key Features: “Natural-language querying ... powered by NVIDIA NIM”
  • README, Quickstart: “The answer comes back with its SQL and the steps that produced it”
  • README, Quickstart: “check_answerable -> coverage 0.5; no term covers ‘ad spend’”
docker compose up -d --build
Not stated in the README:The README provides no throughput, latency, retry, or concurrency metrics for MCP tool calls.;It does not explain how agent-side identities map to row-level or column-level database permissions.
Yes We already maintain enterprise semantic models, certified metrics, and data lineage. We want to preserve those assets while helping an agent understand metrics such as revenue more accurately. Is Auto Ontology suitable?
For: A data governance practitioner responsible for metrics, data catalogs, and lineage certification who already owns semantic models and does not want to replace them

Yes, because the project explicitly complements customers’ existing semantic models rather than requiring governance teams to rebuild all semantic assets.

  • Its Discover capability can connect existing ontologies and semantic models while generating AI-ready knowledge graphs from enterprise metadata.
  • Ground supplies agents with business meaning for metrics, entities, and relationships, helping reconcile definitions across systems.
  • Validate checks generated queries against certified definitions and lineage and returns provenance with the answer. This is more aligned with governance workflows than generating SQL from column names alone.
  • Learn can fold certified corrections and usage back into the ontology, creating a loop between governed assets and runtime querying.

The outcome still depends on whether existing semantic assets can be connected, certified, and maintained. The README does not specify which external semantic-model formats are directly importable, nor does it promise to resolve every metric-definition conflict automatically.

  • README, Introduction: “It complements the semantic models customers already own”
  • README, Discover: “connect existing ontologies and semantic models”
  • README, Ground: “give agents trusted business meaning for metrics, entities, and relationships”
  • README, Validate / Learn: “check generated queries against certified definitions and lineage” and “fold certified corrections and usage back into the ontology”
Not stated in the README:The README does not list the external ontology, semantic-model, or catalog formats that can be imported directly.;It does not describe approval roles, change auditing, or conflict-resolution mechanics for certification.
Yes I am building a Web application for business analysts. Results cannot be just a number; they must show SQL, reasoning steps, and provenance. Is Auto Ontology suitable for this auditable query interface?
For: An analytics-application developer whose natural-language results must be reviewed by audit or business users and must include SQL, steps, provenance, and certified definitions

Yes. The project’s example output and feature design treat SQL, steps, provenance, and validation results as part of the answer rather than hiding them in the backend.

  • The Web UI covers chat, analysis, data catalog, analytics, and settings, which supports a business-analysis workflow starting from a conversational question.
  • The example answer shows SQL, resolved terms, joined paths, and the statement “Validated the filter values against the data, then executed.”
  • The README says Validate checks generated queries against certified definitions and lineage and returns provenance with every answer.
  • Authentication & RBAC can control access to the Web application, but that is not the same as fine-grained database authorization.

It is therefore suitable as a reviewable query interface or context layer. If audit requirements include immutable logs, a complete user-identity chain, or regulatory retention periods, the README does not provide enough evidence.

  • README, Key Features: “Web UI for chat, analysis, data catalog, analytics, and settings”
  • README, Quickstart: “The answer comes back with its SQL and the steps that produced it”
  • README, Quickstart example: “Resolved terms”; “Joined”; “Validated the filter values against the data, then executed”
  • README, Validate: “return provenance with every answer”
docker compose up -d --wait postgres
Not stated in the README:The README does not say whether provenance, SQL, and user-action logs support tamper-evident storage.;It does not define audit-retention periods, export formats, or integration with enterprise SIEM systems.;It does not state whether the Web UI supports custom business review or approval workflows.
It depends I cannot run the enterprise data service long-term on local Docker Compose. It must be deployed on Kubernetes, and the Web UI must provide authentication and RBAC. Is Auto Ontology suitable?
For: A platform engineer operating Kubernetes who needs to deploy the semantic-query service in a controlled cluster with authentication and RBAC

It depends. The deployment model and basic application authentication fit, but the README does not prove that all security and operational requirements for enterprise Kubernetes production are covered.

  • Key Features explicitly provide a Kubernetes Helm chart as well as Docker Compose, giving a platform team an entry point from local deployment to a cluster.
  • The project provides Authentication & RBAC using Better Auth, which covers basic application login and role control.
  • The Quickstart requires AUTH_SECRET, an admin password, a Postgres password, and an NVIDIA API key, and explicitly says to replace default passwords. Credential management is therefore a deployment prerequisite.
  • Project data shows release_count is 0 and latest_release is empty. Upgrade guarantees, compatibility policy, and production change cadence cannot be confirmed from the public information.

If your requirements include database row/column security, tenant isolation, HTTPS, key rotation, or high availability, Helm and RBAC alone are not enough evidence.

  • README, Key Features: “Flexible deployment — Helm chart for Kubernetes or Docker Compose for a local stack”
  • README, Key Features: “Authentication & RBAC — using Better Auth”
  • README, Quickstart: “replace each default password before you start it”
  • Project data: release_count is 0 and latest_release is empty
Not stated in the README:The README does not describe high availability, backup, upgrade rollback, or monitoring configuration for the Helm chart.;It does not say whether Better Auth RBAC integrates with row-level, column-level, or tenant-level database permissions.;It does not specify production network isolation, TLS, or key-rotation patterns.

✨ Highlights

  • MCP, CLI, and API expose semantic context together
  • Postgres stores the semantic catalog for relational sources
  • NVIDIA NIM powers natural-language-to-SQL
  • Apache 2.0 licensed, but external contributions are currently not accepted

🔧 Engineering

  • Generates ontologies from enterprise metadata and connects existing semantic models
  • Validates generated SQL against certified definitions and lineage, then returns provenance
  • Docker Compose or Helm deployment includes a Web UI and RBAC

⚠️ Risks

  • The Quickstart requires Docker Compose v2, uv, and an NVIDIA API key
  • The project currently accepts no external contributions and has 0 releases
  • KumoRFM uploads connected tables, with a default cap of 20 tables
  • The embedding model must match between ingest and query

👥 For who?

  • Python teams that need to give LLM agents a semantic layer over enterprise Postgres
  • Developers building data-agent workflows with MCP, CLI, or API
  • Teams that want to evaluate the system with Wide World Importers through Docker Compose