Entities and relationships in the semantic model

Metrics do not float. They belong to entities: customer, account, order, subscription, workspace. Relationships connect those entities so a query can move from one to another without freehand joins. A semantic model that only lists metric names is half finished. Agents need the graph underneath.

Start with entities

An entity is a business object with a stable key and a clear grain. Customer is not the same as user if your product distinguishes them. Account is not the same as organization if billing and tenancy differ. Name entities the way the business speaks, then map them to tables.

Dimensions hang off entities. Metrics measure something about an entity at a grain. When an agent asks for revenue by plan, the model should know that plan is a property of subscription or account, not a random column on an events dump.

Relationships carry join rules

Relationships declare how entities connect: customer has many orders, order belongs to customer, workspace has many members. The semantic layer uses those edges to compile safe joins. Consumers request metrics and dimensions by name. They do not paste join conditions into every call.

That is especially important for agents. Models will invent joins that look plausible and are wrong: fan-outs that inflate revenue, filters applied on the wrong side of a relationship, or keys that almost match. A declared relationship graph reduces that class of error.

How agents navigate the model

Discovery comes first. With datahashi, list_catalog shows entities and metrics an agent can use. describe_metric explains which entity a metric belongs to and which dimensions are valid. run_semantic_query then requests the metric with allowed breakdowns and filters. The agent plans in business terms, not in table aliases.

Metering exists so teams can see which entities and paths are actually hit. datahashi stays a thin layer over your warehouse. Rollups have shipped for hot questions. A p99 latency target has not. Modeling quality matters more than speed claims.

Modeling tips that age well

Keep entity keys explicit. Prefer one primary path between two entities unless you truly need alternatives. Document relationship cardinality so fan-out risk is visible. Avoid modeling every warehouse table as an entity; model the objects product and finance already argue about.

When two teams disagree on an entity boundary, resolve that before publishing metrics. A metric attached to the wrong entity will pass demos and fail audits. The same-number test assumes the entity grain is shared.

Relationships and filters

Filters should respect entity scope. Filtering orders by customer region is different from filtering customers by region and then counting orders. The model should make the intended path obvious. Agents that only see column names will guess. Agents that see entity-scoped dimensions will guess less.

Grow the graph deliberately

You do not need a complete enterprise ontology on day one. Model the entities behind your top metrics. Add relationships only where consumers already need to cross them. Expand when a new agent workflow or dashboard repeatedly asks for the same join.

A semantic model is a map, not a warehouse clone. Entities and relationships give agents a safe way to walk that map. Metrics give them something worth measuring once they arrive. Put both in the contract, and keep the layer thin enough that the map stays trustworthy.