Skip to content

Semantic Layer

The semantic layer is the structured model that sits between your raw data and the documents Motley generates. It tells Motley (and your AI agent) how to interpret your data: which tables matter, what your key metrics are, how dimensions relate to measures, and which filters should always apply.

When you connect a data source, Motley automatically generates a semantic layer from the ingested schema. You can refine it through conversation with an agent, or manage it directly in the Motley interface.

A well-configured semantic layer is the highest-leverage step for improving document quality. An agent working from a well-defined semantic layer produces accurate, consistent results without needing schema context explained each time.

Building blocks

Models: named, structured views that define what's available for querying. Documents query models, not raw tables. A model is based on either a database table or a custom SQL query and exposes a set of dimensions and measures.

Dimensions: the attributes you group the data by, like date, region, product category or a customer segment. Each dimension maps to a column or SQL expression in the underlying data.

Measures: the numeric values you aggregate: revenue, order count, conversion rate. Each measure defines an aggregation type (e.g. sum, count, avg, etc.) and the column or expression to apply it to.

Default Filters: filters that apply automatically to every query against this source. You can use it to exclude test records, filter by funnel status or restrict to a business unit before any document-specific filtering.

Setting up your semantic layer