Metrics & Governance

Catalog: certification & glossary

The governance tools that answer “can I trust this, who do I ask, and who is allowed to see it?” — asset certification (which of the many dashboards/models/metrics is the blessed one), owners and domains (who looks after each dashboard, model, data source and metric), the business glossary (what your organization’s terms actually mean), lineage (what feeds this, and what uses it), data notices (what the people who answer for an asset want everyone downstream to know), and field sensitivity labels (what gets masked, for whom).

The Catalog’s Glossary tab: each term with its definition and synonyms, alongside the Assets and Lineage tabs.

The Catalog page has three tabs: Glossary, Assets and Lineage. The tab you are on and what you chose in it (a search, filters, a page, the asset whose lineage you traced and how you look at it) are part of the page’s address, so Back, a refresh and a shared link keep them.

Browse the catalog

Opening the Catalog needs the role’s Catalog view permission, which every built-in role has. Everyone who can open it reads the whole glossary; Assets and Lineage name only what your role may open, and count the rest. Changing anything is covered below.

Choose Catalog in the sidebar. Glossary lists the terms your organization has defined. The AI assistant answers with these definitions, and they show up as tooltips on matching fields.
Type in Search glossary to find a term by its name, definition or synonyms.
The Assets tab lists every governed asset with its type, owner and domain. Filter by type, domain or owner, or show only the assets with no owner.
The Lineage tab draws how sources, models, metrics, dashboards and reports connect. Select a node to see what feeds it and what would break if it changed.

About this data

About this data is a dashboard’s, data model’s, data source’s or metric’s trust card: the answers to what anyone asks before quoting a number, in one place. The same card opens from wherever you meet the asset:

In the Catalog: About beside an asset’s name in Assets opens it in a side panel, and so does About this data beside the asset you traced in Lineage.
On a dashboard: the trust row beside its title says what applies, Certified · Data 2 hours ago · 1 check failing, and opens the card under it. It is the Android app’s trust row, on the web.
On the Metrics page: a metric’s About this data opens its card, and a metric’s own panel shows the card below Who stands behind it.

The card answers four questions:

Can I trust it? Whether it is certified, by whom and when, with a metric’s note (For board reporting); how fresh its data is, as fresh as the stalest source it reads (Up to date: data loaded 3 hours ago, 1 source of 2 missed a refresh, Read live from its source); its quality checks by their latest result (2 of 5 checks failing, 1 of them critical), counted and never named; and when it last changed.
Who do I ask? Its owner and its domain (Ownership & domains).
What does it mean? Its description, and the glossary terms linked to it, to its fields or to what a dashboard’s cards read, each with its steward when it has one (Ask Asha Rao about this term).
What breaks if it changes? What it is built on and what uses it, every step of the way, by type (Used by 3 dashboards and 1 presentation), and how often a dashboard was opened in the last 30 days and by how many people. See its lineage opens the asset in the Lineage tab.

Above the four answers, the card shows the asset’s data notices and the ones it inherits.

Everything on the card is read with your access. An asset you can’t open has no card for you, and what feeds it or uses it that you can’t open is counted, never named (and 2 more you can’t open). Quality checks read whole tables, so they aren’t shown to someone a row-level security policy restricts. Reading the card uses no AI.

Explain this asset

On a dashboard’s, a metric’s or a data model’s card, Explain this asset writes one paragraph on where its data comes from. It is the lineage chain’s Explain with AI, by the same rules: a separate click that uses AI credits; the AI is sent the chain alone; the paragraph is checked before you see it, marked AI-written, and never stored. It is offered only where it would run for you, and a data source has none: its data starts there.

The card through the API

GET /api/catalog/assets/{type}/{id}/summary, with type one of dashboard, model, source or metric, returns the card: owner and domain; certification (certified, by, at, a metric’s note and version); description; updated_at; freshness (state, loaded_at, how many sources, how many read live, how many stale); quality, the checks counted by their latest result; a dashboard’s views in the last 30 days; glossary (terms, total); lineage (upstream and downstream, each named with byType, and hidden, counted); explain, whether Explain this asset would run for the caller and if not why; and withheld, why lineage or quality is null. An asset the caller can’t open is 404. An API key needs dashboard:read, and its explain is never allowed: AI features are in the DataSquares app only.

Data notices

A data notice is a word from the people who answer for a data source, data model, metric or dashboard to everyone who reads what is built on it. There are five kinds:

Deprecated: it is being retired, and people should move to something else.
Under maintenance: it is being worked on, and its numbers may change for a while.
Stale: its data is out of date.
Sensitive: it holds sensitive data, so take care sharing it.
Custom note: anything else, in your own words.

Each notice has its words (a short paragraph of up to 500 characters; a custom note must have them), says who set it and when, and can have a last day, after which it stops showing on its own. An asset has at most one notice of each kind. A deleted dashboard’s or metric’s notices show nowhere, and come back with it when it is restored from Recovery; a deleted data source’s or data model’s are deleted with it.

Where notices show

A notice shows on everything built on its asset, every step of the way along its lineage: a notice on a data source shows on the dashboards whose models read it, and on the reports, presentations and stories that read those models or their metrics. Each page shows a short line per notice, the most serious first (Revenue model: under maintenance until Nov 9. Totals may move until the rebuild is done.): two at first, and Show N more notices opens the rest.

on a dashboard, under its title bar (a notice on the dashboard itself reads This dashboard: deprecated);
on a report, above its pages;
on a presentation, in its editor and its reader view, and in present mode in the presenting bar (the first notice, with the rest counted);
on a story, above its title, and in full screen under its title and summary.

An asset’s About this data card lists its own notices and, under From what it is built on, the ones it inherits.

Notices are read with your access. Anyone who can open a page reads its notices’ words, but an asset you can’t open is never named: the line says A data source this uses: deprecated, with no link and no name of who set or edited it. Write the words knowing that everyone downstream reads them. A page’s notices are the ones on what it shows you: a story’s, those on the sections you can see; a presentation’s, those on its published version, and for the people who make it, those on its working copy and its speaker notes too.

Set, edit or clear a notice

On the asset’s About this data card (in the Catalog’s side panel, a dashboard’s popover or a metric’s panel):

Choose Add a notice, pick its kind, write what people should know, and if it should end, the last day it shows.
Choose Set notice. Every page built on the asset shows it from then on.
Edit changes its words or its last day. Clear takes it down everywhere, after asking.

The asset’s owner, anyone whose role can edit that kind of asset (for a dashboard, an editor grant on it too) and workspace admins can set, edit and clear its notices. Everyone else reads them. The audit log records who set, edited or cleared each notice, and what it said.

Notices through the API

GET /api/catalog/assets/{type}/{id}/notices, with type one of dashboard, model, source or metric, lists the asset’s own notices and those it inherits (inherited), the first 50 with total, and can_manage and setting_needs_upgrade. An API key needs dashboard:read, and for a data source source:read too, as the Catalog’s asset list does.
POST to the same path with kind, message and expiresAt sets one; PATCH .../notices/{noticeId} with message, expiresAt or both edits it (null clears one); DELETE .../notices/{noticeId} clears it. A second notice of a kind already on the asset is 409. An API key needs dashboard:write, and its owner’s role decides what it may change, as for the Catalog’s other writes: an admin’s key may set a notice on any asset it can open, and anyone’s key on an asset its owner owns.
GET /api/catalog/notices/for/{type}/{id}, with type one of dashboard, report, presentation or story, returns the notices that page shows: the first 50, with total. An API key needs the item’s own read scope (dashboard:read, reports:read, presentations:read or stories:read), and without dashboard:read it names no asset.

Each notice carries its kind, message, expires_at, set_at, set_by, edited_at, edited_by and asset. When the caller can’t open its asset, the asset’s id, name and href_hint, set_by and edited_by are null, and the notice’s id is a new one in each answer.

Certification

Workspace admins can certify four asset types: dashboards, data models, data sources, and metrics; a metric, also anyone whose role holds Certify metrics (Certification). Certification is a governance act, deliberately separate from authorship — the badge says “this one is endorsed”, not “I made this”.

What certification does:

A green ✓ Certified badge appears where the asset shows — dashboard lists, source cards, the Metrics hub (its tooltip says when it was certified). In the Catalog, the Assets tab marks every certified asset Certified, metrics included, and the lineage graph, its list and its chain mark a certified asset with a check.
Search ranks certified assets first, so the endorsed dashboard beats the seventeen experiments named “Revenue v2 final FINAL”.
The AI agent and the Android app surface certification too — certified-first ordering in the mobile metrics hub.

Certify or uncertify from the asset’s own surface (e.g. the Metrics hub row actions, which show Certify only to those who may certify a metric). The Catalog page has no certify control of its own. Certifying is the act itself: there is no request, review or approval step before it. The API supports dashboards, models, sources, and metrics.

Business glossary

Under Catalog → Glossary (Your team’s meaning for business words. The AI assistant answers with these, and they show as tips on matching fields.), each term is listed with its Definition, its Synonyms, what it is Linked to and its Steward, 20 to a page (50 or 100 if you choose), in name order. Search glossary finds a term by its name, a synonym or its definition, whatever the case.

Choose a term’s name to open its own view: its definition, synonyms, steward and links, who changed it last and when, and its History, newest first, said in words (Asha Rao changed the definition and added the synonym “ARR”). A changed definition shows its wording before and after on request. The latest 50 changes are listed.

If the glossary fails to load, the tab says so, with Try again: it never claims to be empty, and adding terms is paused until it loads, so nothing gets defined twice.

Add or change a term

With the role’s Catalog create permission, choose New term; with its edit permission, Edit beside a term (or Edit term in its view). Then Add term (or Save changes):

Field	Meaning
Term	the word or phrase (e.g. “Active customer”), up to 120 characters
Definition	your team’s real rule, up to 4,000 characters: the AI assistant answers with these words
Synonyms	other words people use for it, matched in questions and in field names: up to 12, of 120 characters each. A comma, a new line or Enter adds each one; a pasted list splits the same way
Steward	the person to ask about the term, one of the workspace’s members. A label only: it gives them no rights

A term is refused for these, and the dialog says why beside the field:

A name the workspace already has, on a new term or a rename: “Customers” is already defined in this workspace. Names compare whatever their case, their full-width forms and characters drawn as nothing, so customers is Customers.
A word that already stands for another term, as that term’s name or one of its synonyms: “revenue” already stands for “Net revenue” in this glossary. Only the words an edit adds are checked, so a clash kept from before never stops you editing a definition. A synonym that repeats another, or the term’s own name, is simply left out.
A blank name or definition: A term needs a name., A term needs a definition.
Text hidden in invisible characters (tag characters, or variation selectors where written text never has them; see What a note can hold): The definition has characters in it that can’t be seen, which the AI assistant would still read. Type it again without them. A term kept with such text from before is never given to the AI.
A steward outside the workspace: The steward must be a member of this workspace.
Someone else’s change in between: Someone changed this term after you opened it. Open it again to see their change, then make yours. Open it again loads the latest version; nothing is overwritten.

Closing the dialog with unsaved text asks first (Discard your changes?).

Terms publish at once: there is no draft or approval step. Each term remembers who changed it last, and each change of a term or its links (adding, editing, deleting, linking, unlinking) is recorded in the audit log with the values before and after, which is what the term’s History reads.

Suggest terms to define

Not sure which words need a definition? With the role’s Catalog create permission, Suggest terms to define lists the words and two-word phrases your names use most that no term defines yet, most used first: Customer, in 6 names, such as Customer ID, customer_name, Customers. Choose Define beside one and New term opens with the word filled in. The definition is yours to write: the AI never writes a definition.

It counts the names you can open: dashboards, metrics, and data models with their visible tables, fields and measures. It reads names only, never a value or a description.
A word a term already names is left out, by its name or a synonym, whatever its case, plural or separators (active_customers is Active customer). So are the words that mean nothing on their own (of, id, date, total, a currency code), words with a digit, and words that only sharpen another (net, active, rate), which count in a phrase such as Net revenue or Churn rate. A phrase must appear in at least two names.
It uses no AI and no AI credits. A plain count of your names finds the same words an AI would, so the list is counted, and comes back the same each time.

Link a term to what implements it

Terms can be linked to the assets that implement them — governed metrics, model fields, or models — so the definition and the implementation stay attached. Each link names its asset and opens it: a metric on the Metrics page, a model, or a field’s model (a field reads Sales · Revenue).

With the role’s Catalog edit permission, choose Link a metric beside a term, choose the metric in the list (Find a metric by name when there are more than eight), then Link. The arrow keys move the choice and link nothing until you choose Link. The × on a link (Unlink Revenue) removes it.
A link whose asset was deleted says so (Deleted metric, Deleted model or Deleted field), and an editor can Remove it.
A link to a field follows the field when it is renamed: search still finds the field from the term, and AI search and the AI assistant still read the term’s synonyms on it.
The web app links metrics. Through the API a term also links to a model or a model’s field (assetType model or model_field). A link must name a metric, model or field that is in the workspace, or it is refused: That metric isn’t in this workspace (it may have been deleted).

Delete a term

Delete needs the role’s Catalog delete permission, which the built-in Admin role has and the built-in Editor role doesn’t; the app shows it only to a role that has it. It asks first (Delete term: the AI assistant stops using the definition at once, and it no longer shows as a tip on matching fields). Deleting is a soft delete: its history is kept, and the AI stops receiving the term on the next request. On Team, deleting still works.

Where glossary terms surface

AI chat — a question gets the definitions of at most eight terms it names, by a term’s name or one of its synonyms, its simple plural or singular too (active customers names Active customer), the longest first; see AI limitations. So “how many active customers?” is answered using your definition of active, not a guess. Deleting a term takes effect immediately, and the AI keeps using the glossary on Team.
Field tooltips — a field whose name matches a term or a synonym shows the definition on hover, right in the field tree (up to 280 characters; a longer one ends in “…”).
Search — a search that matches a term or a synonym also searches for the term and its synonyms, and finds the metrics and fields linked to the term (Semantic search).

The glossary through the API

GET /api/glossary lists every term with its links, in name order. ?view=page answers a page instead, { items, total, offset, limit }, found by q in a name, a synonym or a definition (50 a page unless limit says otherwise, at most 200); ?view=lookup sends each term’s name, synonyms and a definition cut to 280 characters, without links. Every view sends an ETag, and answers 304 to an If-None-Match that still holds. GET /api/glossary/{id}/history reads a term’s changes, newest first, a deleted term’s too.

POST /api/glossary adds a term and PUT /api/glossary/{id} changes one (only the fields you send). Send the term’s updated_at as you read it, in expectedUpdatedAt or an If-Match header, and an edit made after someone else’s is refused. A refusal says why in details.reason: term_taken or changed with a 409; blank, hidden_text, synonym_taken (with the word and the term that has it), not_a_member, asset_not_found, malformed or not_a_field_link with a 400, whose details.field names the part at fault. An API key needs dashboard:read to read and dashboard:write to change.

GET /api/glossary/suggestions lists the words to define, { items, counted, method }: each item’s term, uses and up to three examples, 20 unless limit says otherwise (at most 50); method is count. It needs the Catalog create permission and Business.

Ownership & domains

The Assets tab (Who looks after each dashboard, model, source and metric.) lists the dashboards, models, data sources and metrics you can open, each with its Owner, its Domain, whether it is Certified and when it Last changed — so “who do I ask about this number?” has an answer that isn’t guesswork. Every name opens the asset.

Search assets finds an asset by its name, whatever the case (and, for a longer word, a close spelling of it). Type, Domain and Owner narrow the list; Owner › No owner is the gap list, the one you actually want when starting a governance push. The Name, Type, Owner and Last changed headers sort it.
The list comes 20 at a time (Showing 1–20 of 340; 50 or 100 if you choose), so nothing is cut short.
Above it are the workspace’s own counts, whatever you have filtered: how many assets there are, how many have no owner (Show them), and how many your role can’t open, counted and never named (12 more that your role can’t open aren’t listed). The Domain and Owner filters list the workspace’s 50 most used domains and owners with their counts, so choosing one doesn’t make the others disappear.
Each type is listed to whom its own pages open it: a dashboard by your role or because it was shared with you, a data source with the Data Sources view permission, a model with the Data Models one, a metric with the Metrics one.

Choose an owner or a domain

Choose (or Change) beside an owner and the Domain field show only to a role that may change them: one with the Catalog edit permission, or with the edit permission of the asset’s own type (Dashboards, Data Models, Data Sources or Metrics). Everyone else reads them as text.

An owner is chosen in a dialog: No owner, then the workspace’s active members from A to Z, each with their role; someone deactivated in the company isn’t offered. The arrow keys move the choice and save nothing; Save owner saves it. An owner must be an active member of the workspace: ownership by someone who can’t act on it is responsibility nobody holds. A current owner who can’t be chosen again stays shown, first, until someone else is chosen, with why in place of their role: No longer in this workspace, Deactivated or, on a model, Can’t edit models.
A model’s owner also reviews the AI’s notes about the model (its shared notes and the notes about its tables), so only someone who can edit data models can change it, and only to someone who can edit data models: the dialog lists only them, and says so: The owner of a model also reviews the AI’s notes about it. Only people who can edit models are listed. An owner whose role later can’t edit data models reviews nothing on the model until it can again.
The new owner is told in the app, in the bell and the phone app’s inbox: You now own Exec board, saying who chose them, with a link to it; a model’s new owner is also told that they review the AI’s notes about it. Someone who can’t open the asset yet is told only what kind of asset it is and to ask for access, never its name. Nobody is told when they choose themselves, when the owner stays who it was or is cleared, or about a domain.
A domain (up to 80 characters, with the workspace’s domains suggested) is saved with Enter or Save, never while you type or when you leave the field; Escape or Cancel puts it back. It is kept in the spelling the workspace already uses, so finance typed where Finance exists saves as Finance, and the message says so.
A new dashboard, model or data source is owned by whoever made it. An asset made before November 2026 keeps the owner it had, often none.

Each save says it saved, or why not. A change of an owner or a domain is recorded in the audit log with the values before and after, and leaves the asset’s Last changed date as it was. The Metrics page sets a metric’s owner and domain by the same rules, and each page shows the other’s change at once.

If the list fails to load, the tab says so, with Try again: never that it is empty, nor that everything has an owner. If the workspace’s member list fails, the owner dialog says so and nothing can be saved until it loads.

Describe with AI

The Description column says whether each dashboard and metric has a description (Described, No description), and how many of a model’s tables and fields have none. Description › Missing a description lists only what is left to describe. For something that has none, Describe with AI drafts a description for you to approve. It uses AI credits.

One click drafts it. The draft opens in a box you can edit; Approve saves it (as you edited it) as the asset’s description, and Reject throws it away. Nothing is saved until you approve it, and Decide later keeps the draft waiting for review. A draft already waiting opens at once, with no new AI work.
It is drafted from what the asset is, never its data: its name, a dashboard’s card titles, a metric’s formula, grain, time field and unit, and the models, fields, measures, metrics and filters it reads, with the descriptions they already have. A filter’s values and the quoted text in a formula are left out, and a labelled field is named but never described.
A draft is checked before you see it. One with a number the asset doesn’t carry, one that is too long, or one that looks like personal details, a secret or an instruction is left out, and you’re told why. The AI work was done, so it still uses AI credits.
A description someone wrote is never replaced. An asset that has one isn’t drafted, and a draft approved after someone else wrote a description is not saved. A dashboard with no cards has nothing to describe.
Who can: describing and approving need the asset’s own edit permission (Dashboards or Metrics, or an editor’s share of that dashboard). Everyone else doesn’t see the button.
Several at once: with the Catalog edit permission (admins and editors have it), tick the dashboards and metrics with no description and choose Describe N with AI, up to 10 at a time. Each draft waits under Drafted descriptions waiting for review, where you approve or reject them one by one.
A model’s tables and fields: Describe with AI on a model’s row opens Prep for AI, whose drafts cover every table and field in the model’s AI scope. Someone a row-level security policy restricts on the model’s source gets drafts written from the names alone, without the tables’ counts.
A metric’s own description: editing a metric that has none, Describe with AI under its Description field drafts it in place, to approve or reject there.

It is the Description drafts feature in AI controls: an admin can turn it off for the workspace, and the built-in Viewer role doesn’t have it until an admin allows it. While it is turned off, the tab says so in one line; a role without it doesn’t see the button. Only one request drafts at a time in a workspace: another person’s run is said with who started it and when. Like every AI feature, it is available in the DataSquares app only; API keys can’t use it. Each approval is recorded in the audit log as a change of the dashboard or metric, before and after.

Assets through the API

GET /api/catalog/assets with q, sort (name, type, updated or owner), order (asc or desc) or offset answers a page, { items, total, facets }: 50 unless limit says otherwise (at most 1,000), narrowed by type, domain, ownerId or unowned=true. The facets describe the whole workspace whatever the filters, and facets.hidden counts the assets the caller may not open. A request without q, sort, order or offset keeps the earlier list, { items, facets }: up to 500, by type then name. Each row’s href_hint is where it opens in the app. A page’s rows also carry described (whether it has a description; null for a data source) and, for a model, undescribed_fields; undocumented=true lists only the dashboards and metrics with no description and the models with a table or field that has none.

Describe with AI is /api/catalog/descriptions/drafts, in the app only (an API key is refused): POST with { "assets": [{ "type": "dashboard", "id": "…" }] } drafts up to 10, each answered with its outcome (drafted, pending, described, empty, dropped with a reason, failed or not_started); GET lists the drafts waiting for your review and whether Describe with AI would run for you (describeWithAi); PUT with { "decisions": [{ "draftId": "…", "action": "approve", "text": "…" }] } approves (with your own text, if you send one) or rejects them.

PATCH /api/catalog/assets/{type}/{id} (and PUT /api/ownership/{assetType}/{id}, which the Metrics page uses) takes { "ownerId": "…", "domain": "Finance" }: null clears either, and any other key, or a body with neither, is refused. A refused owner says why in details.reason: caller_cannot_edit_models (403), owner_cannot_edit_models or owner_not_a_member (400). An API key needs dashboard:read to list assets and dashboard:write to change one. The owner dialog reads the workspace’s members (GET /api/workspaces/{id}/members), whose active and can_edit_models say whom the owner write takes.

Edit the catalog, step by step

An example as an editor: a Repeat customer term, linked to a metric, then an owner chosen for a data model.

Open Catalog. The Glossary tab holds the business terms people use, each with a plain definition. Choose New term.
Enter the term, its definition and any synonyms people search for.
The term appears in the glossary and in search. Use Edit and Delete beside it to change or remove it.
Choose + link metric to tie the term to the governed metric that measures it, so the words and the number stay together.

Lineage

The Catalog’s Lineage tab (Where each number comes from and what uses it, from the data source to the share link.) traces your workspace’s assets through its data path, including pipelines, warehouse datasets and blends:

source → pipeline → warehouse dataset → model → blend → saved query / metric → dashboard / report / presentation / story → share link

A saved query also feeds the metrics that read it and the Warehouse datasets imported from it.

Lineage is drawn for you. An asset is named when you may open it, by the permission of the page that opens it: a dashboard or a report by your role or because it was shared with you; a data source, a model or a blend, a saved query, a metric or a pipeline by its page’s view permission; a share link as what it shares. The others are counted, never named, one node for each type next to what they connect to (2 sources you can’t open), and such a node opens nothing. Certified assets carry their check badge here too, so you can see at a glance whether the blessed model is the one actually feeding a dashboard.

Start from an asset

A workspace of up to 150 assets is drawn whole, and the line above it says how many you can open. A larger one starts from Start from an asset: find one by name in Find an asset, or choose Draw the whole workspace or Show the list. The graph draws 25 assets of each type and folds the rest into one +N more node (+12 more dashboards), which draws 50 more each time you choose it. One view holds at most 5,000 assets, and says when it leaves some out: This workspace has more assets than one view lists: the first of each type are shown.

In a workspace cut that way, Find an asset also searches the whole workspace for dashboards, models, data sources and metrics, and says what it searched where: Dashboards, models, sources and metrics were searched across the whole workspace, other assets among the 5,000 assets listed. It shows up to 100 such matches (More match than are shown: type more of the name.), and one the view doesn’t list traces like any other. If that search fails, the view says so (We couldn’t search the whole workspace just now, so only the 5,000 assets listed were searched.), with Try again.

If the app meets a kind of asset it doesn’t know yet, it leaves it out of the graph rather than failing, and one that shows anyway reads as an asset (2 assets you can’t open).

Impact analysis

Choose an asset (click it, or Enter on it) and the view becomes its lineage: What feeds it (upstream), What uses it (downstream) or Both, to a number of Steps (1 to 10, or All; 2 to begin with). A line says what is shown: 2 assets feed Revenue, and 2 assets use it, within 2 steps. When the steps leave assets out, it says so (Assets more than 2 steps away aren’t shown.), with Show every step.

That’s the whole point: run it before you rename a field, retire a model, or delete a source, and What uses it shows the seventeen dashboards that were quietly depending on it. It follows the references both ways from the asset alone, so a dashboard’s siblings — the other dashboards on the same model — are not part of its lineage.

Scoped to a metric, What uses it is its impact view: every dashboard, presentation and story that uses the metric, and the share links of those dashboards, so you know who to tell before you change its definition.

Whole workspace goes back to everything, and Open beside the asset’s name opens the asset itself.

The page’s address holds what you traced and how you look at it: the asset, the side, the steps and List, each left out while it is the default, so a link you share opens the same view, for example /catalog?tab=lineage&asset=metric-…&dir=down&steps=all&view=list (an asset is its type’s prefix and its id, such as dash-… or metric-…). Back walks back through the assets you traced, not through each change of side, steps or view. An asset that doesn’t exist, or that you can’t open, shows We can’t show this asset’s lineage, with Show the whole workspace; it never falls back to the whole workspace by itself.

The graph and the list

The graph reads left to right, upstream first, and an arrow points from what feeds to what it feeds. The arrow button on a node opens its asset: a metric on the Metrics page, a saved query in the SQL editor, a blend on the Blends page, a presentation in its editor and a story on its page; a share link, a warehouse table not registered yet and a node that counts what you can’t open have no link.

By keyboard. The graph is one Tab stop. The arrow keys move up and down a column, left to what feeds an asset and right to what it feeds; Enter shows that asset’s lineage, and Tab reaches its Open link.
As a list. List shows the same lineage as text: what feeds the asset and what uses it, grouped by type, nearest first, with how many steps away each one is, 20 of each type at a time (Show more). For the whole workspace it lists every asset you can open, by type. A name shows that asset’s lineage; Open opens it.

Nothing is hand-maintained

Every edge is derived from the real references, live, each time you open the tab. A pipeline points at the dataset it feeds; a model points at a source or dataset because that’s what it is built on; a blend points at the models its sides are on; a dashboard points at a model or a blend because one of its cards queries it; a share points at its dashboard. There is no asset-level lineage metadata to fill in and nothing to keep up to date — if you repoint a card, the graph changes with it.

Pipeline edges come from stored DAG steps. System pipelines are hidden. A managed dataset is represented by its registered source node; a pipeline load whose dataset is not registered yet appears as a warehouse table node, named after its table. Saved-query dependencies use their model when model-bound and their source otherwise. Dashboard cards contribute model, saved-query, metric-bound and blend edges; reports contribute model or source edges; only active dashboard/report shares appear, as a Public link, a Password link or a Row-security link.

Presentations and stories appear where their figures are bound: a deck or a story that binds a metric, a saved query, or a model’s measure or field is drawn after that metric, query or model. A deck counts its slides’ speaker notes too, for the people who make it (its owner, editors and contributors, and admins), as only they read its notes: a metric bound only in a live number of a slide’s notes draws the deck for them, and nothing for anyone else. A deck whose notes were written before this was added is drawn once the background pass that reads them reaches it, in the minutes after the release. They are drawn for you: a deck or a story you can open is named, and opens from its node; the ones you can’t open are counted, never named, in one node of their own (2 presentations you can’t open). Decks appear only while Presentations is on for your company.

The corollary is that lineage only knows what the platform knows. A dependency expressed outside DataSquares — a view in your warehouse that quietly joins two tables, say — isn’t in the graph.

The lineage chain of a dashboard or a metric

Scope the graph to a dashboard or a metric and its lineage chain appears beside the graph: where its data comes from, hop by hop, built by rules from the same live references as the graph. The hops always come in this order, and a hop with nothing in it is left out:

source → pipeline → Warehouse dataset → model → blends → fields → measures → metrics → cards → dashboard → dashboard filters

Only what you may open is named. A source is named when your role can view data sources; a pipeline when the workspace has Pipelines and your role can view pipelines; a Warehouse dataset when the workspace has the Warehouse. The rest are counted, never named: “1 you can’t open”. Models, blends, their fields and measures, and metrics are named for every member.
Blends are the blends a card reads, after the models their sides are on, so a dashboard built on blend cards traces through them to their models, datasets, pipelines and sources.
Fields are the ones the cards read (axes, series, colour, size, tooltips, sorting and a card’s own filters), a metric’s time dimension and filter fields, and the columns the SquareX formulas of its measures and metrics read. A field with a sensitivity label is marked Labelled.
Measures and metrics show their SquareX formula.
Row-level security shows as A policy applies on the model. The policy’s rule is never shown. A policy it inherits from another model over the same source names that model: From Sales, over the same source table (see Policies from other models).
No values. A filter’s value, a default value or a row of data never appears in the chain.
Column lineage through pipelines is not tracked. The chain shows which pipelines feed a dataset, not which source column becomes which field, and a chain with a pipeline says so.
A card on a saved SQL query is counted in a note: the fields a SQL query reads are not traced.
A metric’s chain ends at its formula. A dashboard’s chain lists its cards: click a card’s name to trace that card on its own (its fields, measures and the dashboard filters linked to it), and Back to the dashboard to return.

Explain with AI

Below the chain, Explain with AI writes one paragraph that walks through the chain in plain words. It is a separate click, and it uses AI credits. A data model’s trust card offers the same paragraph for the model, written from what feeds it, from its source to the model itself (Explain this asset).

The AI is sent the chain alone: the names of the items you may open, a count of the others, the Labelled and policy marks and the formulas. Never a value, never a policy’s rule, and nothing else.
The paragraph is checked before you see it. Every name in it must come from the chain, and every number must be one of the chain’s counts. A paragraph that fails the check is not shown: “The AI’s paragraph didn’t match the lineage, so it isn’t shown. The chain above is the lineage.” The AI work was done, so it still uses AI credits.
The paragraph is marked AI-written · date and is never stored. Tracing another asset, or leaving the tab, lets it go; click again to write a new one.
It is the Governance feature in AI controls: an admin can turn it off for the workspace, and the built-in Viewer role doesn’t have it until an admin allows it. Like every AI feature, it is available in the DataSquares app only; API keys can’t use it.
It is offered only where it would run. A role without the feature doesn’t see Explain with AI: the chain stands alone. While AI, or the Governance feature, is turned off in the workspace, the button shows but can’t be clicked, and the line under it says why (an admin is told where to turn it on). A monthly AI credit budget that is used up is said when you click.

Lineage through the API

GET /api/lineage/graph returns { nodes, edges, truncated }: the whole workspace, or with asset={node-id} that asset’s lineage, direction up, down or both (the default) and depth 1 to 10 or all (2 by default). A node that counts what the caller can’t open carries hidden, how many, and no name or id of what it counts. truncated is true when the depth or the 5,000-asset limit left some out; an asset the caller can’t open, or one that doesn’t exist, is an empty graph. It needs the role’s Catalog view permission. An API key also needs dashboard:read, and names a source, a pipeline, a saved query or a report only when it can read that too (source:read, pipeline:read, query:execute, reports:read; the read scope covers all of them).

GET /api/lineage/graph/chain?kind=dashboard&id={id} (or kind=card, kind=metric, or kind=model for what feeds a data model, which needs the role’s Data Models view) returns the chain. An API key needs the dashboard:read scope, and the chain names a source, a pipeline or a Warehouse dataset only when the key can read that too (source:read, pipeline:read, dataset:read; the read scope covers all of them); the rest are counted. Its explainWithAi ({ allowed, reason, message }) says whether Explain with AI would run for the caller, without running it or spending anything: reason is app_only for an API key, not_configured on a server without AI, or the AI policy’s own (workspace_off, surface_off, role, not_member, unavailable), and message says it in the caller’s words.

POST /api/lineage/graph/explain (app sessions only; API keys are refused) takes { "kind": "dashboard", "id": "{id}" } and returns the chain with the paragraph and its outcome: written, dropped (the check failed) or unavailable.

It also refuses deletes

The same graph is what stops you shooting yourself in the foot. Deleting a Warehouse dataset that anything still references is refused — the dialog reads "{name}" can't be deleted yet, followed by “These assets still reference the dataset. Remove or repoint them first, then delete again.” Every dependent is listed and linked, so you can go fix them. (The API refuses the same delete with a 409 and the same list — see the datasets API.)

Field sensitivity & masking

Any field in a data model can carry a sensitivity label, and labelling a field masks it. In the model editor, click the field and pick a label under Sensitivity: pii, confidential or restricted. Through the API a label is free text (up to 50 characters), so it can follow whatever vocabulary your organization uses. The Catalog page itself has no label editor.

The important part is where it’s enforced: masking happens in the query engine, not in a chart component. The label follows the data into every surface that queries the model — dashboards, exports, shares, embeds and AI chat — with no per-surface opt-in, and no way to undo it from the chart side. Data quality, which reads tables directly, applies labels too (below).

What a masked user actually sees

Use of a labeled field	Result
As a dimension (axis, color, small multiples, tooltip)	values render as `***`, but the chart keeps its shape — grouping still happens on the real column, so you get one bar per real value, just unnamed
As a map’s coordinates (latitude, longitude)	values render as `***`, as for any other dimension
As a value or aggregate (y-axis, bubble size)	refused
Aggregated in a dimension’s place (a count, maximum or sum of it on the axis, color, small multiples or tooltip, including a field whose default aggregation is one)	refused, as a value is
In a filter	refused
In a sort	refused

The refusals are deliberate, and they are loud rather than quiet:

Field “Email” is labeled PII — filtering on it requires a privileged role. Remove the field or ask a workspace admin.

This is the design decision worth understanding. An average of a labeled column is still derived from the labeled data; filtering or sorting by a hidden value leaks it by inference (sort by salary, read the names off the axis). So rather than silently returning a wrong or misleading number, the query fails and tells you which field and which label stopped it.

A field computed from a labeled column is treated as that column. A calculated field whose expression reads a labeled column (say split_part(email, '@', 2)), a second field over the same column, a field on another table of the model that reads the same source table, and a field over a column that one of the table’s transform steps computes from it are masked and refused exactly as the labeled field is. The refusal names the labeled field it reads:

Field “Email domain” reads the field “Email”, labeled PII — filtering on it requires a privileged role. Remove the field or ask a workspace admin.

When DataSquares can’t tell which columns a calculated field reads (its expression selects every column, or picks one by position or by a name held in text), it treats the field as reading a labeled one whenever the model has any. A label on a calculated field protects that field itself, not the columns it’s computed from.

A label protects the column in every model of its source. A label says how sensitive a column’s data is, so it isn’t tied to the model you set it in. Label email in one model, and every other model in the workspace built on the same data source treats that column of the same table as labeled: a field over it, a calculated field that reads it, and a field over a column computed from it are masked and refused there exactly as the labeled field is, with nothing to set up in those models. The refusal names the column and says where its label is:

Field “Contact” reads the column “customers.email”, labeled PII in another model of this source — filtering on it requires a privileged role. Remove the field or ask a workspace admin.

Setting or removing a label in one model changes what the other models’ next queries show straight away. A label in a model of another workspace never applies to yours. A label on a calculated field, or on a column that only that model’s transform steps compute, still protects that field alone. Raw SQL is checked against the labels of the workspace’s live models on the source (below).

And in a Warehouse copy of its table. A table imported or promoted into the Warehouse holds the same column data as the table it was made from, so a label protects the column on both sides, for as long as the copy and the source it was made from are both live: a label in a model of the copy protects that column in every model of the source it was made from (and of other copies of the same table), and a label in a model of the source protects it in every model of the copy. Raw SQL on either side is refused the same way. The refusal says where the label is, never naming the other model, source or dataset:

Field “Email” reads the column “sales.email”, labeled PII in a model of a Warehouse dataset made from the same table — filtering on it requires a privileged role. Remove the field or ask a workspace admin.

From the copy’s side, it says in a model of the source this Warehouse dataset was made from. A dataset made from a saved query is no copy of a table, and carries none of this. A label on the copy never refuses the copy’s own refresh; see What refuses an import.

The same rule holds wherever DataSquares keeps a labeled field’s values out of a feature of its own: the AI’s stored value hints never hold such a field, Explore this slide never offers it as a filter presenters can change, the AI won’t set up an alert on it for someone the label masks, a dashboard’s member colors are kept apart for readers the label masks, Draft with AI sends it by its name and type only, and a blend never joins on a key whose data reads it, for someone the label masks.

SquareX measures are refused for masked users when they read a labeled field’s data, since an aggregate of a labeled column is derived from it: a column the measure names anywhere (as a value, inside an iterator’s row expression, in a Calculate filter, as a date column or a Fixed dimension), however deep through the measures it uses, a calculated field it reads that reads one, or a column a table’s transform steps compute from one. A measure that reads none is served, whatever else its table holds: with customer_email labeled, Sum(orders.revenue) still shows, and CountDistinct(orders.customer_email) is refused, naming the field:

Measure “Unique customers” reads the field “Email”, labeled PII — a measure that reads a labeled field requires a privileged role. Remove the measure or ask a workspace admin.

When DataSquares can’t tell which columns a measure reads (SQL that can read a column without naming it), it fails closed: the measure is refused while any field of the model is labeled. Governed metrics follow the same rule, on cards, decks and digests and in the AI, since every metric is read as a measure.

Who sees clear values

Company admins. Everyone else — members, support staff, and API-key callers — is masked, and a caller whose role can’t be determined is masked too (fail closed). Because the masked query is literally different SQL, it has a different cache key: a cached clear result can never be handed to a masked user.

Who can change a label

Anyone who can edit the model can add a label, because a label only restricts. Changing or removing one unmasks the field for everyone else, so only a company admin can do that; for anyone else, a labelled field’s Sensitivity menu is locked. In the Catalog, the lineage chain marks a labelled field Labelled, and search marks one with labelled: true; neither shows a value.

Through the API, send PUT /api/models/{modelId}/tables/{tableId}/fields/{fieldId} with { "sensitivityLabel": "PII" }, or null to clear it.

Raw SQL and external egress

Raw SQL cannot be rewritten safely, so it is blocked, not silently passed through, when it references a labeled physical column. SELECT * and SQL the parser cannot prove safe are also refused for non-admins. On anonymous or external egress paths such as public shares and webhook activations, even an admin identity cannot bypass that refusal.

The check reads the labels of the workspace’s live models on the source, and of the Warehouse copies linked to it (above); a model deleted since, or one of another workspace, labels nothing here. A refusal names the column, never a model’s field, since the model may be one you can’t open:

Column “customers.email” is labeled PII; raw SQL touching it — requires a privileged role. Remove the field or ask a workspace admin.

The visual query builder’s steps, an activation’s field mapping and a Warehouse table import name a labelled column the same way.

The raw-SQL check matches physical column names and deliberately fails closed. It can therefore over-block ambiguous SQL rather than risk exposing a labeled value. Admins may query a labeled column directly in non-egress raw SQL; API keys, support users, members, and unknown roles may not.

In data quality

Data quality profiles and checks read tables directly, so they apply labels themselves (details):

A profiling scan never sends a labeled column’s values or statistics to the AI, whoever runs it, company admins included.
Column Profile shows a labeled column’s values only to company admins. Anyone else, API keys included, sees its counts and lengths.
A Custom SQL test keeps sample rows only when its query reads no labeled column, by the same test as raw SQL above.

Governed metrics
Lifecycle: export, import & restore — promoting and rolling back the assets you’ve certified.
Data models & relationships — where fields, and row-level security, are defined.
AI chat — how glossary grounding changes answers.
Users, roles & invites — who counts as an admin.