Modeling Guide

Semantic modeling is how Tukun.ai turns repeated business language into shared analytical meaning.

Use modeling to remove recurring ambiguity, not to create a giant taxonomy before anyone has asked real questions.

The purpose of modeling

Modeling helps your team:

• define what a metric actually means
• standardize common exclusions and filters
• reduce repeated clarification in the Workbench
• make cards and dashboards more stable over time

Start with the questions that already recur

The best first models are not theoretical. They come from repeated questions that already matter.

Typical early candidates:

• revenue
• weekly active accounts
• conversion rate
• retention
• churn
• gross margin

What to document for each metric

For each important metric, capture:

• what it means in business terms
• which source tables it depends on
• what grain it should support
• which exclusions always apply
• who owns the definition

If you cannot explain a metric in one short paragraph, it is probably not ready to become shared truth.

Dimensions should reduce confusion, not add it

Use dimensions that the business already understands clearly, such as:

• plan
• region
• channel
• customer segment
• signup month

Avoid introducing multiple near-duplicate dimensions with overlapping meanings unless the distinction is critical and documented.

Model incrementally

A practical sequence is:

1. define one metric that people already ask for every week
2. add the one or two dimensions most often used with it
3. encode the exclusions that users keep repeating manually
4. validate the results in the Workbench
5. promote the stable outputs into cards and dashboards

Good modeling discipline

• use canonical names
• keep definitions short and explicit
• assign an owner
• update the model when business logic changes
• revisit dashboards that depend on changed definitions

What modeling should not become

Do not use semantic modeling as:

• a dumping ground for every possible field
• a substitute for source cleanup
• a way to hide unresolved business disagreement

Modeling improves consistency only when the team is actually willing to adopt the shared definition.