Adding concepts¶

A concept is more than a name and a definition, the extra fields are what let Adverity Atlas compute a metric correctly, aggregate it safely, and recognise it whatever word the question uses. This page covers each field.

Prerequisites¶

Editor role to write a concept directly, or Analyst to propose one for approval (see Proposing a term for approval below). New concepts are created at the workspace tier; promoting them to the organization tier is a separate, reviewed step (see Concept layers).

Creating a concept¶

Open the Glossary and click Add Concept. The New Glossary Concept panel opens, described as “Add a business concept to the glossary”.
Enter a Display Name. This is required, and the Canonical Name is auto-generated from it.
Write the Definition, what the term means in your business.
Set the Category to Metric, Dimension, Identifier, Timestamp, or Text / Label, and fill in the remaining fields below.
For a calculated metric, add the Expression.
Click Create Concept. The concept is saved as a draft, so a half-finished definition never reaches Chat.

Fields on the form¶

Field	What it does	Required
Display Name	What people call it, for example “Customer Lifetime Value”	Required
Canonical Name	The stable machine name, auto-generated from the display name. It cannot be changed after creation	Required
Definition	What the term means in your business context	Optional
Category	Metric, Dimension, Identifier, Timestamp, or Text / Label	Optional
Vertical	The business vertical the concept belongs to, for example `marketing`	Optional
Parent Concept	An existing concept this one sits under, for grouping related terms	Optional
Aliases	Comma-separated alternative names, for example `CLV, CLTV, lifetime value`. A question using any alias resolves to this concept	Optional
Platforms	Comma-separated platform tags, for example `google_ads, facebook, tiktok`, scoping the concept to those contexts	Optional
Expression	The formula for a calculated metric, referencing other canonical names, for example `clicks / NULLIF(impressions, 0)`. Leave empty for base concepts	Optional

Tip

Add aliases generously. If your team says both “CVR” and “conversion rate”, add both, otherwise a question using the word you skipped will not resolve. Suggest with AI under the Aliases field proposes candidates you can click to add.

Two fields have an AI assist. Generate with AI under the Definition field drafts a definition from the display name, category, and vertical. Suggest with AI under Aliases proposes alternative names. Both fill the field for you to review and edit, they do not save anything on their own.

As you type an expression, Adverity Atlas previews it below the field so you can see whether it resolves against the canonical names you referenced.

Proposing a term for approval¶

An Analyst contributes to the glossary without being able to write it directly. The form is the same one above; what changes is that the result is filed for review instead of saved.

Open the Glossary and click Add Concept. The panel opens titled Propose a Glossary Term, with the subtitle “Submitted for a Knowledge Manager to approve”.
Fill in the fields exactly as above.
Click Propose Term. Adverity Atlas confirms with “Term proposed for approval.” and the request appears in Settings > Approvals.
A Knowledge Manager (or an Admin) approves it. The term is written at that point, not before, so nothing reaches Chat unreviewed.

Editing works the same way. Open an existing workspace term and the panel reads Propose an edit to followed by the term’s name, with a Propose Edit button, and Adverity Atlas confirms with “Edit proposed for approval.”

Note

Only workspace-specific terms can be edited by proposal. A standard or organization concept has to be cloned into the workspace first, see Overrides. One proposal per term at a time, a second is refused while the first is still pending.

Creating a concept from Chat¶

Defining a term does not have to mean leaving the conversation. Ask for it in Chat and Adverity Atlas creates the concept and activates it in the same turn, so it is usable straight away:

“Define net_spend as spend after agency fees, with net_cost and spend_net as the source column names”

Because the concept is activated, Adverity Atlas also queues the pass that links matching columns to it, so Linked Columns on the concept fills in shortly afterwards without further action. If a similar concept already exists, Adverity Atlas offers it for reuse instead of creating a near-duplicate, and a name that is already taken is routed to an edit rather than a second copy.

Chat can also publish and retire concepts that already exist, including the drafts Adverity Atlas proposes for itself:

“Publish the campaign_type draft”

“Retire cost_per_lead”

Concepts created this way are scoped to the current workspace. Organization and standard concepts stay an admin action, see Concept layers.

Note

Editing a shared concept from Chat does not change the shared definition. Adverity Atlas creates a workspace-scoped copy that overrides it and applies the edit there, the same behaviour as an override made in the UI.

Concept categories¶

Category	What it is	Examples
Metric	A measurable value, often computed	ROAS, CPA, spend
Dimension	A categorical attribute to group or filter by	Channel, campaign, country
Identifier	A key that identifies a thing	Campaign ID, account ID
Timestamp	A point in time, so the reporting grain is recorded rather than guessed from the column name	Report date, load timestamp
Text / Label	Free text that is neither a measure nor something you group by	Ad headline, notes

A concept’s category is the same vocabulary the column classifier uses, which is what lets a classified column link to a concept. Date and ID columns are classified and mapped like any other, so a timestamp or identifier concept can carry the fact that would otherwise have to be inferred from a column name.

Refining how a concept behaves¶

Some attributes sharpen a concept beyond its definition, how a metric aggregates, how its value is read and formatted, and whether it is sensitive. These are not on the concept form; set them by asking in Chat once the concept exists. The concept detail page shows Aggregation, Value Direction, Output Format, Privacy, and any Aggregation Warning under Behavioral Semantics.

Aggregation: How it rolls up across rows: sum, average, last value, weighted average, or not aggregatable
Aggregation Warning: A caution for when the metric must not be combined naively, “Do not sum CTR across campaigns”
Output Format: Currency, percentage, integer, or decimal, so the answer is formatted the way people expect
Value Direction: Whether higher is better, lower is better, or neither, used when Adverity Atlas judges whether a change is good or bad
Typical range: The normal band for the value, e.g. a rate between 0 and 1, helps flag anomalies (recorded on the concept, not shown on the detail page)
Privacy: Marks a concept as containing PII, so it is handled with the appropriate care

The aggregation rule matters as much as the formula. A rate like CTR averaged when it should be recomputed from its parts gives a wrong number that still looks reasonable; declaring the rule prevents that.

Status¶

A concept you create is Draft, Active, or Deprecated. Only active concepts are used in Chat. Status is not a field you type: a new concept starts as a draft, and on the concept detail page you click Activate to put it into use or Deprecate to retire it without deleting the history.

A fourth status, Superseded, appears only on Standard concepts. When an Adverity release of the standard glossary merges one Standard concept into another, the merged concept is marked Superseded rather than removed, so you can still trace the term. Its detail page shows View replacement, which opens the concept that took its place.

Working on many concepts at once¶

Activating a newly classified warehouse one concept at a time is slow. Select concepts with the checkboxes in the glossary list and an actions bar appears with four bulk operations:

Action	What it does
Activate	Puts every selected draft into use, so Chat can resolve them
Deprecate	Retires the selected concepts without deleting their history
AI Enrich	Fills gaps on the selected concepts: a missing definition, the behavioral semantics of a metric, and platform variants. It runs in the background and skips anything already filled in, so you review drafts instead of writing from scratch
Delete	Removes the selected concepts permanently

Selection follows your filters. Filter the list first, then select, and the action applies to that set rather than the whole glossary. Select all N matching the filters escalates beyond the rows currently loaded to every concept the filters match.

Bulk actions cover Organization-scoped concepts as well as the ones defined in the workspace you are standing in. Filter to Scope: Organization and Status: Draft to activate an imported organization glossary in one pass, rather than opening each concept. A checkbox appears on an Organization row only if you can manage the organization-wide glossary, and never on a Standard concept, which stays clone-only in the workspace glossary.

Warning

Deleting concepts cannot be undone, and deleting an Organization concept removes it from every workspace. When you select everything matching the current filters, Adverity Atlas asks you to confirm the exact number of concepts, and names how many of them are organization-wide, before it deletes them. Prefer Deprecate when you only want a term out of Chat.

Automatic classification¶

You do not have to build the glossary entirely by hand. When you connect a data source, Adverity Atlas classifies its columns against the glossary and proposes matches for you to confirm or correct, the fastest way to cover a new warehouse. Columns that resolved to a concept are listed on the concept detail page under Linked Columns, grouped by table, with each table shown alongside the collection it belongs to so that two tables with the same name in different schemas or datasets stay distinguishable. The list shows only columns in data sources bound to the current workspace, and leaves out any column the workspace hides, whether directly or through its table or collection. See Data sources.

Refreshing classifications after a glossary change¶

Editing, promoting, or deprecating an organization concept refreshes classification across your tenant. About a minute after the change, Adverity Atlas re-classifies the columns that were matched weakly or not matched at all, in every data source bound to a workspace. Several edits in a row are combined into one pass. Columns a workspace classified differently for itself are left alone, and workspace concepts do not trigger a refresh.

Each pass is a task named Refresh glossary classifications. It covers the whole tenant, so it is listed in the All workspaces view of Task Executions rather than on a single workspace’s Tasks page. If no AI provider is configured, the task fails with “No LLM provider configured; classifications were not refreshed.” Set one up in AI providers.

What’s next?¶

Concept layers, which tier a new concept lands in
Overrides, adjust a shared concept instead of duplicating it
Approvals, where a proposed term waits for review
Measures, give the concept executable SQL on a specific table
Chat, see a concept in use