Skip to main content
The Semantic Layer is toorow’s central data modeling boundary. It transforms raw ingestion landings into unified, standardized business indicators available to AI agents and the Admin Console.

​
1. Canonical Daily Fact Surface (fact_daily_kpi)

fact_daily_kpi is the canonical daily fact table. All additive daily marketing metrics across GA4, Meta Ads, Search Console, TikTok, LinkedIn, Shopify, Stripe, and Mailgun are harmonized into this single model.

​
Stored Additive Metrics

Only additive measures are stored directly in fact_daily_kpi:
  • impressions: Total ad or search impressions.
  • clicks: Total click events.
  • spend: Total advertising cost (harmonized to project currency).
  • conversions: Total conversion events.
  • revenue: Total financial revenue.

​
2. Non-Additive & Ratio Metrics (dbt Semantic Views)

Non-additive metrics (ratios, percentages, averages) are never stored directly in fact_daily_kpi (AD-4 invariant). Summing non-additive metrics produces false, misleading figures. Instead, ratios are calculated on-the-fly via dbt semantic views using exact numerators and denominators:

​
3. Read-Through Cache (DuckDB)

To deliver low-latency responses (~50ms) to AI agents without incurring repetitive BigQuery query costs, toorow includes an optional DuckDB read-through cache:
  • Activation: Enabled via TOOROW_CACHE_ENABLED=true in .env.
  • Ephemeral Snapshot: Caches a rolling window of recent marts (default 30 days) filtered strictly by project_id.
  • Automatic Rebuild: Rebuilt automatically following nightly ingestion runs or on-demand via administration APIs.

​
Next Steps & Cross-References

Anomaly Detection

Explore how semantic marts feed baseline anomaly tracking.

Agentic Daily Insights

Learn how AI agents query semantic marts for morning briefings.

Environment Reference

Configure TOOROW_CACHE_ENABLED and cache window parameters.

Adding a Connector

Map new source fields to canonical semantic targets.