Question-led guide · how-to
How do I define a metric before a data agent queries it?
Specify a business metric’s population, event time, exclusions, aggregation, and owner before an agent translates a question into SQL.
Direct answer
Define the metric as a decision contract before asking an agent to write a query. Record the business question, entity grain, included population, time rule, numerator, denominator, exclusions, valid source, and owner. Test at least one boundary case where two plausible definitions diverge. A syntactically correct query can still answer the wrong question if those choices remain implicit or the definition is no longer valid.
Name the decision that needs the number
“Revenue” may support a promotion review, finance close, or a customer-support explanation. Those decisions may legitimately use different time and exclusion rules. State who will act on the result and what discrepancy would matter. An agent cannot infer the intended measure reliably from the word alone, even if it knows every table and can generate executable SQL.
Resolve grain before writing arithmetic
Choose whether the unit is an order, payment, invoice, line item, or customer. Then specify the included population, canceled and refunded cases, currency conversion, and effective date. A sum over payment rows may duplicate an order with two captures; a sum over orders may include unpaid work. The contract must say which source event is authoritative for the decision.
Two answers from the same shop
In a constructed store, ten orders total $1,000 at order time. One $100 order is never paid, while a $50 payment for an older order arrives today. “Today’s ordered value” is $1,000 and “today’s captured payment” is $950. Both queries can be valid. The agent should ask which decision the user means or select a governed definition with the time and population stated in its answer.
Use a metric contract card
A short card supplies what a generated query cannot invent safely.
| Field | Example entry |
|---|---|
| Decision | Daily captured-payment review |
| Grain | Payment capture event |
| Time | Capture timestamp in named business zone |
| Inclusion | Successful captures; exclude reversals |
| Source | Versioned payment-event table |
| Owner | Finance analytics lead |
Test the boundary with paired questions
Write one question that the metric should answer and one that it should refuse or reinterpret. Include a refund, late arrival, duplicate capture, or timezone boundary. Compare the agent’s query with a reviewed reference and inspect the rows, not just the final number. Record whether the agent used the current definition or a cached one from an earlier release.
Publish meaning before automating interpretation
Store the metric definition where both people and agents can retrieve it with version and owner. If the population changes, create a reviewed revision and identify historical reports affected. A semantic model can encode measures and entities, but the business owner still has to decide the meaning. Do not let a frequent agent query silently redefine the metric by usage.
Evidence boundary for business metrics
- dbt semantic models: dbt documents semantic model structure and metric inputs. The documentation does not select the fictional shop’s revenue policy.
- OpenLineage object model: OpenLineage describes jobs, runs, and datasets with source metadata. Lineage alone does not define business meaning or inclusion rules.
The order and payment totals are invented. Finance owners must approve the actual definition and source reconciliation.
Evidence
Semantic models describe entities, dimensions, and measures for governed metrics.
dbt documents semantic model structure and metric inputs.
Primary source · official-doc · checked Oct 7, 2026
Limit: The documentation does not select the fictional shop’s revenue policy.
Dataset and job lineage can identify data production paths.
OpenLineage describes jobs, runs, and datasets with source metadata.
Primary source · official-doc · checked Oct 7, 2026
Limit: Lineage alone does not define business meaning or inclusion rules.
Limitations
The card cannot replace actual data quality checks, source ownership, or a decision on conflicting business definitions.
FAQ
- Can the agent infer a metric from column names?
- It can propose an interpretation, but the business decision and exclusion rules still need a governed definition.
- What if two teams need different definitions?
- Give each definition a distinct identity and scope instead of making one overloaded label silently change by context.
Related guides
Continue within Evolving semantic layers for data agents, or use one of these adjacent diagnostics:
Editorial QA: automated native-English, structure, source-presence, and link checks completed . This record is not an independent expert endorsement. Review boundary.