Build the ontology

A build is how Tattva learns from your sources and your documents. On this page you start a build, follow its phases, read the warnings it leaves, and learn what it changes. You also learn the two banners that tell you a build is due. Run a build after you connect data, after you edit column meanings, and after you upload a metric document.

Where the ontology lives

Open Ontology in the sidebar. Its tabs are grouped in three modes.

The header on every Ontology tab has Refresh, Import and Regenerate.

Start a build

There are three ways to start the same build. Where you see its progress depends on how you started it.

• Regenerate in the Ontology header, on any Ontology tab. A panel opens at the bottom right of the screen and lists each phase as it runs, with its duration and any ⚠ warnings. The Build Ontology card on Make › Data does not show this build.
• Build Ontology → on the Build Ontology card at the top of Make › Data. The card itself shows the phases and each one's summary. After a build finishes, the button reads Rebuild. The card does not list warnings.
• Rebuild → or Rebuild now on one of the banners described below. These start the build through the card, so the card shows it.

Only one build runs at a time. If you click Regenerate while a build is running, the panel follows the running build instead of starting another. Use Regenerate after uploading a metric document: it is the only view with the warnings.

The phases

When you start a build from the card or a banner, the Build Ontology card groups the phases into numbered steps. Phases in the same step run in parallel. Each phase shows a dot (grey waiting, blue running, green done, red failed) and a one-line summary when it finishes. The card also shows how many phases are done, the time taken and the number of changes made. A build started with Regenerate leaves the card unchanged.

Rules Extraction runs after Metric Generation on purpose: the metrics your document mentions exist by then. Its summary reads "Read N documents → M rule proposals", "No new documents to read (N already extracted)" or "No narrative documents to read". When the build had to read a document twice, the first form says so: "Read N documents (N retried) → M rule proposals".

Choose what happens to generated metrics. Settings › Project › Ontology build › Metric generation sets how a build lands the metrics it derives from your columns (Semantic Layer and Metric Generation): Automatic adds them, sending low-confidence ones to Review; Send to Review puts every one in Review, so none goes live until someone accepts it; Off derives none. The Workspace Library has its own setting. In every mode, a generated metric built only from aggregates one of your stored definitions already computes, such as SUM(product_value_exc_tax_exc_shipping_charges) next to a net revenue definition, is not created. The build log lists each one it skipped and why.

Choose what the build proposes on its own. Two more settings in the same panel:

• Concept proposals decides whether the build asks an AI for glossary concepts in your sources. Send to Review (the default) puts each proposed concept in Review. Off proposes none; currency, date-format and similar conventions are still detected. A source is asked about once per version: a rebuild proposes concepts only for a new source or a source with a new version. A concept is kept only when its name or one of its aliases appears in the source's own summary, key findings or column names. A concept is not proposed under the name of an existing concept or metric.
• Link proposals decides what happens to the relationships the build infers between tables. Automatic (the default) adds the verified ones and sends the rest to Review. Send to Review puts every one in Review. Off infers no new relationships; existing ones stay.
• Disambiguation proposals decides what the build does with column names that appear in two or more sources (for example net_revenue in two versions of one table). Off (the default) proposes none; disambiguations that already exist stay, and switching to Off withdraws the pending cards. Send to Review puts each shared column name in Review as a disambiguation. Automatic adds the ones it is confident about and sends the rest to Review. Sources with proposals switched off are never counted.

How a relationship is verified. The build counts how many distinct values the two join columns share. It uses the stored values of both columns when they are complete, and otherwise runs one query per pair on the same engine. It also checks whether each column holds every value once (its distinct values are at least 95% of its non-empty rows), from the column's stored profile, or from the row counts that same query returns when the profile lacks them. The rules are the same whichever way the pair was found (a foreign-key hint, matching column names, or an AI suggestion). Then:

• No shared values: the relationship is not created. The build log counts these as "N rejected: no shared values".
• Both columns repeat their values (many-to-many): joining would multiply rows, so the relationship is not proposed. The build log lists each pair and counts them as "N skipped: would multiply rows".
• Fewer than half of the smaller column's values meet the other column, or that column holds one value only: the relationship goes to Review. The card shows the rate, for example "measured: 42% of values meet (120 of 286)".
• Half or more, and one column holds each value once (many-to-one or one-to-one): the relationship is verified and added.
• Not measured, because the two tables are in different engines, the query failed, or the build could not count whether either column holds each value once: not verified, so it goes to Review. A card whose uniqueness was not counted says "uniqueness not measured" and is labelled many-to-many.

Each build measures again; a measurement is reused for 7 days unless either table has a new version. A relationship that no longer measures as verified loses verified on the next build, including an existing relationship that now measures as many-to-many; the build log lists those as "un-verified live link pair … would multiply rows". A relationship you marked verified, or whose keys you edited, is not changed by a build. Relationships with no shared values are not given to the agent, and unverified or partial ones are given with their rate.

A link card is about two tables, in either direction. When you reject one, the build does not propose the same two tables again, in either direction, and does not add a relationship between them on its own. Accepting a card for those tables, or adding the relationship yourself, lifts this.

To switch proposals off for one source only, open it on Sources and click Turn proposals off. See Sources.

Read the warnings

A phase can finish and still have lost part of its input. When that happens, the Regenerate panel lists a ⚠ line under that phase's row. The panel names phases by their internal key, so the document step is rules_extraction.

For a metric document, each line reads document: name not proposed — reason, or document: could not be read — reason. The name is the metric's slug, or (document) for the text outside the metric sections. The reasons you will see most:

The banners that ask for a build

The top of Make › Data shows a banner when the ontology is behind your changes.

• "Sources changed since last build (…): N added, N re-uploaded, N deleted." Tables were added, re-uploaded or removed since the last build. It lists the sources and, for a re-uploaded table, the columns added, removed, renamed or retyped. Click Rebuild →. Before the first build it reads "N sources ready, ontology not yet built." with Build now →.
• "N curation edits saved but not yet in effect". You edited column meanings since the last build. Reasoning still uses the last build. Click Rebuild now.

What a build changes

Your curation is kept. Column meanings, roles and aggregations you wrote are read by the build and never overwritten.

What the build is unsure of goes to Review. Concepts, entities and metrics the build proposes with less than 85% confidence are queued in Maintain › Review under a provenance chip such as "Build review — 2026-09-26 10:30"; the rest are applied. Relationships whose values were not verified are queued too. Everything read from your documents goes to Review whatever its confidence, and nothing from a document is applied until you accept it.

Each document is read once. A later build skips any document that already produced proposals. A document whose source you deleted is not read at all: deleting a document source deletes its text and retires its cards still waiting in Review. To change an accepted definition, upload a new document. See Replace a definition.

A small document is read in one go; a large one one metric at a time. Tattva estimates the size of the answer from your queries: each section's query length plus about 1,000 for each metric. Up to 12,800, the whole document is read at once, so a metric that uses another metric of the document can refer to it by name. Above that, each section that holds a query is read on its own, with the whole document as context, and the text outside those sections is read once more; up to four of these reads run at the same time. If a whole read is cut off at the output limit anyway, the build reads the document section by section instead, without a warning. A part whose read failed (a section with a complete query and no definition, or a reply the extractor could not use) is read once more on its own; the other parts keep their cards. A part still missing after that counts as read: later builds do not try it again by themselves, and its ⚠ line says what was missed.

You can ask for a document to be read again. On Sources, open the document's source, click Read again on next build and confirm, then click Regenerate. The build reads the latest upload of that document again and proposes new cards. The cards from earlier reads stay in the review history: accepted cards stay accepted, and cards still waiting in Review stay next to the new ones, so reject the ones you no longer want. Asking needs permission to upload sources in the project; for a Workspace Library source, permission to edit the Workspace Library.

Pending proposals stay as they are. A build does not re-check a proposal already in the queue. Its checks were run when the document was read, and Accept uses that result. Proposals that point at a source you deleted are retired.

Accepted definitions are never changed. A build does not rewrite a stored definition you accepted, even when Metric Generation proposes a formula metric with the same name. Only a reviewed replacement from a new document changes it.

Accepted definitions are re-checked. After the phases, each build dry-runs every stored definition this project accepted against BigQuery. A definition that no longer compiles, usually because a column was renamed or dropped upstream, raises a high-severity finding in Maintain › Conflicts (under Data Quality): "Stored definition of metric no longer runs". Until you fix it, questions about that metric cannot be computed from its definition. The finding clears itself at the first build where the definition compiles again. The same pass also flags families that lost a variant or their default, and a stored definition that returns the same value as a formula metric on the same table. See Maintain the ontology.

Next

• Write a metric document
• Review what Tattva proposes