Ontologiq documentation
Ontologiq is a command-line compiler for your operational ontology: the business objects your company runs on — customers, orders, contracts — described once, in YAML, next to your code.
Semantic layers tell you how much. Ontologiq knows who, in what state, and what may be done.
Start here
| Page | What it covers |
|---|---|
| Quickstart | A working project in five minutes, no credentials. Install, scaffold, build, look at a record. |
| Demo | The whole product in one walkthrough: YAML → SQL → an AI agent proposing an action → a human approving it → the audit trail. |
New here? Read those two in order. Twenty minutes and you will know whether this is useful to you.
Understand
| Page | What it covers |
|---|---|
| Concepts | Objects, identity, properties, state, relations and governed actions — the model behind the format. |
| Security model | What is enforced, what is only declared, and the threats each control answers. Read before trusting it with anything. |
| Roadmap and status | What works, what is deferred on purpose, known limitations, and where help would matter. |
Reference
| Page | What it covers |
|---|---|
| YAML reference | Every field of the format, with the semantics the compiler implements. |
| CLI reference | Every command and flag, and what each one does and does not touch. |
| MCP reference | The tools generated for AI agents, their inputs and outcomes, and connecting Claude Desktop. |
| Adapters | Which warehouses are supported, connection settings, and how to write an adapter. |
In three sentences
You describe an object once: where it lives, what identifies it, what states it can be in, what it relates to, and which actions may be performed on it. The compiler turns that into SQL views your analysts can query, a catalog for tooling, and typed MCP tools an AI agent can call. Actions carry roles, preconditions, approval rules and an audit trail — and never write to your database, because effects are your webhooks and your handlers.
What it is not
It is not a metrics layer — Cube, MetricFlow and OSI model aggregates, and this is the layer of entities underneath them. It is not a data-access proxy: anyone with warehouse credentials can query your tables directly, and Ontologiq governs the path you give to agents, not the database. It is not a BI tool, an orchestrator, or a database.
Status
Alpha, and honest about it. Objects, state, relations, governed actions, SQL compilation, the MCP server and the action runtime work end to end on DuckDB today. The visual workbench and a real Databricks adapter are next.
The project is built and maintained by one person so far. Issues, ideas and pull requests are genuinely welcome — see contributing.