Connectors move fields, not definitions
Ad platforms, analytics tools, CRMs, commerce systems, and payment processors each expose their own naming and reporting assumptions. A semantic layer maps those fields into canonical business concepts.
Raw data problem
Why raw marketing ETL is not enough
Connector data is necessary, but raw tables rarely contain the business contract a team needs. The same field name can carry different attribution windows, currencies, date bases, entity IDs, and aggregation behavior.
Dashboards amplify ambiguity
A dashboard can show a clean number while hiding whether revenue is gross or net, whether spend includes fees, or whether ROAS came from platform attribution or blended business totals.
Exports need the same rules
BI tools, spreadsheets, warehouse tables, and AI-assisted analysis should receive governed datasets, not direct access to arbitrary source tables and unsafe joins.
Canonical model
The entities, grains, and dimensions to define
The semantic layer should say what each row represents, which entity owns it, and which dimensions can safely filter or group it.
Canonical entities
Stable business objects that reporting can reference across sources.
ExamplesAd account, campaign, ad group, ad, creative, landing page, order, order line, customer, SKU, subscription, and cohort.
PurposePrevents every source from becoming its own reporting universe.
PitfallJoining entities by display names instead of stable source IDs or governed mappings.
Fact grain
The exact level at which each row is true.
ExamplesCampaign-day, ad-day, landing-page-session, order, order-line, customer-day, and cohort-month.
PurposeDetermines which metrics can be summed, joined, filtered, or compared.
PitfallJoining campaign spend directly to order lines and multiplying spend across products.
Dimensions
Attributes used to filter, group, segment, or label metrics.
ExamplesDate, channel, campaign, device, country, product category, customer type, and order status.
PurposeMakes segmentation predictable and prevents unsupported breakdowns.
PitfallAllowing any dimension to group any metric even when the source grain does not support it.
Date semantics
Rules for which date a metric uses and what reporting period means.
ExamplesSpend date, click date, session date, order date, refund date, shipment date, and cohort start date.
PurposeExplains why the same business event can appear in different periods.
PitfallComparing ad spend by spend date to profit adjusted by later refund dates without labeling the basis.
Currency semantics
Rules for source currency, reporting currency, exchange rates, and mixed-currency aggregation.
ExamplesOriginal currency amount, normalized amount, exchange-rate date, and reporting currency.
PurposeKeeps spend, revenue, and profit comparable across accounts and stores.
PitfallSumming USD, EUR, and GBP fields because they share the same column name.
Scope and ownership
Rules for tenant, subscription, account, store, and workspace boundaries.
ExamplesSubscription ID, connected account ID, platform account ID, property ID, shop ID, and destination export scope.
PurposePrevents cross-account leakage and keeps exports aligned to authorized data.
PitfallTrusting frontend-selected table names or account identifiers as authority.
Metric semantics
Metrics need aggregation rules, not only formulas
A formula is only one part of a metric definition. The semantic layer should also declare whether a metric is additive, derived, unique, attributed, modeled, or safe only at a specific grain.
Additive metrics
Metrics that can be summed across compatible rows.
ExamplesSpend, impressions, clicks, orders, net sales, COGS, gross profit, and contribution profit.
RuleAdditive only when the grain, date basis, currency, and source definition are compatible.
RelatedMarketing metrics glossary
Ratio metrics
Metrics calculated from a numerator and denominator.
ExamplesCTR, CPC, CPM, conversion rate, ROAS, MER, AOV, gross margin, and contribution margin.
RuleAggregate by summing the numerator and denominator, then recomputing the ratio.
RelatedROAS vs. MER guide
Unique counts
Metrics that count distinct people, customers, sessions, or reached users.
ExamplesReach, users, new customers, active customers, and retained customers.
RuleDo not sum across dates, campaigns, stores, or identity spaces unless deduplication is defined.
PitfallSumming daily users to create monthly users.
Attributed metrics
Metrics assigned to channels, campaigns, or touchpoints by an attribution rule.
ExamplesAttributed revenue, attributed conversions, platform ROAS, and attributed new-customer value.
RuleLabel the attribution source, model, lookback window, event basis, and conversion definition.
PitfallTreating platform-attributed revenue as a universal business truth.
Profit metrics
Metrics that subtract selected costs from revenue.
ExamplesGross profit, order profit, order-line profit, contribution profit, and profit LTV.
RuleDeclare included costs, cost allocation rules, date basis, and whether the metric is observed or modeled.
RelatedEcommerce profit glossary
Modeled metrics
Metrics that require assumptions, forecasts, or statistical methods.
ExamplesForecasted demand, modeled LTV, stockout cost, incrementality estimates, and media mix modeling outputs.
RuleKeep modeled outputs labeled with assumptions and confidence, and separate them from observed source facts.
PitfallPresenting modeled estimates as if they were observed transactions.
Guardrails
How a semantic layer keeps analysis query-safe
Guardrails make governed data useful outside the app. They prevent unsafe field combinations, ambiguous metrics, incorrect aggregation, and source-specific assumptions from leaking into exports.
Compatible field checks
Only allow dimensions and metrics together when the source grain supports the combination. Campaign spend can be grouped by campaign and date; order-line profit needs order-line or product-compatible dimensions.
Ratio recomputation
Store numerators and denominators so ROAS, MER, CTR, CAC, AOV, and margin can be recomputed at the requested grain instead of averaged from precomputed rows.
Declared caveats
Expose attribution window, currency behavior, date basis, modeled status, and cost inclusion rules near the metric so downstream users know what the number can and cannot answer.
FAQ
Semantic layer questions
Most semantic-layer problems come from letting raw source fields behave like governed business metrics.
What is a marketing semantic layer?
It is a governed business layer that defines marketing entities, grains, dimensions, metrics, aggregation rules, currency behavior, date semantics, and query guardrails across connector data.
How is it different from marketing ETL?
ETL moves and transforms data. A semantic layer defines what that data means, which fields can be combined, and how metrics should aggregate in dashboards and exports.
Why does grain matter so much?
Grain determines what a row represents. If campaign-day spend is joined to order-line revenue without a governed bridge, spend can be duplicated and profitability can be distorted.
Should attribution metrics be in the semantic layer?
They can be included when the attribution source, conversion definition, lookback window, and limitations are explicit. They should not be mixed with observed revenue without labeling.
Can a semantic layer support BI exports?
Yes. The safest exports are governed datasets with approved dimensions, metrics, filters, date ranges, and aggregation rules, not arbitrary raw source tables.
Which metrics should be guarded first?
Start with ratios, unique counts, attributed revenue, CAC, LTV, margin, and profit metrics because they are the easiest to misaggregate or compare incorrectly.
Continue with metric-specific guides
Read the ROAS vs. MER guide for marketing efficiency denominators, or the contribution margin guide for ecommerce cost rules and profit grain.