> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic layer

> Shared names and definitions for metrics, dimensions, filters, and warehouse queries.

The semantic layer gives warehouse data a shared business vocabulary. A stored
model maps names such as `account_count`, `segment`, and `active_accounts` to
physical tables, expressions, and filters. Queries can use those names instead
of constructing the definitions again for each question.

This is useful when several people, agents, or Plays need the same meaning for
a metric. A pipeline report and a qualification analysis can use the same
reviewed definition of an active account, even when they group the result differently.

## The model and the data

A semantic model describes data. The warehouse holds the actual records.
Deepline stores the model's YAML for the workspace and connector. A semantic
query reads that saved model, compiles the selected definitions to SQL, and
executes the query through the warehouse connection.

| Model element | Meaning | Example |
| - | - | - |
| Logical table | A named view of a physical table | `accounts` refers to `RAW.CRM.ACCOUNTS` |
| Dimension | A value used to select or group records | Account segment |
| Fact | A named record-level value available to queries | An amount stored on a record |
| Metric | A named aggregate expression | Account count |
| Filter | A named condition | Active accounts only |
| Relationship | A declared join path between logical tables | Account ID connects accounts to opportunities |

For example, a model can define `account_count` as `COUNT(*)` and
`active_accounts` as `IS_ACTIVE = TRUE`. A query selecting the count, the segment
dimension, and that filter produces active-account counts by segment.
The physical names in this example are illustrative, not built-in Deepline tables.

Named filters apply when selected. A table's base filter applies automatically.
Declared relationships allow the renderer to plan joins for referenced tables.
The model's identities and relationship rules therefore affect the population
being measured, not just the names shown in a result.

## Supported warehouse connectors

Snowflake, Redshift, and Databricks expose tools to read a stored semantic model,
update it, and run semantic queries. Their connection credentials provide access
to your warehouse. The model does not grant additional database permissions.

Standard models support metric queries with dimensions and filters. Supported
funnel queries describe event steps and count conversions using identity and
time rules. A funnel's ordering and time window change what qualifies as a conversion.

Databricks can also preview or import a Unity Catalog Metric View. Queries of
an imported Metric View use its measures and dimensions directly. This route
does not support every standard-model feature, including funnels, facts, or
custom filter expressions. Parameterized Metric Views are not supported by
the import route.

The [semantic-layer reference](https://deepline.com/docs/semantic-layer-reference.md) explains Snowflake
and Redshift behavior. The [Databricks query contract](https://deepline.com/docs/providers/databricks/actions/run-semantic-query.md)
and [Metric View import contract](https://deepline.com/docs/providers/databricks/actions/import-metric-view.md)
describe the Databricks-specific behavior.

## Definitions and query results

A semantic query returns the rendered SQL with its rows and metadata. This
makes the business selection traceable to the warehouse query that produced it.
The result can answer an analytics question directly or supply records for a Play.

For example, an agent can ask for account counts by segment, inspect the
rendered SQL, and compare those totals with a known warehouse report. Another
Play can use a selected account population as input to research or enrichment.
The semantic layer supplies the selection's meaning. The Play supplies the
subsequent work.

A model's data types, identities, and uniqueness declarations express intended
meaning. They do not repair warehouse records or prove that a field is unique.
Checking definitions against known data remains part of establishing a reliable metric.

## Model changes and access

Updating the stored YAML changes the definitions used by later semantic queries.
Keeping reviewed definitions and meaningful names helps downstream queries
remain understandable as the source schema changes.

Read and query operations require workspace access and the relevant warehouse
permissions. Redshift and Databricks model updates require a workspace owner
or admin. The current Snowflake model update uses workspace membership.
Connection management still requires an owner or admin.

Validation differs by connector. Snowflake's model update checks YAML and table
references. Redshift and Databricks also validate through the semantic renderer.
A successful validation does not establish that warehouse objects exist or that
a metric measures the intended business outcome.

[Define warehouse metrics](https://deepline.com/docs/semantic-layer.md) shows a small model, its saved
configuration, and a comparison against direct SQL. [Integrations](https://deepline.com/docs/features/integrations.md)
explains warehouse connections, and [Database](https://deepline.com/docs/data-lifecycle.md) explains how
external warehouse data differs from the workspace Database.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.