Skip to content
M↓ View as Markdown ↗

Glossary

People don't talk like database schemas. Your sales team talks about "quotes", but your database calls them "contracts with status='quoted'". Your executives ask about "active customers", but your schema has multiple flags and date fields that define "active". The glossary bridges this gap by mapping business terminology to your semantic layer.

Availability

  • Who can do this: members with the Edit capability in the active Workspace can create and edit glossary terms.

Glossary terms belong to a Workspace. Term names must be unique within that Workspace.

Why use a glossary?

When someone asks "How many quotes did we make this year?", the AI Analyst needs to know which filters, measures or models "quotes" maps to. Without a glossary it guesses. With one, it knows, and people can ask in the terms they use without knowing your schema.

A term is also defined once, so sales, marketing and executives who ask about "active customers" get the same answer.

Create a glossary term

  1. In Studio, open Glossary and click New term.
  2. Fill in the fields described below. Only Name is needed to start.
  3. Click Create term.

After you create the term, its page has three tabs:

Tab What you do there
Overview Edit the Definition, Synonyms and Tags.
Discovery Map the term to models, dimensions, measures, filters and metrics.
Hierarchy Set the Parent term and add Child terms.

Edits on all three tabs are saved together. Click Save changes to keep them. If you leave the page with unsaved edits, you're asked whether to discard them.

Name

The business word or phrase you want to define.

Examples: Active Customer, Quote, Premium User, Transaction, Order Status

Definition

The business meaning of this term. AI Analysts use it when they look the term up, and people see it when browsing the glossary.

Example: "A customer with at least one transaction in the last 90 days and an active subscription status."

Write for someone unfamiliar with your business. Cover edge cases and important distinctions, and say how the term relates to the data it is mapped to.

The definition editor supports Bold, Italic, Bullet list and Ordered list. Use Add SemQL example to include a SemQL snippet that shows how the term translates into a query.

Synonyms

Other names for the same concept. They help AI Analysts match questions that don't use the canonical term.

Example: For the term "Active Customer", you might add:

  • Current Customer
  • Engaged Customer
  • Active Account

When someone asks about "current customers", the AI Analyst knows to use the "Active Customer" term and its mappings.

To add a synonym, type it and press Enter. You can add several synonyms to each term.

Tags

Labels for grouping terms in the glossary list.

Example tags: core-concept, user-types, metrics, time-periods

Tags don't change how AI Analysts interpret a term, but they do decide which terms each AI Analyst can see. See Control which terms an AI Analyst sees. Tags are shared with Models in one tag list per Workspace. See Tags.

Parent term

The broader umbrella this term sits under. For example, "Finance Revenue" can sit under "Revenue". See Term hierarchy.

Mappings: connecting terms to your data

Mappings, on the term's Discovery tab, are the most important part of a term. A mapping lets the AI Analyst see the term when it uses that entity, and find the entity when it looks up the term.

A mapping only links the term to one entity. It has no description of its own: explain the connection in the term's Definition instead.

To add a mapping:

  1. Open the term and select the Discovery tab.
  2. In the section you want (Models, Dimensions, Measures, Filters or Metrics), click +.
  3. Search for the entity and select it. For dimensions, measures and filters you can narrow the list by model (All models).
  4. Click Save changes. The mapping isn't kept until you save.

To remove a mapping, click the Remove button next to it, then click Save changes.

Models

Connect the term to one or more models.

Example: "Active Customer" might map to the customers model, since active customers are represented in that model.

Dimensions

Connect the term to dimensions that represent or describe this concept.

Example: "Active Customer" might map to:

  • customer_tier dimension

When someone asks "Show me active customers by tier", the AI Analyst knows to use the customer_tier dimension.

Filters

Connect the term to pre-defined filters that narrow data to this concept.

Example: "Active Customer" might map to:

  • active_customers_only filter

When someone asks "Show me just active customers", the AI Analyst knows to apply the active_customers_only filter.

Measures

Connect the term to measures that count, sum or aggregate this concept.

Example: "Active Customer" might map to:

  • total_active_customers measure

When someone asks "How many active customers do we have?", the AI Analyst knows to use the total_active_customers measure.

Metrics

Connect the term to metrics that calculate business KPIs related to this concept.

Example: Customer-related terms might map to metrics like monthly_active_customers, customer_retention_rate or average_revenue_per_customer.

When someone asks "What's our weekly active user count?", the AI Analyst uses the mapped metric.

Term hierarchy

Relate broader and more specific terms so AI Analysts can discover related vocabulary when they look up a term. Any term can have a parent, whether you created it manually or it was synced from a catalog.

  • Parent term: on the Hierarchy tab (or when you create the term), select the broader term this one sits under. To remove it, select No parent term.
  • Child terms: on the Hierarchy tab, use Add a child term… to nest an existing term under this one. Adding a child sets this term as that term's parent. To remove a child, click Remove child term next to it.

Setting or removing a parent term and adding or removing child terms are saved with the rest of your edits: click Save changes to keep them.

A term can have only one parent, and it can't be its own parent.

How the AI Analyst uses the glossary

When a user asks a question, the AI Analyst:

  1. Identifies business terms in the question
  2. Looks up those terms in the glossary. For each term it gets the definition, synonyms, tags, parent term and mapped entities.
  3. Uses the mappings to find relevant models, dimensions, filters, measures or metrics
  4. Builds the query from those components

Example flow:

  • User asks: "How many customers placed orders last week?"
  • The AI Analyst finds "customers" in the glossary, mapped to the customers model and total_customers measure
  • It finds "orders" in the glossary, mapped to the orders model
  • For "last week", it uses a time dimension with week grain
  • It builds a query combining these components

The AI Analyst only sees the terms its glossary access allows.

Control which terms an AI Analyst sees

Each AI Analyst has its own glossary access, based on tags:

  1. In Studio, open AI Analysts and select the analyst.
  2. Open the Glossary tab.
  3. Under Access Mode, click Edit and choose:
    • All terms
    • Only terms with these tags: only terms carrying one of the selected tags are visible.
    • All terms except these tags
  4. Select the tags, if the mode uses them.
  5. Click Save changes.

The list headed Analyst can see these terms (with the number of terms in brackets) shows the result. If you leave the tab with unsaved changes, you're asked whether to discard them.

New AI Analysts see no glossary terms

A newly created AI Analyst starts with Only terms with these tags and no tags selected, so it sees no glossary terms until you configure this.

Browse and find terms

The glossary list shows terms alphabetically, grouped by first letter (A, B, C and so on). Each item shows:

  • The term name. Terms synced from a catalog show a small Actian Data Intelligence Platform icon; hover it to see whether the term is synced or orphaned.
  • A preview of the definition (or "No definition").

Use Search terms… and the Filters panel (Source: Manual or Catalog, Tag, Empty definition, Empty tags) to narrow the list.

You can also find terms with the Studio search palette. See Searching the semantic layer.

History and deleting terms

  • Version history: click the Version history button on the term page to see earlier versions, compare changes and restore a version. See Version history.
  • Delete: deleting a term removes it from the Glossary list and from search. Its name can be reused.

Best practices

  • Start with the words your team uses most often in questions.
  • Add synonyms for how different departments refer to the same concept.
  • Map each term to every model, dimension, filter, measure and metric it relates to. More mappings give the AI Analyst more to work with.
  • Agree on a small set of tags and use them consistently, because tags decide which AI Analysts see a term.
  • Keep the glossary current as your semantic layer grows.

Syncing terms from the Actian Data Intelligence Platform

If your organization uses the Actian Data Intelligence Platform as its enterprise data catalog, you can connect it to Actian AI Analyst and sync its governed business terms into your Glossary.

How synced terms work

Once a catalog connection is set up and a sync runs, terms from the catalog appear in your Glossary alongside any manually created terms. They behave the same way for AI Analysts: the AI Analyst looks up terms, finds their definitions and uses them to answer questions.

A sync brings in:

  • Name and definition
  • Synonyms

The sync doesn't import a parent/child hierarchy. You can set the hierarchy for synced terms yourself on the Hierarchy tab.

Identifying synced terms

A synced term shows a Synced badge in its header. In the glossary list, synced terms show a small Actian Data Intelligence Platform icon. Use the Source filter (Catalog) to list only synced terms.

Orphaned terms

If a term is removed from the catalog, the next sync keeps it in your Glossary and marks it orphaned. The term's header shows an Orphaned badge, and its tooltip says the term is no longer in the Actian Data Intelligence Platform. Orphaned terms stay (and can still be mapped) until you delete them. They become Synced again if the term reappears in the catalog.

Warning

AI Analysts can still see orphaned terms. Delete any orphaned term you no longer want them to use.

Editing synced terms

You can add mappings, tags and a parent term to synced terms, just like manually created terms. This lets you enrich catalog terminology with query-specific context.

Info

The name, definition and synonyms of a synced term are overwritten on every sync, so make changes to them in the Actian Data Intelligence Platform. Tags, mappings and the parent term you add in AI Analyst are kept.

  • Deleting a synced term in AI Analyst is undone if the term is still in the catalog at the next sync.
  • A manually created term with the same name as a catalog term is taken over by the sync: it becomes a synced term, and its name, definition and synonyms are overwritten.