One request shape for every consumer

Every consumer wants the same thing: a named metric, a time range, a few filters, and a grain. Dashboards encode that in chart configs. Notebooks encode it in SQL strings. Agents encode it in free-form tool calls. When each consumer invents its own shape, the semantic layer becomes a suggestion, not a contract.

One shape beats many dialects

A single request shape means metric name, dimensions, filters, and time window look the same whether the caller is a BI tile, a backend job, or an MCP tool. The warehouse still runs SQL. The difference is that the translation from intent to SQL happens in one place.

That matters for agents especially. Models are good at filling structured slots and bad at inventing consistent SQL across sessions. If the only interface is “write whatever query you like,” you get drift. If the interface is “fill this request object,” you get repeatable behavior.

What the request carries

A useful request is small. It names the metric. It states the time grain and range. It lists dimensions to break down by. It adds filters that the metric allows. It does not ask the caller to join tables or pick aggregation functions. Those belong in the metric contract.

When agents use datahashi, that shape shows up in run_semantic_query. Before they query, they can call list_catalog to see what exists and describe_metric to learn which dimensions and filters are valid. The request stays thin. The meaning stays in the model.

Consumers share the contract

APIs, notebooks, and agents should not each maintain a private dictionary of “how we compute churn.” They should point at the same metric id. When finance updates the definition, every consumer picks it up on the next call. You stop patching five clients for one business change.

This is also how you keep access control coherent. Authorize against metric and dimension names, not against ad hoc SQL strings. Auditing becomes easier because every successful call looks like a structured request, not a novel query.

What datahashi does not claim

datahashi is a thin layer. Metering exists so you can observe usage. Rollups have shipped for hot questions. They are not a p99 promise. Performance work beyond that still belongs in the warehouse and in careful metric design. The product focus is one governed request shape and discoverable contracts.

Why agents benefit immediately

Agents chain tools. A planner that gets a stable JSON-shaped answer can feed the next step without reparsing prose. A planner that gets a different SQL dialect every time has to re-interpret everything. One request shape reduces that friction and makes evaluation possible: you can compare agent runs against the same metric ids.

Keep the interface boring

Boring interfaces scale. Exciting SQL generators do not. Put creativity in the agent plan, not in how metrics are requested. Name the metric. Set the grain. Apply filters. Run the query. That is enough for most agent and API workloads today.

If your stack still has a separate request dialect for each consumer, you are teaching the same lesson many times. Converge on one shape. Let the semantic layer own the translation. Let every consumer, including agents, speak the same language.