Docs/Physical Layer/Physical Layer

Physical Layer

How Celiq connects logical dataset definitions to the physical tables in your warehouse — and keeps them in sync across environments.

LuminaryWeaverUpdated June 2026 · 5 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: The Physical Layer is the bridge between your warehouse tables and Celiq's semantic model. It lets you define datasets once and map them to different physical tables in different environments.
When to use it: When setting up multi-environment workflows (Prod/Dev/Staging), onboarding a new warehouse, or managing schema changes across deployments.
Where to find it: Lumen → Physical Layer (Luminary role required to manage; Weavers can view).
Who can use it: Luminary (manage), Weaver (view).

The Physical Layer sits between your warehouse and your semantic model. It answers one question: "When a node references the orders dataset in the Production environment, which physical table does Celiq actually query?"

Architecture overview

Celiq's data model has three tiers:

Semantic Layer  →  Physical Layer  →  Warehouse
(Nodes / CML)      (Datasets / Deployments / Mappings)   (Snowflake / BigQuery / Postgres / …)

Tier	What lives here	Who manages it
Semantic Layer	Nodes, domains, metrics, dimensions, CML	Weaver
Physical Layer	Datasets, deployments, mappings	Luminary
Warehouse	Actual tables, schemas, databases	Data engineering team

The Physical Layer is intentionally separate from the semantic layer. A Weaver can change how revenue is calculated without touching which table backs it. A Luminary can point a deployment at a new warehouse without rewriting any CML.

Three core concepts

Datasets

A dataset is a logical table definition — a named schema of columns (names and types) that represents a table you want to use in the semantic model.

Think of a dataset as a contract: "Wherever we run this model, there will be a table with these columns." The dataset doesn't live in any one warehouse — it's the abstract definition that mappings then wire to physical tables.

Learn more about Datasets →

Deployments

A deployment is a target environment — Production, Development, Staging, or any other environment you define. Each deployment has its own set of physical table mappings.

Every workspace has at least one deployment marked as default. Discover, Mosaics, and Orion always query through the default deployment unless you explicitly switch.

Learn more about Deployments →

Dataset Mappings

A dataset mapping connects a dataset to a physical table in a specific deployment. Each mapping specifies:

Which deployment this applies to
Which connection (warehouse) to use
The exact physical table name (e.g. public.orders, analytics.fact_orders)

Celiq validates each mapping by introspecting the warehouse and comparing the physical table's columns against the dataset's column definitions. It computes a compatibility score (0–100%) so you can see immediately if schema drift has occurred.

Learn more about Dataset Mappings →

A complete example

Suppose you have an orders dataset with columns: id, customer_id, created_at, revenue.

Deployment	Connection	Physical table	Compatibility
Production	Snowflake (prod)	`PUBLIC.ORDERS`	100%
Development	DuckDB (dev)	`dev.orders`	100%
Staging	Postgres (staging)	`analytics.orders_staging`	92% (2 columns missing)

The semantic model node references orders — not any specific physical table. At query time, Celiq resolves the mapping for the active deployment and generates SQL against the correct table.

Relationship to the semantic model

Nodes in CML reference datasets by name. Example:

cml

node: orders
  dataset: orders        # references the logical dataset, not a table
  dimensions:
    - name: created_at
      type: time
  measures:
    - name: total_revenue
      type: sum
      sql: revenue

When Discover runs a query, it resolves:

Which deployment is active
Which physical table the orders dataset maps to in that deployment
Which connection to use

This resolution happens at query time — not at model-save time — so you can change a mapping without touching any CML.

What happens when mappings are missing

If a dataset has no mapping for the active deployment, Celiq falls back to the dataset's primary_connection_id (the connection used when the dataset was first created) and queries the original table directly.

If no fallback is available, queries against nodes using that dataset will fail with a DATASET_NOT_MAPPED error in Discover.

Datasets — define logical table schemas
Deployments — manage target environments
Dataset Mappings — wire datasets to physical tables
Connections — warehouse connection settings
CML Reference — the dataset: field in node definitions