Metric rules: the concepts

Every kind of metric logic in Tattva in one place, with where it comes from, where you see it, who changes it, how it is checked, how answers use it and what a rebuild does to it.

Tattva's picture of your metrics is built from a dozen kinds of pieces: column profiles and meanings, generated formula metrics, the stored definitions you write, their inputs, settlements, filters, families, value groupings, relationships and conventions. This page lists them all in one place. For each one it says where it comes from, where you see it, who can change it, how it is checked, how answers use it, and what a rebuild does to it. It also covers what each kind of source can contain, which rule wins when two pieces disagree, and the states a stored definition goes through. The other pages in this section go deeper on each piece. To see all of them work together on one metric, read One metric, end to end.

The pieces

"Anyone with project access" means any member who can open the project. "Ontology Admin+" means the Ontology Admin, admin or owner role.

Piece	What it is	Comes from	Where you see it	Who can change it	How it is checked	How answers use it	On rebuild
Column profile	Row, null and distinct counts; the 20 most common values of text columns with at most 1,000 distinct values	Build (Table Profiling)	Ontology › Manage › Knowledge Graph › source node › Schema: "≈N distinct", "common: …"	Nobody edits it; mark a column `pii` to stop common values	Personal-data names, `pii`/`restricted` and policy-tagged columns get no common values	Common values become clickable choices when an input is missing	Files: every build. BigQuery: when older than 7 days or the source has a new version
Column meaning and role	Meaning, role, unit, sensitivity, aggregation hint, temporal role	Build (About-Fields), then you	Sources › source › Schema; Make › Data › Data › Fields; Knowledge Graph drawer › Schema › Override	Anyone with project access, on a source the project owns; a shared source takes a project override	The Effect: line; `no aggregation` stops metrics summing the column	Guides metric generation and the agent's own SQL; an `excluded` column is refused in the agent's SQL (see Sensitive data)	Your edits are kept. They take effect only after a build ("curation edits saved but not yet in effect")
Formula metric	An aggregation over columns, such as `SUM(item_revenue_inc_tax)`	Build (Metric Generation), or + Add metric	Make › Data › Domain (chip Formula); Make › Data › Data › Metrics	Edit: anyone with project access. Delete: Ontology Admin+	Self-Test raises Formulas conflicts (no formula, division without `NULLIF`, unknown columns)	Compiled by code with its filters and verified many-to-one joins only	Proposed again each build. Below 85% confidence it goes to Review. A formula you edited is not overwritten; one you deleted is not recreated
Stored definition	Your SQL, kept whole, with inputs as `@name`	Your document, via Rules Extraction, accepted in Review	Domain row (chip Stored query or Drafted from prose); drawer › Definition	Changed only by accepting a replacement from a new document. Anyone with project access can accept a document card	V1–V12 at review; a dry run at every build	Run as written by code before the model writes; the model does not rewrite it	Never changed by a build. If it stops compiling, the build raises "Stored definition of `x` no longer runs"
Input (parameter)	A value in the query that changes with the question	Your document: the literal it replaced	Parameters table on the review card and the Definition tab; "Inputs:" on the row	Only through a replacement document	V2 (declared and used), V6 (same result), V11 (lists on grouped columns), V12 (derived dates)	Bound by code for each question (see below)	Unchanged
Settlement	Days after which a metric's figures stop changing	Your document ("RTO takes 21 days to show up")	"Settles after N days — …" on the row; chip settles after N days	Set: through Review. Retire: Ontology Admin+ with Retire	V2 needs it for inputs dated from the unsettled days; V12 checks those dates	Marks a figure Provisional from the first unsettled day	Unchanged
Filter	A row exclusion bound to a formula metric	Your document	A `reusable filter` card; a filter · when … box on the row	Set: through Review. Retire rule: Ontology Admin+	V8 checks that a metric built from this one applies it	Applied when code compiles a formula metric. Never applied to a stored definition	Unchanged
Family and variant policy	One word ("revenue") covering several metrics, and what to do when nobody says which	Your document	Family group row on Make › Data › Domain; Variant of chips; `metric family` card	Policy: Ontology Admin+ with [change]. Membership: through Review	F1–F5 at review; each build flags families that lost a variant or their default	Show all variants, ask which one, or use a default and mention the others with their figures	Unchanged
Value grouping	Raw spellings grouped under one label	You	Knowledge Graph › source node › Schema › Values; "N mapped"	Ontology Admin+	V11 warns when a definition compares a grouped column with `=`	A label in the question is widened to every raw value in it, through a list input	Unchanged. Builds may raise a Data Quality conflict for values that do not match
Relationship (join)	How two tables join, with its keys and direction	Build (Relationship Inference), or + New relationship	Ontology › Manage › Knowledge Graph: edges and the edge drawer; Open link → on a conflict	Join keys and + New relationship: anyone with project access, on this project's edges. Delete and Mark verified: Ontology Admin+. Workspace edges: Ontology Admin+	Verified by the build only when at least half of the smaller column's values meet the other column and one of the two columns holds each value once; no shared values and it is not created; both columns repeating their values (many-to-many) and it is not proposed, "would multiply rows". Modelling findings flag verified joins that cannot run or share no values; the drawer shows each key pair's measured value overlap	Formula metrics join only along verified many-to-one links; stored definitions use their own SQL joins. Joins with no shared values are not given to the agent	Measured again each build: unverified ones go to Review, and a link that stops measuring as verified, or now measures as many-to-many, loses verified. With Link proposals set to Send to Review, all go to Review; with Off, none are inferred. A deleted edge, or a rejected link card, is not re-inferred in either direction; join keys set by a person, and Mark verified, are kept
Convention	A reading rule such as currency, date format or time grain	Build (Domain Enrichment)	Make › Data › Data › Detected Conventions	Edit: anyone with project access. Delete: Ontology Admin+	Shown with a confidence	Given to the agent as context for every question	A value you edited is not overwritten; one you deleted is not re-added
Scope (convention category `domain_scope`)	What the data covers, for example "D2C website orders only"	Seeded, or you add it as a convention with category Scope	Make › Data › Data › Detected Conventions	As other conventions	—	Shown as a Scope line under every answer; a question clearly outside it gets a short refusal instead of an answer	As other conventions
Not answered yet (convention category `not_ready`)	A topic the team does not answer yet, with the reason users see (name = the topic, value = the reason)	You add it as a convention with category Not answered yet	Make › Data › Data › Detected Conventions; What you can ask on Reasoning; the configuration document	As other conventions	—	A question about the topic gets the reason and example questions instead of an answer, and is listed under Feedback › Asked but not answered	As other conventions
Available from	The first date a metric's figures are valid from	You, on the metric's Definition tab (suggested from the earliest date in the data)	Definition tab; the metric's page in the configuration document	Ontology Admin+	—	The part of a requested period before the date is not answered for that metric ("not available before …"); the rest is	Unchanged

Where each input's value comes from

Kind of input	In your query it was	Shown as ("Value comes from")	Filled in by
Period start	The first date of the reporting period	from the question's period (start)	The question's period
Period end	The date after the period's last day	from the question's period (end)	The question's period
Derived date	A date a fixed number of days from the period, from the first unsettled day, or from today	the day after the period + 90 days; filled in by code: tail start − 30 days	Code, never asked
Dimension	A value you said changes with the question, such as a warehouse list	from the question	A value or grouped label named in the question, otherwise asked
User	A value the person asking gives, such as the number of days in a repeat window	asked from the user	A value the question states ("66 day"); otherwise the definition's default, if it has one; otherwise the user, through Needs clarification
Default	A value used when nothing else supplies one	"(default …)" after the source	The definition

Details and the clarification card: Inputs and groupings.

What a source can contain

Source	Types	What Tattva does with it
BigQuery table	Any table the workspace's BigQuery identity can read	Queried where it lives, never copied. Profiled, described, and used by formula metrics, stored definitions and the agent's own SQL. Stored definitions run only on BigQuery.
Uploaded file	`.csv`, `.tsv`, `.xlsx`, `.xls`	Parsed into a table, profiled and described. Used by formula metrics and the agent's own SQL, never by a stored definition, and never joined with a BigQuery table.
Metric document	`.md`, `.txt`	Kept word for word. Read by the next build's Rules Extraction, once.

What a metric document's sections become:

A section that…	Becomes	Card type in Review
Defines a metric with a query, SQL pieces or prose	A stored definition with inputs	`metric definition`
Says one word covers several metrics	A family with a policy	`metric family`
Says a metric settles after N days	Folded into that metric's definition when the same document defines it; otherwise its own card	`settlement window`
Excludes rows ("never count cancelled items"), including an exclusion sentence inside a metric's own section ("It leaves out items cancelled on the panel")	A filter, for formula metrics. From inside a metric section it often has no Applies to. Reject it when the exclusion is already in that metric's stored query.	`reusable filter`
Describes an adjustment ("revenue net of returns" as a correction to another metric)	Nothing. Build warning: "adjustments are no longer extracted — define the adjusted number as its own metric"	—
Names business things (products, warehouses, channels) anywhere in the text	Entities, found by a separate pass after the build	`entity`, provenance `document_ner`
Anything else: background, team notes, tables of figures	Ignored for metrics	—

Never accept two cards with the same slug and different content; the card warns "approving more than one silently redefines the earlier ones".

HTML and PDF are not read as metric documents

An .html upload is kept as text you can search, but the build does not read it for metrics. A PDF upload is refused. Save metric documents as .md or .txt.

Which rule wins

When…	What happens
A document defines a metric with the same name as a formula metric	V10 blocks Accept: "already exists with a different definition — retire or rename it first". Delete the formula metric on Make › Data › Data, then upload the document again, or rename yours. See Write a metric document.
A document defines a metric this project already accepted as a stored definition	The new card replaces it (V10 Replaces the accepted definition). Nothing changes until you accept it.
A definition is pending and an older one is accepted	Answers use the accepted one. A pending card is never used.
The project and the Workspace Library both have the metric	The project's own metric wins. An Override from Make › Workspace Library goes to Review first; until an Ontology Admin+ accepts it, answers keep using the workspace version. Maintain › Conflicts › Same-slug across origins shows which one wins.
A question names a grouped label	The label is widened to every raw value grouped under it. A raw value named directly binds only itself.
A question names a variant of a family	That variant alone is computed. The family's policy applies only when the question uses the family word and names no variant.
A filter exists on a metric that has a stored definition	The stored definition runs as written; the filter is not applied.
A settlement and a reporting period overlap	Code marks the figure Provisional from the first unsettled day.

The life of a definition

The states of a stored definition: written, not proposed, pending, deferred, rejected, stored, broken, replacement pending and deleted, with the transitions between them

State	What it means	How it gets there	What moves it on
Written	A section in a document you uploaded	Upload a `.md` or `.txt` on Sources › Upload	The next build's Rules Extraction reads it
Not proposed	The extractor could not use the section	A ⚠ line under `rules_extraction` on the Regenerate panel: "… not proposed — reason"	Nothing. Fix the section and upload it as a new document.
Pending	A card in Maintain › Review, with V1–V12 already run	Rules Extraction proposed it	Accept, Defer or Reject. If a blocking check failed, it is blocked: Accept stays disabled, because Accept uses the checks from when the document was read
Deferred	Parked	Defer	Accept or Reject from the Deferred list
Rejected	Discarded	Reject	End
Stored	In use by answers, trackers and Try it; "✓ validated" on its row	Accept	A build's dry run, a replacement, or Delete
Broken	Stored, but the warehouse no longer accepts the query. Answers cannot compute the metric from it	A build's dry run fails: HIGH finding "Stored definition of `x` no longer runs" in Maintain › Conflicts	Fix the table or upload a corrected document. The finding clears at the first build where it compiles again
Replacement pending	A new document defines the same metric	V10 Replaces the accepted definition, with SQL changed — compare	Accept updates the stored definition in place: family membership and links stay
Deleted	Removed from the ontology	Delete on Make › Data › Data › Metrics	A later build does not recreate a formula metric with that name or formula. Accepting a new document's definition of it brings it back

A build never changes a stored definition. Only you do, by accepting a replacement or by deleting it.