Executable Definition
also called Computable Definition, Definition Binding
Writing a business term so that it compiles to exactly one query - naming the event the grain the window the exclusions and the late-data rule - so two teams implementing it independently cannot produce different numbers.
A glossary entry reads "Active Customer: a customer who has meaningfully engaged with the product in the last 30 days." It has an owner, a review date and a link in the catalogue. Two teams implement it from that sentence and their counts differ by 9%.
Nobody made a mistake. One team counted logins and the other counted any event that wrote data. One counted accounts, the other counted the users inside them. One used the last 30 days in the warehouse time zone, the other the last 30 days ending at the customer's local midnight. Each choice moves the number a few per cent, and the text decided none of them.
An executable definition removes those choices: the five clauses that decide the answer, written so one person can turn the text into a single query without asking anybody a question.
Why it matters
The disagreement this prevents is small enough to be mistaken for a defect. A 9% gap does not look like a semantic problem, so it is investigated as a data problem, and a fortnight goes into reconciling figures that were never going to match. Governance programmes that measure glossary coverage rather than executability report 90% coverage while every number is still contested.
An executable definition can also be implemented once. Until a term has its five clauses a semantic layer has nothing to hold, because the centre does not know what it means either.
Implementation patterns
- Name the countable event as a condition on a specific table or upstream metric, not as a
behaviour. "Any row in
fct_eventswhereevent_typeis in the engagement list" is executable; "meaningful engagement" is not. - Name the grain. Account, user, device, subscription. The commonest source of divergence and almost never written down.
- Name the window and its boundary, with the time zone and whether the end is inclusive.
- Name the exclusions and tie-breaks: internal staff, test accounts, refunded orders, a user who belongs to two accounts in the period.
- Name the late-data rule - whether a published figure may change when events arrive late, and for how long.
- Bind the entry to the implementation. The glossary links to the metric definition in the semantic layer, and that definition's tests are the glossary's enforcement. A glossary holding a rival prose description drifts from the code within two quarters.
Industry example
Metric layers in production - tools that compile a metric definition into SQL for every consuming client - make this property mechanical: the definition is a file with a filter, a grain, a time dimension and a set of tests, and a dashboard cannot express a metric the file does not define. Teams that adopt one discover how few glossary entries survive the translation. The usual finding is that under 30 of several hundred entries are computable at all, and that those 30 are the ones leadership reads.
Failure scenarios
- Two correct implementations, found when a board number and a team number differ by single digits and both are defended.
- A definition change with no restatement decision, so last quarter's reports silently use this quarter's meaning and nothing in the system records that they do.
- Grain drift on a join. A definition at account grain used in a model joined at user grain double-counts, and the total still looks plausible.
Trade-offs
| Choose | Gains | Pays |
|---|---|---|
| Executable definitions for the small metric set | one number per question - a semantic layer that can enforce it - definition changes become reviewable | an afternoon per term with the people who argue - versioning and restatement become obligations |
| Prose definitions for everything | cheap - covers the whole estate quickly | coverage metrics that rise while disagreement stays constant |
When not to use it
Terms that describe the business rather than measure it should stay narrative. "Merchant of record", "strategic account", "regulated market" have no countable event, and forcing a SQL expression onto them manufactures a precision that somebody later quotes as authoritative. The test is whether the term ever appears as a number: if it does, it needs the five clauses; if it appears in a sentence, it needs a good paragraph.
Nor should this run across a harvested backlog of 1,400 candidate terms: choose the terms behind the metrics leadership acts on, usually fewer than 30.
Interview question
Q: You are handed a glossary of 400 terms with named owners and a monthly review, and the business still argues about three numbers every quarter. How would you tell whether the glossary is the problem, and what would you change in the first month?
What a strong answer covers: sampling terms and trying to write the query from the text alone · the five clauses and which is missing most often · binding the survivors to one implementation rather than rewriting all 400 · the restatement question a newly precise definition raises · and why coverage is the wrong metric to report.
Quick check
Quiz: Two teams implement one glossary definition and differ by 9%. What is missing? - An executable form: no countable event and no grain are named, so both readings comply.
Flashcard: Which five clauses make a definition implementable? - Event, grain, window and boundary, exclusions and tie-breaks, late-data rule.