Families

People say "revenue" and mean gross revenue, or net revenue, depending on who is asking. A family tells Tattva that one word covers several metrics, and what to do when a question uses the word without naming one. On this page you learn when to make a family, how each of the three policies changes an answer, how to read and change a family in Make, and how to declare one in a document.

What a family is

A family is a concept plus a variant policy:

• the concept is the shared word, with the other words people use for it ("revenue", "sales");
• the variants are the metrics it covers (gross_revenue, net_revenue), each linked to the family;
• the policy says what an answer does when someone uses the word and names no variant.

Naming a variant skips the policy. "What was net revenue last month?" gets net revenue only.

When to make one

Make a family when:

• one word in everyday use covers two or more metrics you have defined, and
• picking the wrong one gives a materially different number.

Good candidates: revenue (gross and net), retention (repeat rate, cohort retention, cross-sell retention), RTO rate (overall and per SKU).

Do not make one for metrics that merely share a topic, such as "orders" and "AOV". Each variant must be a metric that exists, a metric can be in only one family, and a family needs at least two variants.

The three policies

Show all variants

The answer gives one labelled figure per variant.

Question: What was revenue last week?

Answer: Last week, gross revenue was 412,300 and net revenue was 367,900. Net revenue is provisional, because RTO for the most recent 21 days has not settled.

Code checks that every variant has a figure. If one is missing, the answer carries a warning such as: "Revenue" covers more than one metric, and this answer gives no figure for Net revenue (net_revenue). Ask for it by name to get the missing value.

Use it when both numbers are useful side by side and nobody should see one without the other.

Ask which one

The answer stops and asks before computing anything.

Question: What was retention for the May cohort?

Needs clarification: Which retention do you mean? The variants are offered as choices, and the user can also type into "Or type your own answer…".

After the user picks one, the answer is computed for that variant only, and the Trail says it used the variant the user chose.

Use it when the variants answer different questions and a wrong guess would mislead.

Use one by default and mention the others with their figures

The answer leads with the default variant's figure. When the question asks for the family's value ("What is the revenue for August 2026?"), code also computes each other variant's total for the same period, and the answer gives those figures in one sentence after the default's.

Question: What is the revenue for August 2026?

Answer: Net revenue for August 2026 was ₹16,10,04,561.77. Gross revenue, which includes GST and the customer's share of shipping, was ₹18,94,12,345.67 for the same period.

Some variants get a name but no figure:

• A variant that gives one value per key, such as a per-SKU RTO rate, has no single total. The answer names it only:

  Question: What is our RTO rate?

  Answer: The overall RTO rate for the 30 settled days to 4 September was 8.2%. A per-SKU RTO rate is also defined; ask for it by SKU.

• A variant code could not run for the question, for example because it has no input for a filter the question applies.

• A question that uses the family word for something else, such as "RTO rate for the top 5 products by revenue". Here revenue only ranks the products, so the other variants are named but not computed.

If the answer names a computed variant without its figure, code adds the sentence itself at the end of the answer: "For the same period, computed in code: Gross Revenue (gross_revenue) 18,94,12,345.67 (18.94 crore)."

Use it when one variant is what people mean almost every time.

If the default variant no longer exists, answers fall back to showing all variants, and the family row in Make says "use its default variant (missing — pick another)".

See what happened in the Trail

Open an answer's Trail. The Metric family block names the family and what the policy did: "showed every variant", "asked which variant", "used the variant you chose" or "used the default variant". It also lists the variants, any note (for a default: which variant was reported and what else is defined), the other variants computed for the answer ("Also computed, for one sentence beside the default"), and how the metrics in the question changed.

The family row in Make

Open Ontology › Make › Data, sub-tab Domain. Families are listed first in the Domain Glossary, each as a shaded group row with its variants nested beneath.

The group row shows:

• the family's name and slug;
• Said as "revenue", "sales": the words that trigger it;
• When asked for "Revenue": followed by the current policy: "show all variants", "ask which one", or "use variant and mention the others with their figures";
• a family type chip and the number of variants.

Each variant row beneath it has a Variant of Revenue chip under its name.

To change the policy:

Declare a family in a document

Write a section for the word. Say which metrics it covers and what to do when someone uses it.

## Revenue

There are two revenues, and people mean different ones: gross revenue
and net revenue. People say "revenue" or "sales". When someone asks for
revenue without saying which, show gross and net revenue.

• Say the policy in words. "Show gross and net revenue" gives show all variants. "Ask which one is meant" gives ask. "They mean the overall rate; mention that a per-SKU rate exists" gives a default.
• If you say nothing, the policy is ask, with low confidence, so the card is flagged for you. Tattva never guesses show all.
• Define every variant, in the same document or before. A variant that does not exist blocks the family (F1).
• List the words people use as aliases. Never use a variant's own name: "net revenue" means net revenue, not the family. Such an alias is dropped (F5).

The full guide to writing documents: Write a metric document.

Family review cards

A family from a document arrives in Maintain › Review as a metric family card.

It shows Said as, When asked without naming one: with the proposed policy, each variant marked accepted, pending review or missing, and the F1–F5 checklist.

What each family check means and how to fix it: Family checks F1–F5.

Next

• Inputs and groupings
• How answers work