Talk with our engineers by joining the new Onehouse community Slack!
Core capabilities
Semantic layer: governed natural language queries
Use the Onehouse semantic layer to let people and agents ask questions of your data in natural language and get answers that are accurate, governed, and repeatable. You define your business metrics, dimensions, and the relationships between tables once, as semantic models in the Onehouse catalog. When someone asks a question through the AI Gateway, the language model picks the metrics and dimensions the question needs. The SQL is generated from those certified definitions and runs on Lakegres as the user who asked. The semantic layer is in preview.
Why text-to-SQL needs a semantic layer
A language model writing SQL directly against your tables has to guess at the business rules the schema does not contain. Asked for net revenue by region last quarter, it may read a backup table because the name looks plausible, count refunded and test orders because nothing in the schema says to exclude them, and treat “last quarter” as the last 90 days. Asked again the next day, it may pick a different table and return a different number. Joins can also double-count: an order with three line items has its amount counted three times, and the inflated total still looks believable.
A semantic layer moves those decisions out of the model. The definition of net revenue, including its filters, its source tables, and how they join, lives in a certified semantic model, so the model only has to choose the metric, the dimensions, and the time range. The SQL is then generated the same way every time, so answers are accurate, reproducible, and deterministic.
Semantic models
To set up the semantic layer, you write semantic models. Each one describes part of your business in the terms people ask about:
- Metrics, from simple totals to ratios, derived metrics, cumulative metrics such as year-to-date, and conversion metrics, with their business filters built in.
- Dimensions to group and filter by, including time.
- Relationships between tables, so joins follow the declared keys and never double-count.
- Descriptions and synonyms, so a question in everyday words finds the right metric.
You can write semantic models by hand or load them in bulk from a coding agent. Through the Onehouse MCP server, a Claude Code or Codex session can draft semantic models from your tables and upload them to the catalog for review and certification. Semantic models use the open Apache Ossie (Open Semantic Interchange) format, so they are portable across tools. They live in the Onehouse catalog alongside your tables. Each model is versioned, with draft and certified versions, and validated when saved.
How a question is answered
- The right metrics are found. A question is matched against the certified metrics the user is allowed to see. When it could mean more than one thing, such as gross or net revenue, the user is asked instead of guessing.
- SQL is generated from the definition. The certified source tables, business filters, join paths, and exact date ranges come from the semantic model, so the same question produces the same SQL and the same number every time.
- The query runs as the user. Lakegres runs it read-only, as the person who asked, under the governance catalog policies.
- The results are shown with their derivation. Each answer carries the metric and its version, the resolved dates, and the SQL that produced it, and every answer is audited.
A natural language question, answered from certified definitions.