Docs/Semantic Layer/Domains

Domains

How to create, edit, and manage Celiq Domains — the named YAML groupings that hold your reveals plus connection and AI context.

WeaverLuminaryUpdated June 2026 · 7 min read

✦

In this section

Part of Celiq's semantic layer platform. Connect your warehouse, model your data once, query it everywhere.

💡

Tip

What it is: A Domain is a named grouping in your semantic layer. Its YAML content holds a reveals array plus domain-level metadata — description, connection, and ai_context.
When to use it: Whenever you want to bundle a set of related reveals under one connection and give Orion a shared block of business context for them.
Where to find it: Author and edit Domains in Forge. Browse them read-only under Context Studio → Domains.
Who can use it: Weavers and Luminaries. Every Domain endpoint requires the Weaver-and-above role.

A Domain is the top-level container of the Celiq semantic layer. Each Domain is one row in the domains table, and its content column holds a single YAML document. That YAML names the domain, points it at a connection, optionally carries ai_context for Orion, and lists the reveals that sit inside it.

Because everything is stored as YAML, a Domain is fully versioned: every save writes a new entry to the file-version history, and you can edit the raw source directly when you need fine control.

Overview

A Domain ties three things together:

A connection — the warehouse the domain's reveals query against.
Reveals — the queryable surfaces (reveals[]) that reference your nodes' fields. Each reveal names a primary_node and the metrics and attributes it exposes.
AI context — an optional ai_context block that Orion reads to understand what this domain is for.

Domains are scoped to a workspace and, optionally, to a project. The listing endpoint joins each domain to its project and connection so you can see, at a glance, which warehouse and project a domain belongs to.

When to use it

Create a Domain when you want to:

Group related reveals that share one connection — for example, all your order-and-fulfillment reveals against the production warehouse.
Give Orion shared context for a set of reveals, by writing a domain-level ai_context block.
Scope analytics to a project, so the domain (and its reveals) only appears within that project.

If you only need a single queryable surface, you still need a Domain to hold the reveal — reveals never exist on their own.

Concepts

Term	Meaning
Domain	A named YAML grouping stored in the `domains` table. Its `content` is a YAML document with `domain`, `connection`, optional `description`/`ai_context`, and a `reveals` array.
Reveal	An entry in the domain's `reveals[]` array. Each names a `primary_node` and the metrics/attributes it exposes. See Reveals.
Connection	The warehouse the domain queries. Referenced by the `connection` key in the YAML and resolved to a connection row on save.
ai_context	A free-text block Orion reads to understand the domain. Normalized internally so Orion sees it as the domain's AI context.
System domain	A domain whose name starts with `_celiq_`, or one that lives in a system project. These are hidden from the normal listing and are read-only for everyone except the super admin.
Project scope	The optional `project_id` a domain belongs to. When set, the domain is filtered to that project.

Getting started

Prerequisites

The Weaver or Luminary role. Every Domain endpoint is gated by the Weaver-and-above check.
At least one connection configured, so the domain's connection key resolves to a real warehouse. See Warehouses.
The nodes your reveals will reference should exist, so the semantic gate can confirm the fields are real (see Step-by-step).

How to open it

To author or edit a Domain, open Forge and create a new domain or select an existing one.
To browse Domains read-only, open Context Studio and select the Domains tab. Each card shows the domain name, its node count, its connection, and its description, with an Edit → action that takes you into Forge.

Step-by-step

Open Forge and start a new domain

In Forge, create a new domain. Give it a name — it must not start with _celiq_, which is reserved for system domains and is rejected on save.

Set the connection and description

In the domain YAML, set the connection key to the warehouse you want the reveals to query, and add a description. The validator warns if connection is missing.

Add reveals

Add entries to the reveals array. Each reveal needs a primary_node and the metrics/attributes it exposes. See Reveals for the full reveal shape.

Add AI context (optional)

Add an ai_context block at the domain level so Orion understands what the domain covers. This is read by Orion when it reasons over the domain.

Save through the gate

Save the domain. Celiq parses the YAML, runs the semantic gate, and checks your plan's reveal limit before writing. If anything fails, the save is rejected with a specific message — fix it and save again.

Verify

Run the domain's validate check (or re-open it from the Context Studio Domains tab) to confirm valid YAML, a set connection, and one or more reveals.

Examples

A minimal Domain that groups two reveals against the production warehouse and carries AI context for Orion:

orders.domain

domain: orders description: Order and fulfillment analytics for the storefront. connection: prod_warehouse ai_context: | This domain covers placed orders and their fulfillment. "Revenue" means net order value after refunds. reveals: - name: order_summary label: Order Summary primary_node: orders suggested_metrics: - total_revenue - order_count suggested_attributes: - order_status - channel - name: fulfillment label: Fulfillment primary_node: shipments suggested_metrics: - shipped_count suggested_attributes:

- carrier

On save, Celiq:

Parses the YAML (a syntax error returns Invalid YAML: ...).
Runs the semantic gate — for every reveal whose primary_node already exists, it confirms the referenced fields exist on that node. Reveals whose node is not yet authored are skipped, so authoring order is never blocked.
Counts the reveals in this domain plus all other domains in the workspace and rejects the save if the total would exceed your plan's reveal limit.

Best practices

One connection per domain. A domain has a single connection; put reveals that query different warehouses in separate domains.
Author nodes before reveals where you can. The semantic gate only validates reveals whose node already exists. Creating the node first means field-reference mistakes are caught at save time rather than later.
Write a real ai_context. This is the shared context Orion uses for the whole domain — describe what the data means and how key terms are defined.
Scope to a project when the data is project-specific, so the domain and its reveals only surface where they belong.
Keep reveal counts deliberate. Reveals are limit-enforced across the whole workspace, so retire reveals you no longer use rather than letting them accumulate.

Tips

💡

Tip

You can edit the raw YAML directly — the …/raw source is the exact content of the domain. When you save through Forge, Celiq normalizes ai_context and reveal fields for you, so you do not have to match internal naming. The Context Studio Domains tab is read-only; use its Edit → action to jump back into Forge for changes.

Common mistakes

⚠️

Warning

Naming a domain _celiq_… — names starting with _celiq_ are reserved for system domains and rejected with Name cannot start with _celiq_.
Referencing fields that don't exist on the node — if a reveal names metrics or attributes that aren't on its primary_node, the semantic gate rejects the save. Fix the reveal's field references and save again.
Trying to delete a domain whose reveals are still in use — deletion is blocked while any reveal is referenced by a mosaic or prism.
Expecting system domains in the list — domains named _celiq_… (and those in system projects) are hidden from the normal listing and are read-only except for the super admin.

Troubleshooting

Symptom	Cause	Fix
`Invalid YAML: <message>` on save	The domain `content` is not valid YAML.	Correct the YAML syntax shown in the message and save again.
`name and content are required`	A create request is missing the name or the YAML body.	Provide both a name and the domain content.
`Name cannot start with _celiq_`	The chosen name uses the reserved system prefix.	Pick a name that doesn't start with `_celiq_`.
Save rejected, "Fix the reveal field references before saving the domain."	The semantic gate found a reveal referencing fields not present on its node.	Correct the reveal's metric/attribute names to match the node, or author the missing node, then save.
`Reveal limit reached (<n> on your plan). Upgrade to add more reveals.`	Saving would push the workspace's total reveal count over the plan limit.	Remove unused reveals, or upgrade your plan from Billing.
`Cannot delete domain "…" — reveals are in use: …`	A reveal in the domain is referenced by one or more mosaics or prisms.	Migrate or delete those mosaics/prisms first, then delete the domain.
`Domains in system projects cannot be deleted.`	The domain lives in a system project.	System/demo domains are protected; only the super admin can remove them.
`Domain already exists` on create	A domain with that name and project scope already exists.	Edit the existing domain instead of creating a duplicate.
`Domain not found`	The name (or id) does not match a non-deleted domain in your workspace.	Check the name and that the domain has not been deleted.
Validate shows `⚠ Missing connection` or `⚠ No reveals defined`	The YAML omits `connection`, or its `reveals` array is empty.	Add a `connection` key and at least one reveal.