Topics
Curated bundles of semantic objects that give Orion grouped, governed context inside Context Studio.
When to use it — When you want Orion to treat a set of objects as one coherent, governed dataset for a recurring question area such as "Revenue Analysis" or "Customer Retention".
Where to find it — Context Studio › Topics (the tag icon in the left nav).
Who can use it — Weavers and Luminaries can create and edit Topics. Only Luminaries can certify them.
Topics are a Context Studio governance object, not a CML object. You do not define them in Forge or in a .yml file. Instead, you assemble them in Context Studio by pointing at semantic objects you already have, so Orion can reason over a named, trusted group rather than the whole model at once.
Each Topic has a name, an optional description, an optional domain, an owner, a status, and a list of items. The items are the semantic objects you add to the bundle.
Overview
A Topic answers a simple need: when someone asks Orion about a business area, you want it to draw on the right metrics and dimensions for that area — and ignore the rest. A Topic is the curated shortlist.
When you create a Topic, you give it a name and a short description of the questions it helps answer. You then add items that reference existing semantic objects. Each item records three things:
- object_type — what kind of semantic object it is (for example a metric or a dimension).
- object_id — which specific object it points at.
- role — how the object participates in the Topic. This defaults to
supporting.
Topics carry a governance lifecycle. A new Topic starts in draft. A Luminary can later certify it, which marks it as trusted (status certified) and records who certified it and when. Certified Topics are visually distinguished in the list with a green "certified" badge.
When to use it
Use a Topic when you want Orion to have grouped context for a recurring area of analysis, and when you want that grouping to be governed rather than ad hoc.
- You keep getting questions about one business area (revenue, retention, fulfillment) and want Orion to consistently reach for the same trusted objects.
- You want a curated, named dataset that a Luminary can sign off on before the organization relies on it.
- You want to bundle a primary metric together with the dimensions and supporting metrics that give it meaning.
If you only need to mark a single object as trusted, use a Certification instead. If you want to model relationships across the whole semantic model, see the Knowledge graph.
Concepts
| Term | What it means |
|---|---|
| Topic | A named bundle of semantic objects that gives Orion grouped context. |
| Item | A single entry inside a Topic that points at one semantic object via object_type, object_id, and role. |
| Role | How an item participates in the Topic. Defaults to supporting. |
| Owner | The user who created the Topic. Stored as owner_id and shown as the owner name. |
| Status | The lifecycle state of the Topic: draft (default) or certified. |
| Certified | A Luminary-only state marking the Topic as trusted; records who certified it and when. |
| Domain | An optional label associating the Topic with a business domain. |
Getting started
You need a Weaver or Luminary role to create and edit Topics. You also need some semantic objects already modeled (metrics and dimensions) so you have things to bundle.
Open Context Studio
Go to Context Studio. This is the intelligence layer for your semantic model and Orion AI.
Select Topics
In the left nav, choose Topics (the tag icon). You will see the list of existing Topics, each showing its status badge and item count.
Step-by-step
Start a new Topic
Click + New topic. An inline form opens.
Name the Topic
Enter a clear Topic name, for example Revenue Analysis. The name is required — you cannot save without one.
Describe what it answers
In the Description field, write what questions this Topic helps answer. This is optional but strongly recommended, because it is the context Orion and your teammates read to understand the Topic's purpose.
Create the Topic
Click Create topic. The new Topic appears at the top of the list with a draft status badge.
Add items
Add the semantic objects that belong in this Topic. Each item points at one object by its type and id, and is given a role. If you do not specify a role, the item is saved with the role supporting.
Certify when ready (Luminary only)
When the Topic is reviewed and trusted, a Luminary clicks Certify. The status changes to certified, the card border turns green, and Celiq records who certified it and the time of certification.
To remove a Topic, click the trash icon on its card and confirm. This deletes the Topic and its items.
Examples
Suppose you want Orion to have grouped context for revenue questions. You create a Topic named Revenue Analysis with a primary revenue metric and the dimensions used to slice it.
The item payload you send when adding an object to a Topic looks like this:
{
"object_type": "metric",
"object_id": "total_revenue",
"role": "primary"
}If you omit role, the item is stored as supporting:
{
"object_type": "dimension",
"object_id": "order_region"
}A finished Revenue Analysis Topic might bundle:
| object_type | object_id | role |
|---|---|---|
| metric | total_revenue | primary |
| metric | average_order_value | supporting |
| dimension | order_region | supporting |
| dimension | order_date | supporting |
Once a Luminary certifies it, the Topic shows a green certified badge and an item count, and Orion can treat the bundle as a trusted grouped context for revenue questions.
Best practices
- Give every Topic a description. It is the human- and AI-readable statement of what the Topic is for. A Topic with no description is harder for both your team and Orion to use correctly.
- Keep Topics focused. A Topic should map to one coherent business area, not the whole model. Smaller, sharper bundles give Orion cleaner context.
- Mark the lead object. Use a role like
primaryfor the central metric and leave the rest assupporting, so the Topic's intent is explicit. - Certify deliberately. Treat certification as a sign-off. Certify a Topic only after the items and description are reviewed, because certification signals trust to the whole organization.
- Set an owner expectation. The creator becomes the owner. Keep ownership with someone who understands the business area so the Topic stays accurate over time.
Tips
Use the item count badge on each Topic card as a quick health check. A certified Topic with zero items is a signal that the bundle was never actually populated — open it and add the objects it is meant to group.
Common mistakes
Saving without a name. The name field is required. An empty or whitespace-only name is rejected, so the Topic will not be created.
Treating Topics as CML. Topics are not defined in Forge or in
.yml files. They live only in Context Studio. Do not look for them in your project's CML.Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Topic will not save | The name is empty or only whitespace | Enter a non-empty Topic name; the backend returns name required (400) otherwise. |
| Adding an item fails | The request is missing object_type or object_id | Provide both fields; the backend returns object_type and object_id required (400). |
Added item has role supporting when you wanted something else | No role was provided | Set role explicitly when adding the item; it defaults to supporting. |
| No Certify button on a draft Topic | Your role is not Luminary | Have a Luminary certify it; certification is restricted to the Luminary role. |
| Certify or edit returns Not Found | The Topic id does not exist in your workspace, or it was deleted | Refresh the Topics list and retry against an existing Topic. |
| Edit or delete has no effect | The Topic belongs to a different workspace | Topics are scoped to your workspace; you can only change Topics in your own workspace. |